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

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

Name	In	Required	Type
`accountId`	query	optional	string

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

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

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

Name	In	Required	Type
`limit`	query	optional	integer
`cursor`	query	optional	string
`type`	query	optional	enum: 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 \| amazon_review \| g2_review \| trustpilot_review \| intro_video \| spark_code \| connect_posting_service \| delete_post \| delete_account \| blank_task
`status`	query	optional	enum: pending \| assigned \| in_progress \| pending_approval \| completed \| failed \| expired \| cancelled \| unknown
`accountId`	query	optional	string
`platform`	query	optional	enum: tiktok \| instagram
`externalReference`	query	optional	string
`createdAfter`	query	optional	string
`createdBefore`	query	optional	string

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

Name	In	Required	Type
`taskId`	path	required	string

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

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

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

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

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

Name	In	Required	Type
`taskId`	path	required	string

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

Name	In	Required	Type
`taskId`	path	required	string

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 200 MB or 3 minutes, 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 209,715,200 bytes (200 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

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

Name	In	Required	Type
`Idempotency-Key` Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.	header	optional	string

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

Name	In	Required	Type
`Idempotency-Key` Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.	header	optional	string

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 2 · max items 20

imagestringrequiredmin length 1 · max length 200

textElementsarray<object>requiredmax items 6

contentstringrequiredmin length 1 · max length 500

styleobjectrequired

textColorenum: white | black | red | yellow | blue

fontSizenumbermin 6 · max 72

fontWeightenum: normal | bold

textAlignenum: left | center | right

textModeenum: stroke | background | plain | snapchat

positionXnumbermin 0 · max 100

positionYnumberrequiredmin 0 · max 100

widthnumbermin 20 · max 100

paddingnumbermin 0 · max 20

imageFitenum: fit | fill

roleenum: hook | middle | cta

Request

curl -X POST \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/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",
      "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

Name	In	Required	Type
`postId`	path	required	string

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 2 · max items 20

imagestringrequiredmin length 1 · max length 200

textElementsarray<object>requiredmax items 6

contentstringrequiredmin length 1 · max length 500

styleobjectrequired

textColorenum: white | black | red | yellow | blue

fontSizenumbermin 6 · max 72

fontWeightenum: normal | bold

textAlignenum: left | center | right

textModeenum: stroke | background | plain | snapchat

positionXnumbermin 0 · max 100

positionYnumberrequiredmin 0 · max 100

widthnumbermin 20 · max 100

paddingnumbermin 0 · max 20

imageFitenum: fit | fill

roleenum: hook | middle | cta

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

Name	In	Required	Type
`jobId`	path	required	string

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
      }
    }
  ],
  "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
    }
  },
  "error": {
    "code": "string",
    "message": "Request completed",
    "hint": "string",
    "requestId": "abc123",
    "retryable": true,
    "details": [
      {
        "field": "string",
        "message": "Request completed"
      }
    ],
    "retryAfterSeconds": 1
  }
}

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

Name	In	Required	Type
`Idempotency-Key` Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.	header	optional	string

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

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

Parameters

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

Request body

mediaarray<string>requiredmin items 1 · max items 20

accountIdsarray<string>requiredmin items 1 · max items 2

Choose at most one TikTok account and one Instagram account; duplicate platforms are rejected.

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 2 · max items 20

imagestringrequiredmin length 1 · max length 200

textElementsarray<object>requiredmax items 6

contentstringrequiredmin length 1 · max length 500

styleobjectrequired

textColorenum: white | black | red | yellow | blue

fontSizenumbermin 6 · max 72

fontWeightenum: normal | bold

textAlignenum: left | center | right

textModeenum: stroke | background | plain | snapchat

positionXnumbermin 0 · max 100

positionYnumberrequiredmin 0 · max 100

widthnumbermin 20 · max 100

paddingnumbermin 0 · max 20

imageFitenum: fit | fill

roleenum: hook | middle | cta

Request

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

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

Request

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

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 2

Choose at most one TikTok account and one Instagram account; duplicate platforms are rejected.

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

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

Name	In	Required	Type
`postId`	path	required	string

Request body

captionstringmax length 2200

hashtagsarray<string>max items 30

soundobject

modeenum: trending | original | specificrequired

urlstringformat: uri

urlsByPlatformobject

tiktokstringformat: uri

instagramstringformat: uri

notesstring | nullmax length 2000

contentGroupIdsarray<string>max items 10

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

instagramPostFormatenum: reel | post

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

Request

curl -X PATCH \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/posts/POST_ID" \
  -H "Authorization: Bearer $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",
      "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

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

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

Name	In	Required	Type
`postId`	path	required	string

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

Name	In	Required	Type
`postId`	path	required	string
`Idempotency-Key` Company-scoped operation key. Reuse with identical payload only; conflicting use returns 409.	header	optional	string

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

Name	In	Required	Type
`postId`	path	required	string

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
  }
}

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.

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

Name	In	Required	Type
`tagId`	path	required	string

Request body

namestringmin length 1 · max length 50

New unique tag name.

New dashboard display color.

archivedboolean

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

Request

curl -X PATCH \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/content-tags/TAG_ID" \
  -H "Authorization: Bearer $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

Name	In	Required	Type
`tagId`	path	required	string

Request

curl -X DELETE \
  "https://us-central1-clickbaitcarousel.cloudfunctions.net/publishingApi/v2/content-tags/TAG_ID" \
  -H "Authorization: Bearer $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

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

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

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

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

200 response

{
  "data": [
    {
      "postId": "abc123",
      "queueItemId": "abc123",
      "status": "draft",
      "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

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

Name	In	Required	Type
`accountId`	path	required	string

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

Name	In	Required	Type
`accountId`	path	required	string

Request body

scheduleobject | nullrequired

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

Name	In	Required	Type
`limit`	query	optional	integer
`cursor`	query	optional	string
`search`	query	optional	string

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

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

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": 2,
    "oneAccountPerPlatform": true,
    "maxCarouselImages": 20,
    "scheduling": "earliest_release_worker_local",
    "taskTypes": [
      "string"
    ],
    "taskReview": "humanpost"
  },
  "serverVersion": "string"
}

Responses

200Success

400Error

401Error

403Error

404Error

409Error

422Error

429Error

503Error