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

Uploads#

POST

/v2/uploads

Create an upload

Videos must be MP4 with H.264 video and AAC audio when present, no larger than 120 MB or 3 minutes, up to 1080 × 1920 and 60 fps.

Request body

Option 1

kindenum: video | imagerequired

filenamestringrequiredmin length 1 · max length 255

contentTypestringrequiredmin length 1 · max length 100

sizeBytesintegerrequiredmin > 0

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

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

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

scheduledAfterstringformat: date-time

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",
  "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",
      "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

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

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",
      "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",
          "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

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

scheduledAfterstringformat: date-time

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",
  "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",
      "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",
  "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",
      "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 an editable post

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

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 '{
  "caption": "A new post from HumanPost"
}'

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",
  "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",
      "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",
  "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",
      "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

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

usernamestringrequiredmin length 1 · max length 100

displayNamestringmin length 1 · max length 150

warmupobjectrequired

searchTermsarray<string>requiredmin items 1 · max items 20

instructionsstringmax length 2000

managedPostingEnabledboolean

credentialsobject

emailstringrequiredformat: email

passwordstringrequiredmin length 1 · max length 500

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",
  "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",
      "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

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