Long-running calls

The operations that answer 202 and finish in the background.

View as Markdown Open in Claude Open in ChatGPT

A few operations start heavy work and answer before it finishes: creating a post, in any format, publishing, and redoing the speech of a React. They answer 202, not 200, because Posttar does not pretend the work is done. The resource comes back in its real state, and you fetch the outcome later with a GET.

Operation	Usually takes
`POST /posts`	under a minute for most formats, up to about two for the narrated ones
`POST /posts/{id}/publish`	under a minute
`PATCH /posts/{id}/react`	a few minutes; poll `GET /posts/{id}` until `content.speechState` leaves `generating`

Treat those as the usual case and not as a promise: a busy moment, a long theme or a slow answer from Instagram stretches them. Build the polling loop to wait as long as it needs, with a timeout of a few minutes rather than a few seconds.

While a post is not finished, status stays queued or generating. When it finishes it becomes draft, ready for review, or failed. Poll GET /posts/{id} until it leaves those two states.

There is no outcome webhook in this version. Polling is the only way to learn that a long call finished.

Create a post and wait for it

The whole sequence, in order. Copy this block if you are handing the flow to an agent.

Start the creation. Answers 202.

curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"projectId":"c85848ba-...","theme":"three signs your niche is too broad"}' \
  "https://api.posttar.com/v1/posts"

{ "postId": "dd8d142c-4cba-4ea6-9088-e948ac347f56", "format": "carousel", "state": "generating", "remainingCredits": 5 }

Poll until status leaves queued and generating.

curl -H "Authorization: Bearer $POSTTAR_KEY" \
  "https://api.posttar.com/v1/posts/dd8d142c-4cba-4ea6-9088-e948ac347f56"

{
  "id": "dd8d142c-4cba-4ea6-9088-e948ac347f56",
  "status": "generating",
  "projectId": "c85848ba-2881-4a2e-9bdd-841b26d07359",
  "workspaceId": "2bd5c04d-1dd4-456e-8704-9d7b84703fd0",
  "scheduledFor": null,
  "textContent": null,
  "mediaUrls": []
}

Creating answers state, reading answers status. They are two different fields of two different shapes: state only ever says "generating", because that is all the creation call knows, while status carries the real lifecycle, the ten values listed in Schedule and publish. Read what the specific call returns instead of assuming similar fields share values.