Create a post

Saves a draft; with scheduledAt it's scheduled, with publishNow Postel publishes it within a minute (the response comes back at once with status scheduled; post.published or post.failed events say how it went). Scheduling and publishing need a paid plan; drafts work on every plan.

When the workspace needs approval, a scheduled post waits for an owner or admin (status pending_approval) and publishNow is refused with approval_required. Text is checked against the account's real limit per part before anything is saved. Media URLs are downloaded and attached to the first part. If scheduling fails, the draft is removed again, so a retry can't double up.

Send an Idempotency-Key header to make retries safe: the same key within 24 hours returns the first response instead of creating another post.

Request

curl -X POST "https://www.postel.app/api/v1/posts" \
  -H "Idempotency-Key: zap-7f3a9c-run-2026-11-03T09:00" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "text": "We shipped our public API today. Three things we learned building it:",
    "firstComment": "Docs: https://www.postel.app/docs/api"
  }'

curl -X POST "https://www.postel.app/api/v1/posts" \  -H "Idempotency-Key: zap-7f3a9c-run-2026-11-03T09:00" \  -H "Content-Type: application/json" \  -d '{    "platform": "linkedin",    "text": "We shipped our public API today. Three things we learned building it:",    "firstComment": "Docs: https://www.postel.app/docs/api"  }'

Response

201

{
  "id": "cmhb0x7rd0001lb08q2k5w3zt",
  "platform": "linkedin",
  "status": "draft",
  "text": "We shipped our public API today. Three things we learned building it:",
  "thread": [
    "We shipped our public API today. Three things we learned building it:"
  ],
  "firstComment": "Docs: https://www.postel.app/docs/api",
  "mediaCount": 0,
  "scheduledAt": null,
  "publishedAt": null,
  "url": null,
  "failure": null,
  "createdAt": "2026-11-03T09:12:44.000Z",
  "updatedAt": "2026-11-03T09:12:44.000Z"
}

Try it

Authorization

bearerAuth

AuthorizationBearer <token>

A Postel API key, Authorization: Bearer pstl_…. Create one in Postel under Settings → API & MCP; it acts for the workspace it was made in.

In: header

Headers

Idempotency-Key?string

Makes retries safe. The first request with a key runs; the same key from the same workspace within 24 hours gets that first response back (with Idempotent-Replayed: true) instead of creating again. Use a value unique to the run, up to 255 characters. Only successes are remembered. A key still running answers 409 request_in_progress; a key reused with a different body answers 422 idempotency_key_reused.

Lengthlength <= 255

Request body

application/json

platform*string

Network to post to; the live ones are x, linkedin, bluesky, mastodon, youtube, tiktok. GET /v1/channels lists them with their accounts.

text?string

The post. On X, Bluesky and Mastodon a line with only --- starts the next part of a thread.

Lengthlength <= 25000

thread?array<>

A thread, one item per part (X, Bluesky, Mastodon). Use instead of text.

Items1 <= items <= 25

mediaUrls?array<>

Public image or video URLs, added to the first part. X: up to 4 images, or one video or GIF. LinkedIn: images, or one video.

Itemsitems <= 4

firstComment?string

LinkedIn only: a comment Postel posts under the post right after it goes out. Up to 1250 characters.

Lengthlength <= 1250

scheduledAt?string

Schedule it for this time (needs a paid plan). Leave out to save a draft.

Formatdate-time

publishNow?boolean

Publish right away (needs a paid plan)

Try it

Authorization

Headers

Request body

Responses

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Create a post

Try it

Authorization

Headers

Request body

Responses

201application/json

400application/json

401application/json

402application/json

409application/json

422application/json

429application/json

500application/json

502application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`