Skip to content
HumanPostAPI
ReferenceAPI 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

Updating an existing account? Follow the profile quickstart for API and CLI examples, asynchronous outcomes, and costs and frequency limits.

Upload profile photos first#

Create an image with POST /v2/uploads, PUT the file using requiredHeaders, complete the upload, then read GET /v2/uploads/{uploadId}. Pass its ready url as profilePictureUrl when creating an account. Use JPEG, PNG, or WebP up to 10 MB for profiles. Compatible direct image URLs are decoded and copied into owned assets; Drive viewer and HTML pages are rejected. The account preview and worker task use the same validated photo. The signed uploadUrl is for sending bytes.

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": [] }

Tasks#

GET

/v2/task-types

Discover task capabilities

Requires tasks:read. Optionally pass accountId to inspect eligibility. Old blank-task-capable apps support new Amplify bundles. Worker business hours and HumanPost review apply.

Parameters

NameInRequiredType
accountIdqueryoptionalstring

Request

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

200 response

{
  "data": [
    {
      "type": "comment_video",
      "platforms": [
        "string"
      ],
      "requiredPayloadFields": [
        "string"
      ],
      "creditKind": "string",
      "creditQuantity": 1,
      "evidence": "string",
      "available": true,
      "blockers": [
        "string"
      ],
      "actions": [
        "string"
      ]
    }
  ],
  "scheduling": "worker_business_hours",
  "review": "humanpost",
  "accountId": "abc123"
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
429Error
POST

/v2/tasks

Create a comment or Amplify task

Requires tasks:write and Idempotency-Key. Reserves one Comment or Amplify credit atomically. Amplify is one public task with separately reviewed Repost + Like and Comment components. Keys are company-scoped; changed payloads conflict. Worker business hours apply. No admin, worker, payout or approval overrides.

Parameters

NameInRequiredType
Idempotency-Keyheaderrequiredstring

Request body

Option 1
accountIdstringrequiredmin length 1 · max length 200
externalReferencestringmin length 1 · max length 200
typeenum: comment_videorequired
payloadobjectrequired
targetVideoUrlstringrequiredformat: uri · max length 2000
commentTextstringrequiredmin length 1 · max length 500
commentImageUrlstringformat: uri · max length 2000
allowAccountRolloverboolean
Option 2
accountIdstringrequiredmin length 1 · max length 200
externalReferencestringmin length 1 · max length 200
typeenum: amplify_videorequired
payloadobjectrequired
targetVideoUrlstringrequiredformat: uri · max length 2000
commentTextstringrequiredmin length 1 · max length 500

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/tasks" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Idempotency-Key: UNIQUE_OPERATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "ACCOUNT_ID",
  "type": "amplify_video",
  "externalReference": "partner-order-123",
  "payload": {
    "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456",
    "commentText": "hi"
  }
}'

201 response

{
  "taskId": "AMPLIFY_TASK_ID",
  "companyId": "COMPANY_ID",
  "type": "amplify_video",
  "status": "assigned",
  "accountId": "ACCOUNT_ID",
  "currentAccountId": "ACCOUNT_ID",
  "platform": "tiktok",
  "externalReference": "partner-order-123",
  "payload": {
    "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456",
    "commentText": "hi"
  },
  "createdAt": "2027-01-01T00:00:00Z",
  "updatedAt": "2027-01-01T00:00:00Z",
  "completedAt": null,
  "reason": null,
  "components": [
    {
      "taskId": "REPOST_LIKE_TASK_ID",
      "role": "repost_like",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "assigned",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    },
    {
      "taskId": "COMMENT_TASK_ID",
      "role": "comment",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "assigned",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    }
  ],
  "attempts": [
    {
      "taskId": "AMPLIFY_TASK_ID",
      "role": "attempt_1",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "assigned",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    }
  ],
  "currentAttemptId": "AMPLIFY_TASK_ID",
  "availableActions": [
    "cancel"
  ],
  "evidenceAvailable": false,
  "credit": {
    "kind": "amplify",
    "quantity": 1,
    "source": "monthly",
    "outcome": "reserved"
  },
  "historyComplete": true
}

Responses

200Idempotent replay
201Success
400Error
401Error
403Error
404Error
409Error
429Error
GET

/v2/tasks

List company tasks

Requires tasks:read. Bounds each scanned page; follow nextCursor even after an empty filtered page. Hides operational children/replacements and reports their effective outcome under the original task ID. Legacy tasks missing companyId are accessible by ID after account ownership verification, but absent from this company-indexed list.

Parameters

NameInRequiredType
limitqueryoptionalinteger
cursorqueryoptionalstring
typequeryoptionalenum: post_video | amplify_video | repost_like_video | like_video | comment_video | reply_to_comment | like_comment | follow_account | edit_bio | edit_username | edit_display_name | update_profile_pic | account_login | account_logout | account_setup | warmup_scroll | record_fyp | record_reels | intro_video | spark_code | connect_posting_service | delete_post | delete_account | blank_task
statusqueryoptionalenum: pending | assigned | in_progress | pending_approval | completed | failed | expired | cancelled | unknown
accountIdqueryoptionalstring
platformqueryoptionalenum: tiktok | instagram
externalReferencequeryoptionalstring
createdAfterqueryoptionalstring
createdBeforequeryoptionalstring

Request

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

200 response

