List posts
GET /posts returns your posts. Optionally filter with ?status= (for example
scheduled or draft).
Response
Create a post
POST /posts creates a draft or scheduled post.
TikTok posts can only be saved as drafts through the API: TikTok requires the
creator to choose who sees each post in the Postbase composer.
Returns the created post with
201 Created. Invalid channel ids or media ids, an empty
post, or a post a network would reject return 400 with the reason; with no
active plan, scheduling returns 402. Error bodies look like
{ "error": "<readable message>", "code": "<code>" }.
Retrying safely
If a request times out, you can’t tell whether the post was made. Send anIdempotency-Key header (any unique string, such as a UUID or your own record’s
id) and retry with the same key: the first request creates the post, and any
repeat returns that post with 200 OK and "idempotent_replay": true instead
of creating another. Keys are scoped to your workspace and don’t expire.
Get a post
GET /posts/{id} returns the post and how it went on each channel.
Response
url is set once it’s published, error says why it failed, and
retry_at is when Postbase will try it again on its own (null once it has
stopped retrying). warning means it went out with something to know. metrics
holds the latest numbers where the network reports them.
Edit a post
PATCH /posts/{id} edits a draft or scheduled post. It takes the same fields as
creating one, and only the fields you send change: send just scheduled_at to
reschedule, or "scheduled_at": null to turn it back into a draft. The same
checks apply as when creating. Returns the post as GET /posts/{id} does. A
post that has started publishing returns 409.
Retry a post
POST /posts/{id}/retry sends the post again, right away, to the channels where
it failed. Channels where it published are left alone, so nothing goes out
twice. Returns 202 Accepted with the channels being retried:
Response
409. Check GET /posts/{id} first: a
channel whose connection expired needs reconnecting in Postbase.
Cancel a post
POST /posts/{id}/cancel reverts a scheduled post to a draft. Reschedule it
later with PATCH /posts/{id}.