APIAPI Reference

API Reference

Explore every publishing API endpoint, field, and response.

Use this reference to inspect request fields, response shapes, and ready-to-run examples for every v2 endpoint.

Base URL

https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi

Authentication

Authorization: Bearer $API_KEY

Download OpenAPI

Content-tagging workflow#

Create a reusable tag once, then assign its returned contentGroupId when creating or updating a post. Tags are optional internal metadata and never alter the social post.

Tagging is optional. A post can have up to 10 explicit tag or template reporting groups.
Use the stable contentGroupId returned when a tag is created, not its display name or bare tagId.
contentGroupIds is a replacement list: resend the complete desired list to add or remove one tag, or send [] to remove all explicit tags.
Tag assignments can be changed before or after a post is published. Other post fields still follow normal editability rules.
A template:<id> group inherited from the template used to create a post is provenance and remains visible even when explicit tags are cleared.

# Create a tag. Save contentGroupId from the response.
POST /v2/content-tags
{ "name": "Launch", "color": "blue" }
→ { "tagId": "abc123", "contentGroupId": "tag:abc123", ... }

# Assign tags while creating a post.
POST /v2/posts
{ "media": ["UPLOAD_ID"], "accountIds": ["ACCOUNT_ID"], "contentGroupIds": ["tag:abc123"] }

# Replace the complete explicit tag list before or after publishing.
PATCH /v2/posts/POST_ID
{ "contentGroupIds": ["tag:abc123", "tag:def456"] }

# Remove every explicit tag.
PATCH /v2/posts/POST_ID
{ "contentGroupIds": [] }

Uploads#

POST

/v2/uploads

Create an upload

Videos must be MP4 or MOV with H.264 or HEVC (H.265) video and AAC audio when present, no larger than 120 MB or 3 minutes, up to 1080 × 1920 and 60 fps. Supported uploads are stored without transcoding.

Request body

Option 1

kindenum: video | imagerequired

filenamestringrequiredmin length 1 · max length 255

For video uploads, the filename must use the .mp4 or .mov extension.

contentTypestringrequiredmin length 1 · max length 100

For video uploads, use video/mp4 for MP4 or video/quicktime for MOV.

sizeBytesintegerrequiredmin > 0

Video uploads may be at most 125,829,120 bytes (120 MiB); images may be at most 52,428,800 bytes (50 MiB).

Option 2

kindenum: video | imagerequired

sourceUrlstringrequiredformat: uri

filenamestringmin length 1 · max length 255

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/uploads" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "video",
  "filename": "video.mp4",
  "contentType": "video/mp4",
  "sizeBytes": 0
}'

201 response

{
  "uploadId": "abc123",
  "uploadUrl": "https://example.com/media",
  "expiresAt": "2026-07-15T12:00:00Z"
}

Responses

201Success

400Error

401Error

403Error

413Error

415Error

422Error

429Error

POST

/v2/uploads/{uploadId}/complete

Complete a signed upload

Validates uploaded video container, codecs, size, duration, dimensions, and frame rate before marking it ready.

Parameters

Name	In	Required	Type
`uploadId`	path	required	string

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/uploads/UPLOAD_ID/complete" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "uploadId": "abc123",
  "status": "ready"
}

Responses

200Success

409Error

413Error

415Error

422Error

GET

/v2/uploads/{uploadId}

Get upload status

Parameters

Name	In	Required	Type
`uploadId`	path	required	string

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/uploads/UPLOAD_ID" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "uploadId": "abc123",
  "kind": "video",
  "status": "pending",
  "url": "https://example.com/media",
  "thumbnailUrl": "https://example.com/media",
  "error": "string"
}

Responses

200Success

404Error

Posts#

POST

/v2/posts

Create and queue a post

Optionally assign up to 10 tags or template reporting groups with contentGroupIds. Tags are for internal analytics and do not appear in the social caption.

Parameters

Name	In	Required	Type
`Idempotency-Key`	header	optional	string

Request body

mediaarray<string>requiredmin items 1 · max items 10

accountIdsarray<string>requiredmin items 1 · max items 50

skipApprovalboolean

When true, send the post directly to the posting queue instead of waiting for dashboard approval.

