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. Median 43 s, p99 87 s, measured in production.

You need a projectId. If you do not have one, GET /projects lists them.

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" }]
}

Read the slides, if you want to edit them before publishing.

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

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.