{
  "data": [
    {
      "taskId": "AMPLIFY_TASK_ID",
      "companyId": "COMPANY_ID",
      "type": "amplify_video",
      "status": "assigned",
      "accountId": "ACCOUNT_ID",
      "currentAccountId": "ACCOUNT_ID",
      "platform": "tiktok",
      "externalReference": "partner-order-123",
      "payload": {
        "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456",
        "commentText": "hi"
      },
      "createdAt": "2027-01-01T00:00:00Z",
      "updatedAt": "2027-01-01T00:00:00Z",
      "completedAt": null,
      "reason": null,
      "components": [
        {
          "taskId": "REPOST_LIKE_TASK_ID",
          "role": "repost_like",
          "accountId": "ACCOUNT_ID",
          "username": "humanpost",
          "status": "assigned",
          "scheduledFor": null,
          "deadline": "2027-01-01T03:00:00Z",
          "startedAt": null,
          "submittedAt": null,
          "reviewedAt": null,
          "completedAt": null,
          "reason": null,
          "evidenceAvailable": false
        },
        {
          "taskId": "COMMENT_TASK_ID",
          "role": "comment",
          "accountId": "ACCOUNT_ID",
          "username": "humanpost",
          "status": "assigned",
          "scheduledFor": null,
          "deadline": "2027-01-01T03:00:00Z",
          "startedAt": null,
          "submittedAt": null,
          "reviewedAt": null,
          "completedAt": null,
          "reason": null,
          "evidenceAvailable": false
        }
      ],
      "attempts": [
        {
          "taskId": "AMPLIFY_TASK_ID",
          "role": "attempt_1",
          "accountId": "ACCOUNT_ID",
          "username": "humanpost",
          "status": "assigned",
          "scheduledFor": null,
          "deadline": "2027-01-01T03:00:00Z",
          "startedAt": null,
          "submittedAt": null,
          "reviewedAt": null,
          "completedAt": null,
          "reason": null,
          "evidenceAvailable": false
        }
      ],
      "currentAttemptId": "AMPLIFY_TASK_ID",
      "availableActions": [
        "cancel"
      ],
      "evidenceAvailable": false,
      "credit": {
        "kind": "amplify",
        "quantity": 1,
        "source": "monthly",
        "outcome": "reserved"
      },
      "historyComplete": true
    }
  ],
  "nextCursor": null
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
429Error
GET

/v2/tasks/{taskId}

Inspect task progress

Requires tasks:read. Read combined Amplify components or comment replacement attempts. Completed means approved by HumanPost, not merely submitted. Use availableActions to discover supported controls. Operational child IDs cannot be queried independently through this company interface.

Parameters

NameInRequiredType
taskIdpathrequiredstring

Request

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

200 response

{
  "taskId": "AMPLIFY_TASK_ID",
  "companyId": "COMPANY_ID",
  "type": "amplify_video",
  "status": "assigned",
  "accountId": "ACCOUNT_ID",
  "currentAccountId": "ACCOUNT_ID",
  "platform": "tiktok",
  "externalReference": "partner-order-123",
  "payload": {
    "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456",
    "commentText": "hi"
  },
  "createdAt": "2027-01-01T00:00:00Z",
  "updatedAt": "2027-01-01T00:00:00Z",
  "completedAt": null,
  "reason": null,
  "components": [
    {
      "taskId": "REPOST_LIKE_TASK_ID",
      "role": "repost_like",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "assigned",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    },
    {
      "taskId": "COMMENT_TASK_ID",
      "role": "comment",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "assigned",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    }
  ],
  "attempts": [
    {
      "taskId": "AMPLIFY_TASK_ID",
      "role": "attempt_1",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "assigned",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    }
  ],
  "currentAttemptId": "AMPLIFY_TASK_ID",
  "availableActions": [
    "cancel"
  ],
  "evidenceAvailable": false,
  "credit": {
    "kind": "amplify",
    "quantity": 1,
    "source": "monthly",
    "outcome": "reserved"
  },
  "historyComplete": true
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
429Error
GET

/v2/tasks/{taskId}/events

Read task history

Requires tasks:read. Persisted revisions arrive asynchronously and may be delivered out of order; eventId deduplicates, revision identifies the document version. historyComplete is false for legacy work. Poll without a cursor to see newer events; cursors page backward through history.

Parameters

NameInRequiredType
taskIdpathrequiredstring
limitqueryoptionalinteger
cursorqueryoptionalstring

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/tasks/TASK_ID/events" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY"

200 response

{
  "data": [
    {
      "eventId": "abc123",
      "taskId": "abc123",
      "operationalTaskId": "abc123",
      "role": "string",
      "occurredAt": "2027-01-01T00:00:00Z",
      "revision": "string",
      "kind": "created",
      "status": "pending",
      "reason": "string",
      "scheduledFor": "2027-01-01T00:00:00Z",
      "submittedAt": "2027-01-01T00:00:00Z",
      "reviewedAt": "2027-01-01T00:00:00Z",
      "creditOutcome": "string"
    }
  ],
  "nextCursor": "cursor_abc123",
  "historyComplete": true
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
429Error
GET

/v2/tasks/{taskId}/evidence

Read task screenshots

Requires tasks:evidence:read. Pages current evidence then archived Amplify proof. Follow nextCursor even after an empty page. Company-authorized screenshots use signed URLs valid for 60–3600 seconds. URLs are bearer links until expiry. Never exposes permanent Firebase download tokens or worker personal records.

Parameters

NameInRequiredType
taskIdpathrequiredstring
limitqueryoptionalinteger
cursorqueryoptionalstring
expiresInSecondsqueryoptionalinteger

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/tasks/TASK_ID/evidence" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY"

200 response

{
  "data": [
    {
      "evidenceId": "abc123",
      "taskId": "abc123",
      "operationalTaskId": "abc123",
      "role": "string",
      "url": "https://example.com/media",
      "expiresAt": "2027-01-01T00:00:00Z",
      "submittedAt": "2027-01-01T00:00:00Z",
      "reviewedAt": "2027-01-01T00:00:00Z",
      "status": "pending",
      "historical": true
    }
  ],
  "nextCursor": "cursor_abc123",
  "expiresAt": "2027-01-01T00:00:00Z"
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
429Error
POST

/v2/tasks/{taskId}/cancel

Cancel remaining task work

Requires tasks:write. Supports unfinished Comment and Amplify requests. Retains proof/history; cannot undo platform actions. Amplify refunds only when neither component was approved. Idempotent repeats do not refund twice. Old-period refunds do not replenish a new period.

Parameters

NameInRequiredType
taskIdpathrequiredstring

Request body

reasonstringrequiredmin length 1 · max length 500

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/tasks/TASK_ID/cancel" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

200 response

{
  "taskId": "AMPLIFY_TASK_ID",
  "companyId": "COMPANY_ID",
  "type": "amplify_video",
  "status": "cancelled",
  "accountId": "ACCOUNT_ID",
  "currentAccountId": "ACCOUNT_ID",
  "platform": "tiktok",
  "externalReference": "partner-order-123",
  "payload": {
    "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456",
    "commentText": "hi"
  },
  "createdAt": "2027-01-01T00:00:00Z",
  "updatedAt": "2027-01-01T00:00:00Z",
  "completedAt": null,
  "reason": "Customer cancelled",
  "components": [
    {
      "taskId": "REPOST_LIKE_TASK_ID",
      "role": "repost_like",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "cancelled",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    },
    {
      "taskId": "COMMENT_TASK_ID",
      "role": "comment",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "cancelled",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    }
  ],
  "attempts": [
    {
      "taskId": "AMPLIFY_TASK_ID",
      "role": "attempt_1",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "cancelled",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    }
  ],
  "currentAttemptId": "AMPLIFY_TASK_ID",
  "availableActions": [],
  "evidenceAvailable": false,
  "credit": {
    "kind": "amplify",
    "quantity": 1,
    "source": "monthly",
    "outcome": "refunded"
  },
  "historyComplete": true
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
429Error
POST

/v2/tasks/{taskId}/resume

Resume blocked Amplify work

Requires tasks:write. Reopens failed/expired Amplify components on the original account/worker; approved work stays completed. Worker business hours and dispatch availability apply. No new credit is charged. Standalone comments follow their existing automatic replacement policy.

Parameters

NameInRequiredType
taskIdpathrequiredstring

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/tasks/TASK_ID/resume" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY"

200 response

{
  "taskId": "AMPLIFY_TASK_ID",
  "companyId": "COMPANY_ID",
  "type": "amplify_video",
  "status": "assigned",
  "accountId": "ACCOUNT_ID",
  "currentAccountId": "ACCOUNT_ID",
  "platform": "tiktok",
  "externalReference": "partner-order-123",
  "payload": {
    "targetVideoUrl": "https://www.tiktok.com/@creator/video/123456",
    "commentText": "hi"
  },
  "createdAt": "2027-01-01T00:00:00Z",
  "updatedAt": "2027-01-01T00:00:00Z",
  "completedAt": null,
  "reason": null,
  "components": [
    {
      "taskId": "REPOST_LIKE_TASK_ID",
      "role": "repost_like",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "assigned",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    },
    {
      "taskId": "COMMENT_TASK_ID",
      "role": "comment",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "assigned",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    }
  ],
  "attempts": [
    {
      "taskId": "AMPLIFY_TASK_ID",
      "role": "attempt_1",
      "accountId": "ACCOUNT_ID",
      "username": "humanpost",
      "status": "assigned",
      "scheduledFor": null,
      "deadline": "2027-01-01T03:00:00Z",
      "startedAt": null,
      "submittedAt": null,
      "reviewedAt": null,
      "completedAt": null,
      "reason": null,
      "evidenceAvailable": false
    }
  ],
  "currentAttemptId": "AMPLIFY_TASK_ID",
  "availableActions": [
    "cancel"
  ],
  "evidenceAvailable": false,
  "credit": {
    "kind": "amplify",
    "quantity": 1,
    "source": "monthly",
    "outcome": "reserved"
  },
  "historyComplete": true
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
429Error

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 250 MB, up to 2160 × 3840 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 262,144,000 bytes (250 MiB); images may be at most 52,428,800 bytes (50 MiB).

Option 2
kindenum: video | imagerequired
sourceUrlstringrequiredformat: uri · max length 2048
filenamestringmin length 1 · max length 255

Request

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

201 response

{
  "uploadId": "abc123",
  "uploadUrl": "https://example.com/media",
  "expiresAt": "2027-01-01T00:00:00Z",
  "requiredHeaders": {
    "Content-Type": "string"
  }
}

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

NameInRequiredType
uploadIdpathrequiredstring

Request

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

200 response

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

Responses

200Success
409Error
413Error
415Error
422Error
GET

/v2/uploads/{uploadId}

Get upload status

Parameters

NameInRequiredType
uploadIdpathrequiredstring

Request

curl -X GET \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/uploads/UPLOAD_ID" \
  -H "Authorization: Bearer $HUMANPOST_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
POST

/v2/uploads/batch

Import an ordered resumable URL batch

Requires posts:write. Imports 1–100 public URLs durably; job results retain input indices and per-file failures. Poll /v2/jobs/{jobId}. Reuse a key only with identical input.

Parameters

NameInRequiredType
Idempotency-Key

Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.

headeroptionalstring

Request body

itemsarray<object>requiredmin items 1 · max items 100
kindenum: video | imagerequired
sourceUrlstringrequiredformat: uri · max length 2048
filenamestringmin length 1 · max length 255

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/uploads/batch" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Idempotency-Key: UNIQUE_OPERATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "kind": "video",
      "sourceUrl": "https://example.com/media"
    }
  ]
}'

Responses

202Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error

Drafts#

POST

/v2/drafts

Create an unqueued editable draft

Requires posts:write. Creates an unqueued draft. Optional slides retain editable text and styles; finished artwork can be used as-is. Posting billing is enforced on submission. Preview before queueing; draft creation counts once toward the post creation cap.

Parameters

NameInRequiredType
Idempotency-Key

Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.

headeroptionalstring

Request body

mediaarray<string>requiredmin items 1 · max items 20
captionstringmax length 2200
hashtagsarray<string>max items 30
soundobject
modeenum: trending | original | specificrequired
urlstringformat: uri
urlsByPlatformobject
tiktokstringformat: uri
instagramstringformat: uri
notesstringmax length 2000
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 1 · max items 20
imagestringrequiredmin length 1 · max length 200
textElementsarray<object>requiredmax items 6
contentstringrequiredmin length 1 · max length 500
styleobjectrequired
backgroundColorenum: none | black | white | red | yellow | blue
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/drafts" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Idempotency-Key: UNIQUE_OPERATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "media": [
    "string"
  ]
}'

201 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 1,
    "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": "2027-01-01T00:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "failureReason": "string",
      "queuedAt": "2027-01-01T00:00:00Z",
      "approvedAt": "2027-01-01T00:00:00Z",
      "scheduledAfter": "2027-01-01T00:00:00Z",
      "expiresAt": "2027-01-01T00:00:00Z",
      "scheduledSlotStart": "2027-01-01T00:00:00Z",
      "postedAt": "2027-01-01T00:00:00Z",
      "postUrl": "https://example.com/media"
    }
  ]
}