captionstringmax length 2200

hashtagsarray<string>max items 30

soundobject

modeenum: trending | original | specificrequired

urlstringformat: uri

urlsByPlatformobject

tiktokstringformat: uri

instagramstringformat: uri

notesstringmax length 2000

priorityintegermin 0

contentGroupIdsarray<string>max items 10

Optional tag or template reporting-group IDs. Use the contentGroupId returned by POST /v2/content-tags. Multiple groups are allowed; omit this field for no explicit tags.

instagramPostFormatenum: reel | post

How Instagram should publish the media. Regular posts require a company capability; Reels are the default.

slidesarray<object>min items 2 · max items 10

imagestringrequiredmin length 1 · max length 200

textElementsarray<object>requiredmax items 6

contentstringrequiredmin length 1 · max length 500

styleobjectrequired

textColorenum: white | black | red | yellow | blue

fontSizenumbermin 6 · max 72

fontWeightenum: normal | bold

textAlignenum: left | center | right

textModeenum: stroke | background | plain | snapchat

positionXnumbermin 0 · max 100

positionYnumberrequiredmin 0 · max 100

widthnumbermin 20 · max 100

paddingnumbermin 0 · max 20

imageFitenum: fit | fill

roleenum: hook | middle | cta

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/posts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "media": [
    "string"
  ],
  "accountIds": [
    "abc123"
  ]
}'

201 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 0,
    "thumbnailUrl": "https://example.com/media"
  },
  "caption": "A new post from HumanPost",
  "hashtags": [
    "string"
  ],
  "sound": {
    "mode": "trending",
    "url": "https://example.com/media",
    "urlsByPlatform": {
      "tiktok": "https://example.com/media",
      "instagram": "https://example.com/media"
    }
  },
  "notes": "string",
  "contentGroupIds": [
    "abc123"
  ],
  "instagramPostFormat": "reel",
  "createdAt": "2026-07-15T12:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "queuedAt": "2026-07-15T12:00:00Z",
      "approvedAt": "2026-07-15T12:00:00Z",
      "scheduledAfter": "2026-07-15T12:00:00Z",
      "scheduledSlotStart": "2026-07-15T12:00:00Z",
      "postedAt": "2026-07-15T12:00:00Z",
      "postUrl": "https://example.com/media"
    }
  ]
}

Responses

200Idempotent replay

201Post created

400Error

409Error

429Error

GET

/v2/posts

List posts

Optionally filter by one tag or template reporting group with contentGroupId, or use `untagged` to return posts with no attribution.

Parameters

Name	In	Required	Type
`limit`	query	optional	integer
`cursor`	query	optional	string
`accountId`	query	optional	string
`status`	query	optional	enum: draft \| pending_approval \| queued \| posting \| posted \| partially_posted \| cancelled \| processing \| failed
`since`	query	optional	string
`contentGroupId` Return only posts attributed to this tag or template reporting group. Use `untagged` for posts with no tag or template attribution.	query	optional	string or enum: untagged

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/posts" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "data": [
    {
      "postId": "abc123",
      "status": "draft",
      "media": {
        "kind": "video",
        "count": 0,
        "thumbnailUrl": "https://example.com/media"
      },
      "caption": "A new post from HumanPost",
      "hashtags": [
        "string"
      ],
      "sound": {
        "mode": "trending",
        "url": "https://example.com/media",
        "urlsByPlatform": {
          "tiktok": "https://example.com/media",
          "instagram": "https://example.com/media"
        }
      },
      "notes": "string",
      "contentGroupIds": [
        "abc123"
      ],
      "instagramPostFormat": "reel",
      "createdAt": "2026-07-15T12:00:00Z",
      "accounts": [
        {
          "accountId": "abc123",
          "username": "humanpost",
          "platform": "tiktok",
          "status": "draft",
          "queuedAt": "2026-07-15T12:00:00Z",
          "approvedAt": "2026-07-15T12:00:00Z",
          "scheduledAfter": "2026-07-15T12:00:00Z",
          "scheduledSlotStart": "2026-07-15T12:00:00Z",
          "postedAt": "2026-07-15T12:00:00Z",
          "postUrl": "https://example.com/media"
        }
      ]
    }
  ],
  "nextCursor": "cursor_abc123"
}

