Docs menuDrafts

Drafts

GET /api/v1/drafts

Drafts (default), scheduled or archived posts, newest first; page with cursor. tag: only posts with that label.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
statusquery"draft" | "scheduled" | "archived" | "all"

draft (default), scheduled, archived or all.

connection_idquerystring

One account's posts plus those aimed at no account. Omitted: the default account, else the only one.

Up to 36 characters
qquerystring

Only posts whose text contains this.

Up to 200 characters
date_fromquerystring

Only posts whose event_date is from this time (ISO 8601, UTC when no offset).

Up to 40 characters
date_toquerystring

Only posts whose event_date is up to this time (ISO 8601, UTC when no offset).

Up to 40 characters
has_mediaqueryboolean

true: only posts with media; false: only posts without.

created_viaquery"web" | "chat" | "duplicate" | "session" | "mcp" | "api" | "repeat" | "rss"

Only posts made this way: api (an API key), mcp (an AI app), web (the Postory app), chat, duplicate, session, repeat, rss.

limitqueryinteger

At most this many posts, 1-50 (default 20). A larger value is read as 50, 0 or less as 20.

cursorquerystring

next_cursor from the previous page, while has_more; keep the other parameters unchanged.

Up to 512 characters
include_repliesqueryboolean

true also lists reply posts (left out by default).

tagquerystring

Only posts with this label (its name).

Up to 40 characters

Example

Request
curl https://postory.io/api/v1/drafts \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "items": [
    {
      "id": "<post_id>",
      "url": "https://postory.io/calendar?view=list&focus=<post_id>",
      "status": "draft",
      "text": "Hello from the Postory API",
      "event_date": "2026-12-01T09:00:00+00:00",
      "created_via": "api",
      "target": {
        "connection_id": "<connection_id>",
        "platform": "x",
        "handle": "yourhandle"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "<next_cursor>",
  "acting_as": {
    "postory": "[email protected]",
    "x": "yourhandle",
    "label": "@yourhandle · X",
    "plan": "free"
  }
}

Other responses

401

No API key, or an invalid or revoked one

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

POST /api/v1/drafts

Save a new draft (or thread), or several (posts); with scheduled_at also schedule it on every account. Idempotency-Key replays the first answer for 24 hours.

  • 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
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
idempotency_keystring

A UUID you choose: a retry with the same key answers the first result (replayed: true) instead of doing it again. The Idempotency-Key header does the same for the whole request.

Up to 36 characters
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
partsThreadPart[]

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. Not with posts.

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
postsNewPost[]

Several posts in one request instead of parts: 1 to 10, each {parts, connection_ids, labels, first_comment, scheduled_at}}; a field a post omits takes this request's. Answers drafts (and deliveries).

1–10 items
posts[].connection_idsstring[]

This post's accounts (connection_ids from GET /accounts), the first primary. Omitted: the request's connection_ids, else the default account.

Up to 10 items
posts[].first_commentstring

This post's first comment. Omitted: the request's first_comment.

Up to 25000 characters
posts[].labelsstring[]

This post's label names. Omitted: the request's labels.

Up to 10 items
posts[].partsrequiredThreadPart[]

This post's thread, 1 to 25 parts in order, part 1 first; text only.

1–25 items
posts[].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
posts[].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
posts[].scheduled_atstring

When to publish this post on each of its accounts: ISO 8601 (UTC when it has no offset), 2 minutes to 30 days from now, or "next_slot". Omitted: the request's scheduled_at; neither: it stays a draft.

Up to 40 characters
scheduled_atstring

Also schedule the post (with posts: each post without its own) on every account: ISO 8601 (UTC when it has no offset), 2 minutes to 30 days from now, or "next_slot". The accounts, times and the credits of every delivery are checked before anything is saved; then each delivery is checked as POST /drafts/{post_id}/schedule checks it and answered in deliveries (ok, or its error; that post stays a draft).

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/drafts \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {"text": "First post of the thread"},
      {"text": "Second post"}
    ],
    "connection_ids": ["<connection_id>"]
  }'
Response 201
{"post_id": "<post_id>", "preview_url": "<preview_url>"}

Other responses

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

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

GET /api/v1/drafts/{post_id}

One draft: its parts with length against each account's limit, media and accounts. Per part chars, limit (the account's text_max) and fits; where the account's text_advice is lower, advice and over_advice too.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters

Example

Request
curl "https://postory.io/api/v1/drafts/<post_id>" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{"post_id": "<post_id>"}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

PATCH /api/v1/drafts/{post_id}

Edit a draft: only what is sent changes; parts replaces the thread.

  • Scopepostory:drafts
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters

Request body

FieldTypeDescription
community_idstring

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

Up to 32 characters
connection_idsstring[]

REPLACES the draft's accounts, the first primary; at most 10.

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). "" removes it.

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[]

REPLACES the post's labels by name ([] clears them; a new name makes the label).

Up to 10 items
partsEditPart[]

REPLACES the thread: send every part to keep, each with the id GET /drafts/{post_id} gave it (part 1 has none). A part left out is deleted with its attachments.

1–25 items
parts[].delay_secondsinteger

Parts 2..N: seconds after the previous part, 0 (straight after) or 60-7200. Omitted: the part keeps its wait.

From 0 to 7200
parts[].idstring

The part's id from GET /drafts/{post_id}, to keep that part; part 1 has none (null).

Up to 36 characters
parts[].media_idsstring[]

Omitted: the part keeps its media. A list (ids from GET /drafts/{post_id}) is the part's whole media in order; what it leaves out moves back to part 1. Nothing is deleted.

Up to 10 items
parts[].textstring

The part's text, up to 25,000 characters. A part with neither text nor media is refused.

