# 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:

```bash
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:

```bash
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.