Responses

200Success

POST

/v2/posts/{postId}/queue

Queue an existing draft post

Adds one queue item per requested account to an existing post whose media is ready.

Parameters

Name	In	Required	Type
`postId`	path	required	string
`Idempotency-Key`	header	optional	string

Request body

accountIdsarray<string>requiredmin items 1 · max items 50

skipApprovalboolean

When true, send the post directly to the posting queue instead of waiting for dashboard approval.

captionstringmax length 2200

hashtagsarray<string>max items 30

soundobject

modeenum: trending | original | specificrequired

urlstringformat: uri

urlsByPlatformobject

tiktokstringformat: uri

instagramstringformat: uri

notesstringmax length 2000

priorityintegermin 0

instagramPostFormatenum: reel | post

How Instagram should publish the media. Regular posts require a company capability; Reels are the default.

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/posts/POST_ID/queue" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accountIds": [
    "abc123"
  ]
}'

201 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 0,
    "thumbnailUrl": "https://example.com/media"
  },
  "caption": "A new post from HumanPost",
  "hashtags": [
    "string"
  ],
  "sound": {
    "mode": "trending",
    "url": "https://example.com/media",
    "urlsByPlatform": {
      "tiktok": "https://example.com/media",
      "instagram": "https://example.com/media"
    }
  },
  "notes": "string",
  "contentGroupIds": [
    "abc123"
  ],
  "instagramPostFormat": "reel",
  "createdAt": "2026-07-15T12:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "queuedAt": "2026-07-15T12:00:00Z",
      "approvedAt": "2026-07-15T12:00:00Z",
      "scheduledAfter": "2026-07-15T12:00:00Z",
      "scheduledSlotStart": "2026-07-15T12:00:00Z",
      "postedAt": "2026-07-15T12:00:00Z",
      "postUrl": "https://example.com/media"
    }
  ]
}

Responses

200Idempotent replay

201Post queued

400Error

404Error

409Conflict (`media_not_ready`, `duplicate_queue_item`, or post already published)

429Error

GET

/v2/posts/{postId}

Get a post

Parameters

Name	In	Required	Type
`postId`	path	required	string

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/posts/POST_ID" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 0,
    "thumbnailUrl": "https://example.com/media"
  },
  "caption": "A new post from HumanPost",
  "hashtags": [
    "string"
  ],
  "sound": {
    "mode": "trending",
    "url": "https://example.com/media",
    "urlsByPlatform": {
      "tiktok": "https://example.com/media",
      "instagram": "https://example.com/media"
    }
  },
  "notes": "string",
  "contentGroupIds": [
    "abc123"
  ],
  "instagramPostFormat": "reel",
  "createdAt": "2026-07-15T12:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "queuedAt": "2026-07-15T12:00:00Z",
      "approvedAt": "2026-07-15T12:00:00Z",
      "scheduledAfter": "2026-07-15T12:00:00Z",
      "scheduledSlotStart": "2026-07-15T12:00:00Z",
      "postedAt": "2026-07-15T12:00:00Z",
      "postUrl": "https://example.com/media"
    }
  ]
}

Responses

200Success

404Error

PATCH

/v2/posts/{postId}

Update post metadata or content tags

contentGroupIds replaces the complete explicit assignment list and can be changed before or after publishing. Resend the desired list to add or remove individual tags; send [] to remove all explicit tags. Other metadata remains subject to normal post editability rules.

Parameters

Name	In	Required	Type
`postId`	path	required	string

Request body

captionstringmax length 2200

hashtagsarray<string>max items 30

soundobject

modeenum: trending | original | specificrequired

urlstringformat: uri

urlsByPlatformobject

tiktokstringformat: uri

instagramstringformat: uri

notesstring | nullmax length 2000

contentGroupIdsarray<string>max items 10

Replace the post's complete list of explicitly assigned tag or template reporting groups. This remains editable after publishing. To remove one tag, resend the list without it; pass [] to remove every explicit tag. Template provenance inherited from the post's original template remains visible.

instagramPostFormatenum: reel | post