Default: "" · Up to 25000 characters
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. "" clears it.

Up to 50 characters
versionsEditVersion[]

Per account: parts replaces its own text, use_shared_text: true drops it so the account takes the shared parts again. Accounts not listed keep theirs.

Up to 10 items
versions[].connection_idrequiredstring

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

Up to 36 characters
versions[].partsNewPart[]

REPLACES that account's own thread, text only, 1 to 25 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
versions[].use_shared_textboolean

true drops the account's own text: it takes the shared parts again.

Example

Request
curl -X PATCH "https://postory.io/api/v1/drafts/<post_id>" \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"community_id": "<community_id>"}'
Response 200
{"post_id": "<post_id>", "preview_url": "<preview_url>"}

Other responses

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

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

DELETE /api/v1/drafts/{post_id}

Delete a draft permanently, with its attachments. POST …/archive is reversible.

  • Scopepostory:drafts
  • Limit classDELETE
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters

Example

Request
curl -X DELETE "https://postory.io/api/v1/drafts/<post_id>" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "deleted": true,
  "id": "<post_id>",
  "acting_as": {
    "postory": "[email protected]",
    "x": "yourhandle",
    "label": "@yourhandle · X",
    "plan": "free"
  }
}

Other responses

401

No API key, or an invalid or revoked one

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

POST /api/v1/drafts/{post_id}/archive

Move a draft to the archive (restorable in Postory).

  • Scopepostory:drafts
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters

Example

Request
curl -X POST "https://postory.io/api/v1/drafts/<post_id>/archive" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "id": "<post_id>",
  "status": "archived",
  "message": "Post was moved to archive",
  "acting_as": {
    "postory": "[email protected]",
    "x": "yourhandle",
    "label": "@yourhandle · X",
    "plan": "free"
  }
}

Other responses

401

No API key, or an invalid or revoked one

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

POST /api/v1/drafts/{post_id}/preflight

Check and price publishing NOW; an ok answer carries a single-use confirmation_token (10 minutes) and, with browser approval on, an approval_url the user must approve. Nothing is published or charged.

  • Scopepostory:publish
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters

Example

Request
curl "https://postory.io/api/v1/drafts/<post_id>/preflight" \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connection_id": "<connection_id>"}'
Response 200
{
  "approval_url": "<approval_url>",
  "confirmation_token": "<confirmation_token>",
  "ok": true
}

Other responses

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/drafts/{post_id}/publish

Publish now with the preflight's confirmation_token, after the user's yes (or their browser approval). Waits for the outcome; a thread with part delays answers once part 1 is live, with the remaining parts.

  • Scopepostory:publish
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters
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
allow_republishboolean

true publishes a post already published to this account again, on purpose (otherwise 409 already_published).

confirmation_tokenrequiredstring

From POST /drafts/{post_id}/preflight for this post and account: single-use, valid 10 minutes, void once the draft changes.

Up to 128 characters
connection_idstring

The account to publish to. Omitted: the account the token was issued for.

Up to 36 characters
idempotency_keystring

A UUID you choose: a retry with the same key answers the first result (replayed: true) instead of doing it again. The Idempotency-Key header does the same for the whole request.

Up to 36 characters

Example

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

Other responses

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/drafts/{post_id}/schedule

Queue a draft for scheduled_at (2 minutes to 30 days away); no confirmation. Several accounts and no connection_id: one delivery each.

  • Scopepostory:publish
  • Limit classWRITE
  • Success201

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters
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
connection_idstring

With 2+ accounts on the draft: only this account (a connection_id). Omitted: every account of the draft.

Up to 36 characters
idempotency_keystring

A UUID you choose: a retry with the same key answers the delivery it queued, while that delivery exists. Use a new key for each new schedule.

Up to 36 characters
scheduled_atrequiredstring

When to publish: ISO 8601 (UTC when it has no offset), 2 minutes to 30 days from now; or "next_slot", the account's next free posting slot.

Up to 40 characters
share_previewboolean

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

Example

Request
curl "https://postory.io/api/v1/drafts/<post_id>/schedule" \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "<ISO time 2 min–30 days ahead>"}'
Response 201
{
  "scheduled_post_id": "<scheduled_post_id>",
  "already_scheduled": false,
  "status": "pending",
  "scheduled_at": "2026-12-01T09:00:00+00:00",
  "post_id": "<post_id>",
  "connection_id": "<connection_id>",
  "note": "Queued. Postory publishes it at that time and notifies the user; it shows on the Postory calendar. Credits are charged when it publishes; a cancel before then costs nothing and returns it to a draft. Revoking this API key cancels it. If AI access is still paused when it is due, it is skipped.",
  "credits": 3,
  "acting_as": {
    "postory": "[email protected]",
    "x": "yourhandle",
    "label": "@yourhandle · X",
    "plan": "free"
  },
  "preview_url": null
}

Other responses

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/drafts/bulk

Archive (restorable) or delete (permanent) 1-10 drafts (items: [{post_id}]). A scheduled post is refused until its delivery is cancelled; a published post's archive entry is never deleted.

  • Scopepostory:drafts
  • Limit classNONE
  • Success200

Request body

FieldTypeDescription
actionrequired"archive" | "delete"

archive (restorable in Postory) or delete (permanent, with the drafts' attachments).

itemsrequiredBulkDraftItem[]

1 to 10 drafts, each {post_id}, each at most once.

1–10 items
items[].post_idrequiredstring

The draft's post_id.

Up to 36 characters

Example

Request
curl https://postory.io/api/v1/drafts/bulk \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "archive", "items": [{"post_id": "<post_id>"}]}'
Response 200
{"applied": 0, "refused": 0}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

422

A request parameter is not valid

429

Rate limit spent; see Retry-After