Skip to main content
POST
Publish a document post

Authorizations

Authorization
string
header
required

Your API key, sent as Authorization: Bearer <key>. One key manages every profile on the account.

Headers

Idempotency-Key
string

A key you generate per post, written down BEFORE the call. Replaying a completed key returns the earlier result instead of publishing again — from outside that looks exactly like being ignored. Reusing one for a DIFFERENT body answers idempotency_conflict.

Body

application/json
profile_id
string
required

Id of the brand profile to act on. List them with GET /v1/profiles.

platforms
enum<string>[]
required

Channels to publish to. A comma-separated string is accepted as well.

Available options:
tiktok,
instagram,
linkedin,
youtube,
facebook,
x,
threads,
pinterest,
reddit,
bluesky,
google_business,
telegram,
discord,
slack,
mastodon,
nostr,
lemmy,
devto,
hashnode,
wordpress,
whop,
listmonk
document_url
string<uri>
required

https:// URL of the document to publish.

caption
string
required

The post BODY. This is NOT the post title: title (and the per-channel <channel>_title) is a separate field, and putting the body in it skips the caption-length check.

scheduled_at
string<date-time>

Publish at this time instead of now (ISO 8601). Pair with timezone.

timezone
string

IANA timezone for scheduled_at, e.g. Asia/Ho_Chi_Minh.

Response

Success.

status
enum<string>

processing and scheduled are not outcomes yet — poll GET /v1/posts/status. draft: no channel refused, but at least one holds the post as a draft (see results.<channel>.draft); it is final. canceled comes from a status poll only: a scheduled post that was cancelled before it ran. unknown: the publish call stopped waiting before the channels answered (502 upstream_timeout) and their side has not picked the post up yet; keep polling.

Available options:
completed,
draft,
partial,
failed,
processing,
scheduled,
canceled,
unknown
profile_id
string
platforms
string[]
failed_platforms
string[]

Present only when at least one channel refused.

request_id
string | null
job_id
string | null
truncated
object[]

Present only when the shared caption was cut to fit a channel. One entry per channel and text: text is title, caption or description, field the channel field the cut text went in, length the caption's length and limit the cap, both in unit (utf16 characters, or utf8 bytes for YouTube's description). Every channel not listed received the full caption.

results
object | null

Keyed by channel.

warnings
object[]

Present only when a channel published the post but not exactly as asked — for example a TikTok photo that went out without the requested music. status is not changed by a warning: the post is live, so do not retry it. On an async post warnings appear on GET /v1/posts/status, not on the first publish response. A warning a platform returns only with the first answer of a post is on the publish response only.