How Instagram should publish the media. `post` is rejected unless the company has regular feed posts enabled.

Request

curl -X PATCH \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/posts/POST_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contentGroupIds": [
    "tag:abc123",
    "tag:def456"
  ]
}'

200 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 0,
    "thumbnailUrl": "https://example.com/media"
  },
  "caption": "A new post from HumanPost",
  "hashtags": [
    "string"
  ],
  "sound": {
    "mode": "trending",
    "url": "https://example.com/media",
    "urlsByPlatform": {
      "tiktok": "https://example.com/media",
      "instagram": "https://example.com/media"
    }
  },
  "notes": "string",
  "contentGroupIds": [
    "abc123"
  ],
  "instagramPostFormat": "reel",
  "createdAt": "2026-07-15T12:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "queuedAt": "2026-07-15T12:00:00Z",
      "approvedAt": "2026-07-15T12:00:00Z",
      "scheduledAfter": "2026-07-15T12:00:00Z",
      "scheduledSlotStart": "2026-07-15T12:00:00Z",
      "postedAt": "2026-07-15T12:00:00Z",
      "postUrl": "https://example.com/media"
    }
  ]
}

Responses

200Success

409Error

DELETE

/v2/posts/{postId}

Cancel a post

Parameters

Name	In	Required	Type
`postId`	path	required	string
`accountId`	query	optional	string

Request

curl -X DELETE \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/posts/POST_ID" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 0,
    "thumbnailUrl": "https://example.com/media"
  },
  "caption": "A new post from HumanPost",
  "hashtags": [
    "string"
  ],
  "sound": {
    "mode": "trending",
    "url": "https://example.com/media",
    "urlsByPlatform": {
      "tiktok": "https://example.com/media",
      "instagram": "https://example.com/media"
    }
  },
  "notes": "string",
  "contentGroupIds": [
    "abc123"
  ],
  "instagramPostFormat": "reel",
  "createdAt": "2026-07-15T12:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "queuedAt": "2026-07-15T12:00:00Z",
      "approvedAt": "2026-07-15T12:00:00Z",
      "scheduledAfter": "2026-07-15T12:00:00Z",
      "scheduledSlotStart": "2026-07-15T12:00:00Z",
      "postedAt": "2026-07-15T12:00:00Z",
      "postUrl": "https://example.com/media"
    }
  ],
  "cancellation": {
    "cancelled": [
      "string"
    ],
    "skipped": [
      {
        "accountId": "abc123",
        "reason": "currently_posting"
      }
    ]
  }
}

Responses

200Success

409Error

GET

/v2/posts/{postId}/analytics

Get post analytics

Parameters

Name	In	Required	Type
`postId`	path	required	string
`limit`	query	optional	integer
`cursor`	query	optional	string

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/posts/POST_ID/analytics" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "summary": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "saves": 0,
    "engagementRate": 0,
    "lastUpdated": "2026-07-15T12:00:00Z",
    "postUrl": "https://example.com/media",
    "accountId": "abc123",
    "platform": "tiktok"
  },
  "history": [
    {
      "id": "abc123",
      "videoId": "abc123",
      "accountId": "abc123",
      "platform": "tiktok",
      "postUrl": "https://example.com/media",
      "views": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0,
      "saves": 0,
      "collectedAt": "2026-07-15T12:00:00Z",
      "taskId": "abc123"
    }
  ],
  "nextCursor": "cursor_abc123"
}

Responses

200Success

Content tags#

GET

/v2/content-tags

List content tags

Returns active and archived custom tags with the stable contentGroupId value used when creating, updating, or filtering posts.

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/content-tags" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "data": [
    {
      "tagId": "abc123",
      "contentGroupId": "abc123",
      "name": "string",
      "color": "slate",
      "archived": true,
      "createdAt": "2026-07-15T12:00:00Z",
      "updatedAt": "2026-07-15T12:00:00Z"
    }
  ]
}

Responses

200Success

POST

/v2/content-tags

Create a content tag

Creates an optional company-scoped analytics tag. Use the returned contentGroupId in a post's contentGroupIds array.

Request body

namestringrequiredmin length 1 · max length 50

Unique tag name within the API key's company.