Responses

200Idempotent replay
201Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error
PATCH

/v2/drafts/{postId}

Edit draft artwork or metadata with version conflict protection

Requires posts:write. Edits only an unqueued draft. expectedVersionId prevents overwriting newer artwork. Replacing slides invalidates the preview; request a new preview before submission.

Parameters

NameInRequiredType
postIdpathrequiredstring

Request body

mediaarray<string>min items 1 · max items 20
captionstringmax length 2200
hashtagsarray<string>max items 30
soundobject
modeenum: trending | original | specificrequired
urlstringformat: uri
urlsByPlatformobject
tiktokstringformat: uri
instagramstringformat: uri
notesstringmax length 2000
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 1 · max items 20
imagestringrequiredmin length 1 · max length 200
textElementsarray<object>requiredmax items 6
contentstringrequiredmin length 1 · max length 500
styleobjectrequired
backgroundColorenum: none | black | white | red | yellow | blue
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
expectedVersionIdstringmin length 1 · max length 200

Reject a stale artwork edit rather than overwriting another editor's version.

Request

curl -X PATCH \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/drafts/POST_ID" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "caption": "Updated draft caption",
  "expectedVersionId": "VERSION_ID"
}'

200 response

{
  "post": {
    "postId": "abc123",
    "status": "draft",
    "media": {
      "kind": "video",
      "count": 1,
      "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": "2027-01-01T00:00:00Z",
    "accounts": [
      {
        "accountId": "abc123",
        "username": "humanpost",
        "platform": "tiktok",
        "status": "draft",
        "failureReason": "string",
        "queuedAt": "2027-01-01T00:00:00Z",
        "approvedAt": "2027-01-01T00:00:00Z",
        "scheduledAfter": "2027-01-01T00:00:00Z",
        "expiresAt": "2027-01-01T00:00:00Z",
        "scheduledSlotStart": "2027-01-01T00:00:00Z",
        "postedAt": "2027-01-01T00:00:00Z",
        "postUrl": "https://example.com/media"
      }
    ]
  },
  "versionId": "abc123",
  "media": [
    {
      "uploadId": "abc123",
      "url": "https://example.com/media"
    }
  ],
  "slides": [
    {
      "slideId": "abc123",
      "image": "string",
      "imageUrl": "https://example.com/media",
      "textElements": [
        {
          "id": "abc123",
          "content": "string",
          "style": {}
        }
      ],
      "imageFit": "fit",
      "role": "string"
    }
  ]
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error

Jobs & reports#

GET

/v2/jobs/{jobId}

Read job progress and results

Requires analytics:read for reports; posts:write for previews/imports. Poll persisted progress or read final ordered results, preview URLs, or report. Requires the job's scope and the same company.

Parameters

NameInRequiredType
jobIdpathrequiredstring

Request

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

200 response

{
  "jobId": "abc123",
  "type": "upload_batch",
  "status": "pending",
  "progress": 1,
  "total": 1,
  "createdAt": "2027-01-01T00:00:00Z",
  "updatedAt": "2027-01-01T00:00:00Z",
  "results": [
    {
      "index": 1,
      "uploadId": "abc123",
      "status": "ready",
      "error": {
        "code": "string",
        "message": "Request completed",
        "hint": "string",
        "requestId": "abc123",
        "retryable": true,
        "details": [
          {
            "field": "string",
            "message": "Request completed"
          }
        ],
        "retryAfterSeconds": 1,
        "context": {}
      }
    }
  ],
  "report": {},
  "preview": {
    "postId": "abc123",
    "versionId": "abc123",
    "status": "ready",
    "mediaUrls": [
      "https://example.com/media"
    ],
    "jobId": "abc123",
    "error": {
      "code": "string",
      "message": "Request completed",
      "hint": "string",
      "requestId": "abc123",
      "retryable": true,
      "details": [
        {
          "field": "string",
          "message": "Request completed"
        }
      ],
      "retryAfterSeconds": 1,
      "context": {}
    }
  },
  "error": {
    "code": "string",
    "message": "Request completed",
    "hint": "string",
    "requestId": "abc123",
    "retryable": true,
    "details": [
      {
        "field": "string",
        "message": "Request completed"
      }
    ],
    "retryAfterSeconds": 1,
    "context": {}
  }
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error
POST

/v2/analytics/reports

Compare UTC-day growth and rank observed destinations

Requires analytics:read. Requires ready V3 rollups. Dates must be UTC midnight: from inclusive, to exclusive, maximum 366 days; previous period has equal duration. Growth follows collection dates. Top posts use latest cumulative views for destinations whose collection spans overlap the period. Includes freshness/coverage and up to 500 groups; tag groups overlap. Poll the returned job.

Parameters

NameInRequiredType
Idempotency-Key

Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.

headeroptionalstring

Request body

fromstringrequiredformat: date-time
tostringrequiredformat: date-time
comparePreviousboolean
accountIdstringmin length 1 · max length 200
platformenum: tiktok | instagram
contentGroupIdstringmax length 240
groupByenum: account | platform | content_group | template
topLimitintegermin 1 · max 100

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/analytics/reports" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Idempotency-Key: UNIQUE_OPERATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "2027-01-01T00:00:00Z",
  "to": "2027-01-08T00:00:00Z"
}'

Responses

202Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error

Posts#

POST

/v2/posts

Create and queue a post

Submit one video or carousel to up to 100 distinct company-owned accounts, including multiple Instagram or TikTok accounts. Reuse ready upload IDs; no re-upload is needed per account. Creates one post and all per-account queue items atomically, or rejects the entire request if any target is invalid. Use one stable Idempotency-Key for the complete distribution and save the returned postId to track each account. Approval, billing and posting schedules still apply per destination. Optionally assign up to 10 internal analytics groups with contentGroupIds.

Parameters

NameInRequiredType
Idempotency-Keyheaderoptionalstring

Request body

mediaarray<string>requiredmin items 1 · max items 20
accountIdsarray<string>requiredmin items 1 · max items 100

Up to 100 distinct company-owned accounts, including multiple accounts on the same platform. Creates one queue item per account atomically.

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
scheduledAfterstringformat: date-time

Earliest release instant, expressed as ISO 8601 with a timezone offset. Actual publishing follows worker-local windows and capacity; this is not an exact posting time.

expiresAtstringformat: date-time

Stop releasing queued targets at this instant. Does not recall work already released to an operator.

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 1 · max items 20
imagestringrequiredmin length 1 · max length 200
textElementsarray<object>requiredmax items 6
contentstringrequiredmin length 1 · max length 500
styleobjectrequired
backgroundColorenum: none | black | white | red | yellow | blue
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 $HUMANPOST_API_KEY" \
  -H "Idempotency-Key: UNIQUE_OPERATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "media": [
    "string"
  ],
  "accountIds": [
    "abc123"
  ]
}'

201 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 1,
    "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": "2027-01-01T00:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "failureReason": "string",
      "queuedAt": "2027-01-01T00:00:00Z",
      "approvedAt": "2027-01-01T00:00:00Z",
      "scheduledAfter": "2027-01-01T00:00:00Z",
      "expiresAt": "2027-01-01T00:00:00Z",
      "scheduledSlotStart": "2027-01-01T00:00:00Z",
      "postedAt": "2027-01-01T00: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

NameInRequiredType
limitqueryoptionalinteger
cursorqueryoptionalstring
accountIdqueryoptionalstring
statusqueryoptionalenum: draft | pending_approval | queued | posting | posted | partially_posted | cancelled | processing | failed
sincequeryoptionalstring
contentGroupId

Return only posts attributed to this tag or template reporting group. Use `untagged` for posts with no tag or template attribution.

queryoptionalstring or enum: untagged

Request

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

200 response

{
  "data": [
    {
      "postId": "abc123",
      "status": "draft",
      "media": {
        "kind": "video",
        "count": 1,
        "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": "2027-01-01T00:00:00Z",
      "accounts": [
        {
          "accountId": "abc123",
          "username": "humanpost",
          "platform": "tiktok",
          "status": "draft",
          "failureReason": "string",
          "queuedAt": "2027-01-01T00:00:00Z",
          "approvedAt": "2027-01-01T00:00:00Z",
          "scheduledAfter": "2027-01-01T00:00:00Z",
          "expiresAt": "2027-01-01T00:00:00Z",
          "scheduledSlotStart": "2027-01-01T00:00:00Z",
          "postedAt": "2027-01-01T00:00:00Z",
          "postUrl": "https://example.com/media"
        }
      ]
    }
  ],
  "nextCursor": "cursor_abc123"
}

Responses

200Success
POST

/v2/posts/{postId}/queue

Queue an existing draft post

Atomically adds one queue item per requested account (up to 100 distinct company-owned accounts, including multiple accounts on the same platform) to an existing post whose media is ready. An account that already has an active queue item rejects the entire request. Approval, billing and posting schedules still apply per destination.

Parameters

NameInRequiredType
postIdpathrequiredstring
Idempotency-Keyheaderoptionalstring

Request body

accountIdsarray<string>requiredmin items 1 · max items 100

Up to 100 distinct company-owned accounts, including multiple accounts on the same platform. Creates one queue item per account atomically.

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
scheduledAfterstringformat: date-time

Earliest release instant, expressed as ISO 8601 with a timezone offset. Actual publishing follows worker-local windows and capacity; this is not an exact posting time.

expiresAtstringformat: date-time

Stop releasing queued targets at this instant. Does not recall work already released to an operator.

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 $HUMANPOST_API_KEY" \
  -H "Idempotency-Key: UNIQUE_OPERATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accountIds": [
    "abc123"
  ]
}'

