Schedule and publish
Put a post on the calendar, take it off, or publish it right now.
A draft becomes a scheduled post with one call, and scheduling is reversible until it fires.
Schedule:
curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
-d '{"when":"2026-10-02T13:00:00Z"}' \
"https://api.posttar.com/v1/posts/dd8d142c-.../schedule"Take it off the calendar, back to draft:
curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" \
"https://api.posttar.com/v1/posts/dd8d142c-.../unschedule"Publishing now
POST /posts/:id/publish publishes to Instagram immediately. It answers 202: the post comes back as publishing and finishes in the background. Median 38 s, p99 61 s.
Publishing needs a connected Instagram account on the project. Connecting it is OAuth and does not cross into the API, so a project that was never connected in the app cannot publish through it either.
The states a post moves through
| status | What it means |
|---|---|
idea | A theme captured, nothing generated yet |
queued, generating | Being created right now |
draft | Ready for review |
scheduled | On the calendar, waiting for its time |
publishing | Being sent to Instagram |
published | Live on Instagram |
failed | Generation or publication failed |
archived | Put away, still readable |
POST /posts/:id/archive does not remove anything from Instagram. A post that is already published stays published there.