Dashboard display color. Defaults to slate.

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/content-tags" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'

201 response

{
  "tagId": "abc123",
  "contentGroupId": "abc123",
  "name": "string",
  "color": "slate",
  "archived": true,
  "createdAt": "2026-07-15T12:00:00Z",
  "updatedAt": "2026-07-15T12:00:00Z"
}

Responses

201Success

409Error

PATCH

/v2/content-tags/{tagId}

Update or archive a content tag

Rename or recolor a tag, archive it to prevent new assignments, or restore it with archived: false. Archiving preserves existing post attribution and analytics.

Parameters

Name	In	Required	Type
`tagId`	path	required	string

Request body

namestringmin length 1 · max length 50

New unique tag name.

New dashboard display color.

archivedboolean

Set true to hide the tag from new assignments without changing historical attribution; set false to restore it.

Request

curl -X PATCH \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/content-tags/TAG_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'

200 response

{
  "tagId": "abc123",
  "contentGroupId": "abc123",
  "name": "string",
  "color": "slate",
  "archived": true,
  "createdAt": "2026-07-15T12:00:00Z",
  "updatedAt": "2026-07-15T12:00:00Z"
}

Responses

200Success

404Error

409Error

DELETE

/v2/content-tags/{tagId}

Delete a content tag

Permanently deletes the tag and removes it from all posts in the company. Prefer archiving for historical continuity.

Parameters

Name	In	Required	Type
`tagId`	path	required	string

Request

curl -X DELETE \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/content-tags/TAG_ID" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "tagId": "abc123",
  "updatedPosts": 0
}

Responses

200Success

404Error

Accounts#

GET

/v2/accounts

List publishing accounts

Parameters

Name	In	Required	Type
`platform`	query	optional	enum: tiktok \| instagram

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/accounts" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "data": [
    {
      "accountId": "abc123",
      "platform": "tiktok",
      "username": "humanpost",
      "displayName": "string",
      "status": "string",
      "timezone": "string",
      "followers": 0,
      "postsToday": 0,
      "dailyCap": 0,
      "queueDepth": 0,
      "nextWindow": "2026-07-15T12:00:00Z",
      "lastPostAt": "2026-07-15T12:00:00Z"
    }
  ]
}

Responses

200Success

POST

/v2/accounts

Create a publishing account

Request body

platformenum: tiktok | instagramrequired

usernamestringrequired

displayNamestringrequiredmin length 1 · max length 80

biostringrequiredmin length 1 · max length 220

profilePictureUrlstringrequiredformat: uri · max length 2048

bioUrlstringformat: uri · max length 2048

warmupobjectrequired

searchTermsarray<string>requiredmin items 1 · max items 20

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/accounts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "tiktok",
  "username": "humanpost",
  "displayName": "string",
  "bio": "string",
  "profilePictureUrl": "https://example.com/media",
  "warmup": {
    "searchTerms": [
      "string"
    ]
  }
}'

201 response

{
  "accountId": "abc123",
  "platform": "tiktok",
  "username": "humanpost",
  "displayName": "string",
  "status": "string",
  "timezone": "string",
  "followers": 0,
  "postsToday": 0,
  "dailyCap": 0,
  "queueDepth": 0,
  "nextWindow": "2026-07-15T12:00:00Z",
  "lastPostAt": "2026-07-15T12:00:00Z"
}

Responses

201Success

403Error

409Error

429Error

GET

/v2/accounts/{accountId}

Get a publishing account

Parameters

Name	In	Required	Type
`accountId`	path	required	string

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/accounts/ACCOUNT_ID" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "accountId": "abc123",
  "platform": "tiktok",
  "username": "humanpost",
  "displayName": "string",
  "status": "string",
  "timezone": "string",
  "followers": 0,
  "postsToday": 0,
  "dailyCap": 0,
  "queueDepth": 0,
  "nextWindow": "2026-07-15T12:00:00Z",
  "lastPostAt": "2026-07-15T12:00:00Z"
}

Responses

200Success

404Error

GET

/v2/accounts/{accountId}/queue

Get an account queue

Parameters