201 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 1,
    "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": "2027-01-01T00:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "failureReason": "string",
      "queuedAt": "2027-01-01T00:00:00Z",
      "approvedAt": "2027-01-01T00:00:00Z",
      "scheduledAfter": "2027-01-01T00:00:00Z",
      "expiresAt": "2027-01-01T00:00:00Z",
      "scheduledSlotStart": "2027-01-01T00:00:00Z",
      "postedAt": "2027-01-01T00: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

NameInRequiredType
postIdpathrequiredstring

Request

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

200 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 1,
    "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": "2027-01-01T00:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "failureReason": "string",
      "queuedAt": "2027-01-01T00:00:00Z",
      "approvedAt": "2027-01-01T00:00:00Z",
      "scheduledAfter": "2027-01-01T00:00:00Z",
      "expiresAt": "2027-01-01T00:00:00Z",
      "scheduledSlotStart": "2027-01-01T00:00:00Z",
      "postedAt": "2027-01-01T00: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

NameInRequiredType
postIdpathrequiredstring

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 $HUMANPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contentGroupIds": [
    "tag:abc123",
    "tag:def456"
  ]
}'

200 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 1,
    "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": "2027-01-01T00:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "failureReason": "string",
      "queuedAt": "2027-01-01T00:00:00Z",
      "approvedAt": "2027-01-01T00:00:00Z",
      "scheduledAfter": "2027-01-01T00:00:00Z",
      "expiresAt": "2027-01-01T00:00:00Z",
      "scheduledSlotStart": "2027-01-01T00:00:00Z",
      "postedAt": "2027-01-01T00:00:00Z",
      "postUrl": "https://example.com/media"
    }
  ]
}

