Create a post

From a theme to a draft you can review, with the polling loop.

View as Markdown Open in Claude Open in ChatGPT

Creating is asynchronous. You send a theme, get 202 with an id, and poll until the post leaves the working states. A carousel is usually ready in under a minute.

You need a projectId. GET /projects lists them: each entry's id is the projectId that every other call takes.

Theme to draft

The whole sequence. This block is meant to be handed to an agent as is.

Find the project you are writing for.

curl -H "Authorization: Bearer $POSTTAR_KEY" "https://api.posttar.com/v1/projects"

{
  "projects": [
    { "id": "c85848ba-...", "name": "My brand", "instagram": null, "createdAt": "2026-07-31T14:29:14Z" }
  ],
  "limit": 1,
  "canCreateMore": false
}

Start the post. Answers 202, the work runs in the background.

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-...", "format": "carousel", "state": "generating", "remainingCredits": 5 }

Poll until status is no longer queued or generating.

curl -H "Authorization: Bearer $POSTTAR_KEY" "https://api.posttar.com/v1/posts/dd8d142c-..."

{
  "id": "dd8d142c-...",
  "status": "draft",
  "projectId": "c85848ba-...",
  "workspaceId": "2bd5c04d-...",
  "scheduledFor": null,
  "textContent": "Your niche might be broader than you think...",
  "mediaUrls": [{ "url": "https://.../slide-1.webp", "type": "image" }]
}

4
Read the post again to get the slides, if you want to edit them before publishing. They come in content.slides, each with its id.
curl -H "Authorization: Bearer $POSTTAR_KEY" "https://api.posttar.com/v1/posts/dd8d142c-..."

Writing from a link

POST /posts also takes a link. When you send one, Posttar reads that page first, and theme becomes the instruction for what to do with it ("turn this into three tips", for example). You can send either one alone, but not neither.

What can go wrong

`code`	What it means here
`invalid_input`	Neither `theme` nor `link` was sent, or `projectId` is not a valid id
`not_found`	The project is not in this workspace
`invalid_state`	No credits left on the plan

Credits are spent when generation starts, not when it succeeds. A post that ends in failed has already cost its credit.