Name	In	Required	Type
`accountId`	path	required	string
`limit`	query	optional	integer
`cursor`	query	optional	string

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/accounts/ACCOUNT_ID/queue" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "data": [
    {
      "postId": "abc123",
      "queueItemId": "abc123",
      "status": "draft",
      "caption": "A new post from HumanPost",
      "thumbnailUrl": "https://example.com/media",
      "queuedAt": "2026-07-15T12:00:00Z",
      "scheduledAfter": "2026-07-15T12:00:00Z",
      "scheduledSlotStart": "2026-07-15T12:00:00Z"
    }
  ],
  "nextCursor": "cursor_abc123"
}

Responses

200Success

GET

/v2/accounts/{accountId}/analytics

Get account analytics

Parameters

Name	In	Required	Type
`accountId`	path	required	string

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/accounts/ACCOUNT_ID/analytics" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "accountId": "abc123",
  "followers": 0,
  "posts": 0,
  "engagement": 0,
  "analytics": {
    "views": 0,
    "likes": 0,
    "comments": 0
  },
  "scannedPosts": 0
}

Responses

200Success

Workspace#

GET

/v2/workspace

Read a company workspace

Returns only the company bound to the API key, its connected accounts, and sanitized image folder and pack metadata. Requires workspace:read.

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/workspace" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "version": 1,
  "company": {
    "companyId": "abc123",
    "name": "string",
    "description": "string",
    "website": "string"
  },
  "accounts": [
    {
      "accountId": "abc123",
      "platform": "tiktok",
      "username": "humanpost",
      "displayName": "string",
      "status": "string",
      "timezone": "string",
      "followers": 0,
      "postsToday": 0,
      "dailyCap": 0,
      "queueDepth": 0,
      "nextWindow": "2026-07-15T12:00:00Z",
      "lastPostAt": "2026-07-15T12:00:00Z",
      "niche": "string",
      "warmupSearchTerms": [
        "string"
      ]
    }
  ],
  "folders": [
    {
      "folderId": "abc123",
      "name": "string",
      "createdAt": "2026-07-15T12:00:00Z",
      "images": [
        {
          "imageId": "abc123",
          "folderId": "abc123",
          "label": "string",
          "description": "string",
          "tags": [
            "string"
          ],
          "width": 0,
          "height": 0,
          "createdAt": "2026-07-15T12:00:00Z"
        }
      ],
      "packs": [
        {
          "packId": "abc123",
          "folderId": "abc123",
          "name": "string",
          "description": "string",
          "color": "string",
          "imageIds": [
            "abc123"
          ],
          "imageFit": "fit",
          "useImagesOnce": true
        }
      ]
    }
  ],
  "refreshedAt": "2026-07-15T12:00:00Z"
}

Responses

200Success

401Error

403Error

404Error

POST

/v2/workspace/media-urls

Create short-lived image download URLs

Resolves selected images through company-owned folder records before signing. Storage paths and credentials are never accepted from the caller. Requires media:read.

Request body

itemsarray<object>requiredmin items 1 · max items 100

folderIdstringrequiredmin length 1 · max length 200

imageIdstringrequiredmin length 1 · max length 200

expiresInSecondsintegermin 60 · max 3600

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/workspace/media-urls" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "folderId": "abc123",
      "imageId": "abc123"
    }
  ]
}'

200 response

{
  "expiresAt": "2026-07-15T12:00:00Z",
  "data": [
    {
      "folderId": "abc123",
      "imageId": "abc123",
      "url": "https://example.com/media"
    }
  ]
}

Responses

200Success

400Error

401Error

403Error

404Error

Usage & meta#

GET

/v2/openapi.json

OpenAPI document

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/openapi.json" \
  -H "Authorization: Bearer $API_KEY"

200 response

{}

Responses

200Success

GET

/v2/usage

Get plan and API usage

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/usage" \
  -H "Authorization: Bearer $API_KEY"

200 response

{
  "plan": "string",
  "billingType": "string",
  "videoQuota": 0,
  "videoCount": 0,
  "postCredits": {
    "limit": 0,
    "used": 0
  },
  "postsPerDay": 0,
  "apiRequestsToday": 0,
  "postsCreatedToday": 0
}

Responses

200Success