Responses

200Success
409Error
DELETE

/v2/posts/{postId}

Cancel a post

Parameters

NameInRequiredType
postIdpathrequiredstring
accountIdqueryoptionalstring

Request

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

200 response

{
  "postId": "abc123",
  "status": "draft",
  "media": {
    "kind": "video",
    "count": 1,
    "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": "2027-01-01T00:00:00Z",
  "accounts": [
    {
      "accountId": "abc123",
      "username": "humanpost",
      "platform": "tiktok",
      "status": "draft",
      "failureReason": "string",
      "queuedAt": "2027-01-01T00:00:00Z",
      "approvedAt": "2027-01-01T00:00:00Z",
      "scheduledAfter": "2027-01-01T00:00:00Z",
      "expiresAt": "2027-01-01T00:00:00Z",
      "scheduledSlotStart": "2027-01-01T00:00:00Z",
      "postedAt": "2027-01-01T00: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

NameInRequiredType
postIdpathrequiredstring
limitqueryoptionalinteger
cursorqueryoptionalstring

Request

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

200 response

{
  "summary": {
    "views": 1,
    "likes": 1,
    "comments": 1,
    "shares": 1,
    "saves": 1,
    "engagementRate": 1,
    "lastUpdated": "2027-01-01T00: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": 1,
      "likes": 1,
      "comments": 1,
      "shares": 1,
      "saves": 1,
      "collectedAt": "2027-01-01T00:00:00Z",
      "taskId": "abc123"
    }
  ],
  "nextCursor": "cursor_abc123"
}

Responses

200Success
GET

/v2/posts/{postId}/content

Read media, slide text, styles, and version

Requires posts:read. Returns slide text/styles, upload IDs, signed background URLs (15 minutes), and the current versionId.

Parameters

NameInRequiredType
postIdpathrequiredstring

Request

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

200 response

{
  "post": {
    "postId": "abc123",
    "status": "draft",
    "media": {
      "kind": "video",
      "count": 1,
      "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": "2027-01-01T00:00:00Z",
    "accounts": [
      {
        "accountId": "abc123",
        "username": "humanpost",
        "platform": "tiktok",
        "status": "draft",
        "failureReason": "string",
        "queuedAt": "2027-01-01T00:00:00Z",
        "approvedAt": "2027-01-01T00:00:00Z",
        "scheduledAfter": "2027-01-01T00:00:00Z",
        "expiresAt": "2027-01-01T00:00:00Z",
        "scheduledSlotStart": "2027-01-01T00:00:00Z",
        "postedAt": "2027-01-01T00:00:00Z",
        "postUrl": "https://example.com/media"
      }
    ]
  },
  "versionId": "abc123",
  "media": [
    {
      "uploadId": "abc123",
      "url": "https://example.com/media"
    }
  ],
  "slides": [
    {
      "slideId": "abc123",
      "image": "string",
      "imageUrl": "https://example.com/media",
      "textElements": [
        {
          "id": "abc123",
          "content": "string",
          "style": {}
        }
      ],
      "imageFit": "fit",
      "role": "string"
    }
  ]
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error
POST

/v2/posts/{postId}/preview

Render current draft without approving or submitting it

Requires posts:write. Reads or requests the current draft preview. Rendering is asynchronous and does not approve or queue the draft. Old renders cannot replace newer versions.

Parameters

NameInRequiredType
postIdpathrequiredstring
Idempotency-Key

Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.

headeroptionalstring

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/posts/POST_ID/preview" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Idempotency-Key: UNIQUE_OPERATION_KEY"

Responses

202Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error
GET

/v2/posts/{postId}/preview

Read current rendered preview

Requires posts:read. Reads or requests the current draft preview. Rendering is asynchronous and does not approve or queue the draft. Old renders cannot replace newer versions.

Parameters

NameInRequiredType
postIdpathrequiredstring

Request

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

200 response

{
  "postId": "abc123",
  "versionId": "abc123",
  "status": "ready",
  "mediaUrls": [
    "https://example.com/media"
  ],
  "jobId": "abc123",
  "error": {
    "code": "string",
    "message": "Request completed",
    "hint": "string",
    "requestId": "abc123",
    "retryable": true,
    "details": [
      {
        "field": "string",
        "message": "Request completed"
      }
    ],
    "retryAfterSeconds": 1,
    "context": {}
  }
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error

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 $HUMANPOST_API_KEY"

200 response

{
  "data": [
    {
      "tagId": "abc123",
      "contentGroupId": "abc123",
      "name": "string",
      "color": "slate",
      "archived": true,
      "createdAt": "2027-01-01T00:00:00Z",
      "updatedAt": "2027-01-01T00: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.

colorenum: slate | blue | cyan | green | amber | orange | rose | violet

Dashboard display color. Defaults to slate.

Request

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

201 response

{
  "tagId": "abc123",
  "contentGroupId": "abc123",
  "name": "string",
  "color": "slate",
  "archived": true,
  "createdAt": "2027-01-01T00:00:00Z",
  "updatedAt": "2027-01-01T00: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

NameInRequiredType
tagIdpathrequiredstring

Request body

namestringmin length 1 · max length 50

New unique tag name.

colorenum: slate | blue | cyan | green | amber | orange | rose | violet

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 $HUMANPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'

200 response

{
  "tagId": "abc123",
  "contentGroupId": "abc123",
  "name": "string",
  "color": "slate",
  "archived": true,
  "createdAt": "2027-01-01T00:00:00Z",
  "updatedAt": "2027-01-01T00: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

NameInRequiredType
tagIdpathrequiredstring

Request

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

200 response

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

Responses

200Success
404Error

Accounts#

GET

/v2/accounts

List publishing accounts

Requires accounts:read. Returns only the API key's company accounts. Includes stored profilePictureUrl, bio, and warmupSearchTerms. Missing picture/bio values are null; missing terms are []. Setup placeholders contain requested values; pending profile edits retain previous values until worker approval. Stored values do not independently verify the live platform profile or completed warm-up.

Parameters

NameInRequiredType
platformqueryoptionalenum: tiktok | instagram

Request

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

200 response

{
  "data": [
    {
      "accountId": "ACCOUNT_ID",
      "platform": "tiktok",
      "username": "buildmode",
      "displayName": "Build Mode",
      "profilePictureUrl": "https://cdn.example.com/build-mode.png",
      "bio": "Building practical side hustles in public.",
      "warmupSearchTerms": [
        "build in public",
        "side hustle experiments"
      ],
      "status": "settingUp",
      "timezone": "America/New_York",
      "followers": 0,
      "postsToday": 0,
      "dailyCap": 4,
      "queueDepth": 0,
      "nextWindow": null,
      "lastPostAt": null
    }
  ]
}

Responses

200Success
POST

/v2/accounts

Create a publishing account

Provide 1–5 warmup.searchTerms. Requests with more than five terms are rejected. Existing accounts and tasks with longer lists remain supported; new or edited lists must have at most five terms. The response uses warmupSearchTerms for the stored terms. Account setup is asynchronous. Includes stored profilePictureUrl, bio, and warmupSearchTerms. Missing picture/bio values are null; missing terms are []. Setup placeholders contain requested values; pending profile edits retain previous values until worker approval. Stored values do not independently verify the live platform profile or completed warm-up.

Request body

platformenum: tiktok | instagramrequired
usernamestringrequired
displayNamestringrequiredmin length 1 · max length 80
biostringrequiredmin length 1 · max length 220
profilePictureUrlstringrequiredformat: uri · max length 2048

Use the stable URL from a completed image upload (POST /v2/uploads, then GET /v2/uploads/{uploadId}.url). Compatible direct HTTP(S) image URLs are decoded and copied into owned Storage. JPEG, PNG, WebP or GIF; maximum 10 MB and 40 megapixels. Drive viewer/HTML pages are rejected.

bioUrlstringformat: uri · max length 2048
warmupobjectrequired
searchTermsarray<string>requiredmin items 1 · max items 5

1–5 account-specific warm-up search terms. Existing accounts may contain more than five.

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/accounts" \
  -H "Authorization: Bearer $HUMANPOST_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": "ACCOUNT_ID",
  "platform": "tiktok",
  "username": "buildmode",
  "displayName": "Build Mode",
  "profilePictureUrl": "https://cdn.example.com/build-mode.png",
  "bio": "Building practical side hustles in public.",
  "warmupSearchTerms": [
    "build in public",
    "side hustle experiments"
  ],
  "status": "settingUp",
  "timezone": "America/New_York",
  "followers": 0,
  "postsToday": 0,
  "dailyCap": 4,
  "queueDepth": 0,
  "nextWindow": null,
  "lastPostAt": null
}

Responses

201Setup requested
400Error
403Error
409Error
429Error
GET

/v2/accounts/{accountId}

Get a publishing account

Requires accounts:read. Account must belong to the API key's company. Includes stored profilePictureUrl, bio, and warmupSearchTerms. Missing picture/bio values are null; missing terms are []. Setup placeholders contain requested values; pending profile edits retain previous values until worker approval. Stored values do not independently verify the live platform profile or completed warm-up.

Parameters

NameInRequiredType
accountIdpathrequiredstring

Request

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

200 response

{
  "accountId": "ACCOUNT_ID",
  "platform": "tiktok",
  "username": "buildmode",
  "displayName": "Build Mode",
  "profilePictureUrl": "https://cdn.example.com/build-mode.png",
  "bio": "Building practical side hustles in public.",
  "warmupSearchTerms": [
    "build in public",
    "side hustle experiments"
  ],
  "status": "settingUp",
  "timezone": "America/New_York",
  "followers": 0,
  "postsToday": 0,
  "dailyCap": 4,
  "queueDepth": 0,
  "nextWindow": null,
  "lastPostAt": null
}

Responses

200Success
404Error
POST

/v2/accounts/{accountId}/profile-changes

Request existing-account profile updates

Requires accounts:write. Groups username, display name, bio and picture edits into the asynchronous worker workflow. A display-name edit during a known cooldown is queued until eligible; other requested fields can proceed independently. Two fully completed requests per account in a rolling 30-day window are included; partial/failed requests do not consume this allowance. Only one request may be active. Platform restrictions also apply. Reuse the same key and body to retry, including after completion or interrupted task dispatch.

Parameters

NameInRequiredType
accountIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

usernamestringmin length 1 · max length 32

Username; leading @ is removed and letters are lowercased. 1–30 letters, numbers, periods or underscores; no trailing period. Platform availability is checked by the worker.

displayNamestringmin length 1 · max length 50

Display name: up to 30 characters for TikTok or 50 for Instagram.

biostringmax length 150

Bio: up to 80 characters for TikTok or 150 for Instagram. Empty string clears the bio.

profilePictureUploadIdstringmin length 1 · max length 200

A ready image upload belonging to this company. Profile photos must decode as JPEG, PNG, WebP or GIF, at most 10 MB and 40 megapixels. Upload through /v2/uploads first; arbitrary image URLs and signed PUT URLs are not accepted here.

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/accounts/ACCOUNT_ID/profile-changes" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Idempotency-Key: UNIQUE_OPERATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Build Mode",
  "bio": "Tools for growing teams",
  "profilePictureUploadId": "upload_123"
}'

200 response

{
  "requestId": "profile_123",
  "accountId": "account_123",
  "status": "queued",
  "fields": [
    "displayName",
    "bio",
    "profilePicture"
  ],
  "completedFields": [],
  "blockedFields": [],
  "message": null,
  "createdAt": "2026-10-09T12:00:00.000Z",
  "updatedAt": "2026-10-09T12:00:00.000Z",
  "completedAt": null,
  "allowance": {
    "limit": 2,
    "windowDays": 30,
    "used": 0,
    "remaining": 2,
    "nextEligibleAt": null
  },
  "idempotentReplay": true
}

Responses

200Original request returned on idempotent replay
202Accepted; worker execution and approval are pending
400Error
401Error
403Error
404Error
409Error
429Error
GET

/v2/accounts/{accountId}/profile-changes

Get profile-update eligibility and latest request

Requires accounts:read. Returns allowance, field eligibility, active request and latest outcome. Instagram name dates follow HumanPost's rolling 14-day safeguard; the platform limit and reset semantics are unverified. Dates do not guarantee platform acceptance, and outside edits may be unknown. Null means no tracked restriction, not unlimited edits. Check fieldNextEligibleAt as well as canSubmit.

Parameters

NameInRequiredType
accountIdpathrequiredstring

Request

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

200 response

{
  "accountId": "abc123",
  "allowance": {
    "limit": 2,
    "windowDays": 30,
    "used": 1,
    "remaining": 1,
    "nextEligibleAt": "2027-01-01T00:00:00Z"
  },
  "fieldNextEligibleAt": {
    "username": "2027-01-01T00:00:00Z",
    "displayName": "2027-01-01T00:00:00Z",
    "bio": "2027-01-01T00:00:00Z",
    "profilePicture": "2027-01-01T00:00:00Z"
  },
  "activeRequestId": "abc123",
  "legacyRequestPending": true,
  "canSubmit": true,
  "nextEligibleAt": "2027-01-01T00:00:00Z",
  "latestRequest": {
    "requestId": "abc123",
    "accountId": "abc123",
    "status": "creating",
    "fields": [
      "username"
    ],
    "completedFields": [
      "username"
    ],
    "blockedFields": [
      "username"
    ],
    "message": "Request completed",
    "createdAt": "2027-01-01T00:00:00Z",
    "updatedAt": "2027-01-01T00:00:00Z",
    "completedAt": "2027-01-01T00:00:00Z",
    "allowance": {
      "limit": 2,
      "windowDays": 30,
      "used": 1,
      "remaining": 1,
      "nextEligibleAt": "2027-01-01T00:00:00Z"
    },
    "idempotentReplay": true
  }
}

Responses

200Success
401Error
403Error
404Error
GET

/v2/accounts/{accountId}/profile-changes/{profileChangeRequestId}

Get a profile-update request

Requires accounts:read. Poll status and inspect completedFields, blockedFields and message. completed means every field was approved; partially_completed, blocked and failed are terminal. Stored account values update through existing worker approval behavior.

Parameters

NameInRequiredType
accountIdpathrequiredstring
profileChangeRequestIdpathrequiredstring

Request

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

200 response

{
  "requestId": "profile_123",
  "accountId": "account_123",
  "status": "queued",
  "fields": [
    "displayName",
    "bio",
    "profilePicture"
  ],
  "completedFields": [],
  "blockedFields": [],
  "message": null,
  "createdAt": "2026-10-09T12:00:00.000Z",
  "updatedAt": "2026-10-09T12:00:00.000Z",
  "completedAt": null,
  "allowance": {
    "limit": 2,
    "windowDays": 30,
    "used": 0,
    "remaining": 2,
    "nextEligibleAt": null
  },
  "idempotentReplay": false
}

Responses

200Success
401Error
403Error
404Error
GET

/v2/accounts/{accountId}/queue

Get an account queue

Parameters

NameInRequiredType
accountIdpathrequiredstring
limitqueryoptionalinteger
cursorqueryoptionalstring

Request

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

200 response

{
  "data": [
    {
      "postId": "abc123",
      "queueItemId": "abc123",
      "status": "draft",
      "failureReason": "string",
      "caption": "A new post from HumanPost",
      "thumbnailUrl": "https://example.com/media",
      "queuedAt": "2027-01-01T00:00:00Z",
      "scheduledAfter": "2027-01-01T00:00:00Z",
      "expiresAt": "2027-01-01T00:00:00Z",
      "scheduledSlotStart": "2027-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "cursor_abc123"
}

Responses

200Success
GET

/v2/accounts/{accountId}/analytics

Get account analytics

Parameters

NameInRequiredType
accountIdpathrequiredstring

Request

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

200 response

{
  "accountId": "abc123",
  "followers": 1,
  "posts": 1,
  "engagement": 1,
  "analytics": {
    "views": 1,
    "likes": 1,
    "comments": 1
  },
  "scannedPosts": 1,
  "coverage": {
    "limit": 200,
    "possiblyTruncated": true,
    "source": "string",
    "destinationSpecific": false,
    "latestCollectedAt": "string"
  }
}

Responses

200Success

Scheduling#

GET

/v2/schedule

Get the company posting schedule

Requires accounts:read. Returns the default for the API key's company. Individual account overrides take precedence.

Request

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

200 response

{
  "companyId": "abc123",
  "schedule": {
    "windows": [
      "08:00"
    ]
  },
  "source": "company",
  "scheduledPostsPerDay": 1,
  "maxPostsPerDay": 4,
  "timezoneMode": "worker_local"
}

Responses

200Success
403Error
404Error
PATCH

/v2/schedule

Set the company posting schedule

Requires accounts:write. Replaces the company default, preserving individual account overrides. Individual account schedules still take priority even when this default is edited afterward through the dashboard, API, or MCP. One daily post per selected 3-hour window, in each assigned worker's local timezone. Send schedule: null to restore global rules, not pause posting. Applies to future dispatches; already released tasks are unchanged. Missed posts may use unused make-up windows, up to 4 posts/day/account.

Request body

scheduleobject | nullrequired

Replace the active windows with 1–4 sorted HH:mm starts, at least 3 hours apart, between 08:00 and 17:00 inclusive. Standard slots: 08:00, 11:00, 14:00, 17:00. Times follow each assigned worker's timezone. null clears the override; it does not pause posting.

windowsarray<string>requiredmin items 1 · max items 4

Request

curl -X PATCH \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/schedule" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule": {
    "windows": [
      "08:00",
      "17:00"
    ]
  }
}'

200 response

{
  "companyId": "abc123",
  "schedule": {
    "windows": [
      "08:00"
    ]
  },
  "source": "company",
  "scheduledPostsPerDay": 1,
  "maxPostsPerDay": 4,
  "timezoneMode": "worker_local"
}

Responses

200Success
400Error
403Error
404Error
GET

/v2/accounts/{accountId}/schedule

Get an account's effective posting schedule

Requires accounts:read. Returns the account override, company default, effective schedule, source, and timezone. Account must belong to the API key's company.

Parameters

NameInRequiredType
accountIdpathrequiredstring

Request

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

200 response

{
  "accountId": "abc123",
  "schedule": {
    "windows": [
      "08:00"
    ]
  },
  "companySchedule": {
    "windows": [
      "08:00"
    ]
  },
  "effectiveSchedule": {
    "windows": [
      "08:00"
    ]
  },
  "source": "account",
  "scheduledPostsPerDay": 1,
  "maxPostsPerDay": 4,
  "timezoneMode": "worker_local",
  "timezone": "string"
}

Responses

200Success
403Error
404Error
PATCH

/v2/accounts/{accountId}/schedule

Set or clear an account posting schedule

Requires accounts:write. Replaces this account's override. Send schedule: null to inherit the company default (or global rules), not pause posting. Applies to future dispatches; already released tasks are unchanged. Times follow the assigned worker's timezone. Missed posts may use unused make-up windows, up to 4 posts/day.

Parameters

NameInRequiredType
accountIdpathrequiredstring

Request body

scheduleobject | nullrequired

Replace the active windows with 1–4 sorted HH:mm starts, at least 3 hours apart, between 08:00 and 17:00 inclusive. Standard slots: 08:00, 11:00, 14:00, 17:00. Times follow each assigned worker's timezone. null clears the override; it does not pause posting.

windowsarray<string>requiredmin items 1 · max items 4

Request

curl -X PATCH \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/accounts/ACCOUNT_ID/schedule" \
  -H "Authorization: Bearer $HUMANPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schedule": {
    "windows": [
      "11:00",
      "14:00"
    ]
  }
}'

200 response

{
  "accountId": "abc123",
  "schedule": {
    "windows": [
      "08:00"
    ]
  },
  "companySchedule": {
    "windows": [
      "08:00"
    ]
  },
  "effectiveSchedule": {
    "windows": [
      "08:00"
    ]
  },
  "source": "account",
  "scheduledPostsPerDay": 1,
  "maxPostsPerDay": 4,
  "timezoneMode": "worker_local",
  "timezone": "string"
}

Responses

200Success
400Error
403Error
404Error

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 $HUMANPOST_API_KEY"

200 response

{
  "version": 1,
  "company": {
    "companyId": "abc123",
    "name": "string",
    "description": "string",
    "website": "string"
  },
  "accounts": [
    {
      "accountId": "abc123",
      "platform": "tiktok",
      "username": "humanpost",
      "displayName": "string",
      "profilePictureUrl": "https://example.com/media",
      "bio": "string",
      "warmupSearchTerms": [
        "string"
      ],
      "status": "string",
      "timezone": "string",
      "followers": 1,
      "postsToday": 1,
      "dailyCap": 1,
      "queueDepth": 1,
      "nextWindow": "2027-01-01T00:00:00Z",
      "lastPostAt": "2027-01-01T00:00:00Z",
      "niche": "string"
    }
  ],
  "folders": [
    {
      "folderId": "abc123",
      "name": "string",
      "createdAt": "2027-01-01T00:00:00Z",
      "images": [
        {
          "imageId": "abc123",
          "folderId": "abc123",
          "label": "string",
          "description": "string",
          "tags": [
            "string"
          ],
          "width": 1,
          "height": 1,
          "createdAt": "2027-01-01T00:00:00Z"
        }
      ],
      "packs": [
        {
          "packId": "abc123",
          "folderId": "abc123",
          "name": "string",
          "description": "string",
          "color": "string",
          "imageIds": [
            "abc123"
          ],
          "imageFit": "fit",
          "useImagesOnce": true
        }
      ]
    }
  ],
  "refreshedAt": "2027-01-01T00: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 $HUMANPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "folderId": "abc123",
      "imageId": "abc123"
    }
  ]
}'

200 response

{
  "expiresAt": "2027-01-01T00:00:00Z",
  "data": [
    {
      "folderId": "abc123",
      "imageId": "abc123",
      "url": "https://example.com/media"
    }
  ]
}

Responses

200Success
400Error
401Error
403Error
404Error
GET

/v2/workspace/folders

Browse company folders with bounded search and cursor

Requires workspace:read. Browse company-owned folders with optional search. Scans are bounded; continue with nextCursor even if a filtered page is empty.

Parameters

NameInRequiredType
limitqueryoptionalinteger
cursorqueryoptionalstring
searchqueryoptionalstring

Request

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

200 response

{
  "data": [
    {
      "folderId": "abc123",
      "name": "string",
      "createdAt": "2027-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "cursor_abc123"
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error
GET

/v2/workspace/folders/{folderId}/images

Browse company-owned folder images

Requires workspace:read. Browse available images in a company-owned folder with optional label, description, or tag search. Continue with nextCursor even if a filtered page is empty.

Parameters

NameInRequiredType
folderIdpathrequiredstring
limitqueryoptionalinteger
cursorqueryoptionalstring
searchqueryoptionalstring

Request

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

200 response

{
  "data": [
    {
      "imageId": "abc123",
      "folderId": "abc123",
      "label": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "width": 1,
      "height": 1,
      "createdAt": "2027-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "cursor_abc123"
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error

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 $HUMANPOST_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 $HUMANPOST_API_KEY"

200 response

{
  "taskCredits": {
    "comment": {
      "monthlyLimit": 1,
      "monthlyUsed": 1,
      "monthlyAvailable": 1,
      "oneTimeAvailable": 1,
      "totalAvailable": 1,
      "monthlyCreditsAvailable": true
    },
    "amplify": {
      "monthlyLimit": 1,
      "monthlyUsed": 1,
      "monthlyAvailable": 1,
      "oneTimeAvailable": 1,
      "totalAvailable": 1,
      "monthlyCreditsAvailable": true
    },
    "periodStart": "2027-01-01T00:00:00Z",
    "periodEnd": "2027-01-01T00:00:00Z"
  },
  "plan": "string",
  "billingType": "string",
  "videoQuota": 1,
  "videoCount": 1,
  "postCredits": {
    "limit": 1,
    "used": 1
  },
  "postsPerDay": 1,
  "apiRequestsToday": 1,
  "postsCreatedToday": 1,
  "uploadsCreatedToday": 1,
  "accountsCreatedToday": 1,
  "dailyLimits": {
    "apiRequestsToday": 1,
    "postsCreatedToday": 1,
    "uploadsCreatedToday": 1,
    "accountsCreatedToday": 1
  },
  "resetsAt": "2027-01-01T00:00:00Z"
}

Responses

200Success
GET

/v2/context

Read company, scopes, and capabilities

Confirms the company bound to this key, granted scopes, available tools and capabilities.

Request

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

200 response

{
  "company": {
    "companyId": "abc123",
    "name": "string"
  },
  "scopes": [
    "posts:read"
  ],
  "availableTools": [
    "string"
  ],
  "capabilities": {
    "instagramFeedPosts": true,
    "maxAccountsPerPost": 100,
    "oneAccountPerPlatform": false,
    "maxCarouselImages": 20,
    "scheduling": "earliest_release_worker_local",
    "taskTypes": [
      "string"
    ],
    "taskReview": "humanpost"
  },
  "serverVersion": "string"
}

Responses

200Success
400Error
401Error
403Error
404Error
409Error
422Error
429Error
503Error