Posts and scheduling

Get an API key

A post belongs to an establishment and goes to one or several networks, its targets. Each target has its own text, media and format, and its own state.

Endpoints

POST/v1/postsGET/v1/postsGET/v1/posts/{id}PATCH/v1/posts/{id}DELETE/v1/posts/{id}

The body of a post

Field	Meaning
`establishmentId`	The establishment that publishes (`GET /v1/establishments`)
`targets[]`	One entry per network: `platform`, `text`, optional `media`, `format` and `accountId`
`targets[].media[]`	A media of the library by `id`, or a public https `url` with its `type` (`image` or `video`)
`targets[].accountId`	The account to use when the establishment has several on that network
`scheduledAt`	A future ISO 8601 date-time; absent, the post leaves now
`status`	`draft` to save a draft that does not leave (no `scheduledAt` then)

States

State	Meaning
`draft`	Saved, does not leave
`scheduled`	Will leave at `scheduledAt`
`publishing`	Being sent to the network
`published`	Online, with its `permalink`
`failed`	The network refused it; `error` says why
`sent_to_inbox`	Sent to the app of the network, where the owner finishes it (TikTok)

The status of the post sums up its targets. It is partial when one network published and another failed.

Edit before departure

PATCH /v1/posts/{id} rewrites the targets, moves scheduledAt, or changes status: draft takes the time away and keeps the content, scheduled schedules it again. Once a network has sent the post, it answers 409 post_not_editable.

bash

curl -X PATCH https://api.sofia-post.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"scheduled","scheduledAt":"2026-11-20T09:00:00Z"}'

Delete

DELETE /v1/posts/{id} answers 204. While a network is sending the post, it answers 409 post_in_flight: retry a moment later.

List posts

GET /v1/posts lists every post the token can reach, newest first, filtered by establishmentId, status, from, to and createdBy (me or app). A post matches status when at least one of its networks is in that state. See pagination.