Docs menuPosts

Posts

POST /api/v1/posts

Create a post and, by mode, keep it as a draft, schedule it (scheduled_at), queue it in each account's next free posting slot (queue) or publish it now (confirm: true after the user's yes; without it you get the preview and token). Idempotency-Key replays the first answer for 24 hours. A call that leaves its draft unfinished (a refused step, the preview) is remembered: the same post sent again within 24 hours continues on that draft (the same post_id) while it is untouched, instead of saving a second one.

  • Scopepostory:drafts
  • Limit classWRITE
  • Success201

Parameters

NameInTypeDescription
Idempotency-Keyheaderstring

Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours (Idempotent-Replayed: true) without running anything again; the same key with a different request is 409 idempotency_conflict.

Up to 255 characters

Request body

FieldTypeDescription
community_idstring

X only: the id of a Community to post in.

Up to 32 characters
confirmboolean

mode: now: true publishes in this call, after the user's yes. false (default) answers the preview, the price and a confirmation_token (needs_confirmation: true).

Default: false
connection_idsstring[]

Every account the post is for (connection_ids from GET /accounts), the first primary; at most 10. Omitted: the default account, else the only one.

Up to 10 items
event_datestring

The post's slot on the Postory calendar (ISO 8601, UTC when it has no offset). Not a publish time: scheduling is POST /drafts/{post_id}/schedule.

Up to 40 characters
first_commentstring

A reply to part 1 sent after the last part, by the post's X, Threads or Bluesky accounts only (draft.first_comment_note names the others); refused when no account of the post takes one. Checked against each account's own text limit (422 first_comment_too_long).

Up to 25000 characters
first_comment_delay_secondsinteger

Seconds after the last part before the first comment goes out: 0 (straight after) or 60-7200.

From 0 to 7200
labelsstring[]

Names of your labels for the post, at most 10 of up to 40 characters; a new name makes the label.

Up to 10 items
mode"draft" | "schedule" | "queue" | "now"

draft (default) saves it; schedule also queues it for scheduled_at on every account; queue queues it in each account's next free posting slot; now previews a publish now, and publishes with confirm: true.

Default: "draft"
partsrequiredThreadPart[]

The post, or a thread of 1 to 25 parts in order, part 1 first. Text only: attach media to the saved draft with POST /media or POST /drafts/{post_id}/media/from-url.

1–25 items
parts[].delay_secondsinteger

Parts 2..N: seconds after the previous part goes out before this one does, 0 (straight after) or 60-7200. Part 1 has none.

From 0 to 7200
parts[].textstring

The part's text, up to 25,000 characters (each network's own limit is checked at publish: chars, limit and fits in the answer).

Default: "" · Up to 25000 characters
scheduled_atstring

mode: schedule only, and required there: ISO 8601 (UTC when it has no offset), 2 minutes to 30 days from now.

Up to 40 characters
share_previewboolean

true makes a read-only public link to the post, opened with no login: preview_url.

share_with_followersboolean

X only, with community_id: also show the Community post to your followers (default true).

topic_tagstring

Threads only: the post's topic tag, up to 50 characters.

Up to 50 characters
versionsNewVersion[]

An account's own text where it differs from parts: {connection_id, parts}, one per account, at most 10. Media stays on the shared parts.

Up to 10 items
versions[].connection_idrequiredstring

The account this version is for: one of the draft's connection_ids.

Up to 36 characters
versions[].partsrequiredNewPart[]

That account's own thread, text only, 1 to 25 parts; media stays on the shared parts.

1–25 items
versions[].parts[].textstring

The part's text, up to 25,000 characters (each network's own limit is checked at publish: chars, limit and fits in the answer).

Default: "" · Up to 25000 characters

Example

Request
curl https://postory.io/api/v1/posts \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [{"text": "Hello from the Postory API"}],
    "mode": "draft",
    "connection_ids": ["<connection_id from accounts>"]
  }'
Response 201
{
  "mode": "draft",
  "status": "draft",
  "post_id": "<post_id>",
  "web_url": "https://postory.io/calendar?view=list&focus=<post_id>",
  "draft": {
    "id": "<post_id>",
    "status": "draft",
    "created_via": "api",
    "connection_id": "<connection_id>",
    "handle": "yourhandle",
    "parts": [
      {
        "n": 1,
        "id": null,
        "media_ids": [],
        "chars": 26,
        "limit": 25000,
        "fits": true,
        "advice": 280,
        "over_advice": false
      }
    ],
    "share_with_followers": true,
    "event_date": "2026-12-01T09:00:00+00:00",
    "created_at": "2026-12-01T09:00:00+00:00",
    "updated_at": "2026-12-01T09:00:00+00:00",
    "delivered_to": [],
    "schedules": [],
    "validation": {"ok": true, "issues": [], "warnings": []},
    "platform": "x",
    "url": "https://postory.io/calendar?view=list&focus=<post_id>"
  },
  "acting_as": {
    "postory": "[email protected]",
    "x": "yourhandle",
    "label": "@yourhandle · X",
    "plan": "free"
  },
  "preview_url": null
}

Other responses

202

Accepted: approval_required (open approval_url) or a publish still in flight

400

The copy does not fit an account's network: multipart_unsupported (network, connection_id) is several parts for a network that posts one (LinkedIn); give that account its own one-part version

401

No API key, or an invalid or revoked one

402

Not enough credits for this delivery; see buy_url

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

422

A request parameter is not valid, or an account's network does not take what the post asks: capability_unsupported (network, capability, capability_state, connection_id), e.g. a first comment on a post only for LinkedIn. A shared first comment on a post for several networks is fine: only the accounts whose network takes one send it

429

Rate limit spent; see Retry-After

POST /api/v1/replies

Answer up to 10 received replies: first without confirmation_token (checked, priced, previewed; nothing sent), then with it after the user's yes (or their browser approval).

  • Scopepostory:publish
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
Idempotency-Keyheaderstring

Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours (Idempotent-Replayed: true) without running anything again; the same key with a different request is 409 idempotency_conflict.

Up to 255 characters

Request body

FieldTypeDescription
confirmation_tokenstring

Omitted: the batch is checked, priced and previewed, nothing is sent. Then the token that answer gave (single-use, 10 minutes), after the user's yes: the batch is sent.

Up to 128 characters
connection_idstring

The account the replies were received on (a connection_id). Omitted: the default account, else the only one.

Up to 36 characters
idempotency_keystring

A UUID you choose: a retry of the sending call with the same key answers its first result instead of sending again.

Up to 36 characters
itemsReplyItem[]

The answers, 1 to 10, each {reply_to, text}. Required on the first call; ignored with confirmation_token (the approved batch is sent).

1–10 items
items[].reply_torequiredstring

The received reply to answer: an item's id from GET /replies-to-answer or GET /archive/received-replies; each at most once per batch.

Up to 100 characters
items[].textrequiredstring

The answer's text, up to 25,000 characters. On X leave out a leading @handle (X adds it); the other networks send it as written.

Up to 25000 characters

Example

Request
curl https://postory.io/api/v1/replies \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{"confirmation_token": "<confirmation_token>"}'
Response 200
{
  "approval_url": "<approval_url>",
  "confirmation_token": "<confirmation_token>"
}

Other responses

401

No API key, or an invalid or revoked one

402

Not enough credits for this delivery; see buy_url

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

422

A request parameter is not valid

429

Rate limit spent; see Retry-After