Drafts
GET /api/v1/drafts
Drafts (default), scheduled or archived posts, newest first; page with cursor. tag: only posts with that label.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
status | query | "draft" | "scheduled" | "archived" | "all" |
|
connection_id | query | string | One account's posts plus those aimed at no account. Omitted: the default account, else the only one. Up to 36 characters |
q | query | string | Only posts whose text contains this. Up to 200 characters |
date_from | query | string | Only posts whose |
date_to | query | string | Only posts whose |
has_media | query | boolean |
|
created_via | query | "web" | "chat" | "duplicate" | "session" | "mcp" | "api" | "repeat" | "rss" | Only posts made this way: |
limit | query | integer | At most this many posts, 1-50 (default 20). A larger value is read as 50, 0 or less as 20. |
cursor | query | string |
|
include_replies | query | boolean |
|
tag | query | string | Only posts with this label (its name). Up to 40 characters |
Example
curl https://postory.io/api/v1/drafts \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"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
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A request parameter is not valid
429Rate 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.
- Scope
postory:drafts - Limit class
WRITE - Success
201
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours ( |
Request body
| Field | Type | Description |
|---|---|---|
community_id | string | X only: the id of a Community to post in. Up to 32 characters |
connection_ids | string[] | Every account the post is for ( |
event_date | string | The post's slot on the Postory calendar (ISO 8601, UTC when it has no offset). Not a publish time: scheduling is |
first_comment | string | A reply to part 1 sent after the last part, by the post's X, Threads or Bluesky accounts only ( |
first_comment_delay_seconds | integer | Seconds after the last part before the first comment goes out: 0 (straight after) or 60-7200. From 0 to 7200 |
idempotency_key | string | A UUID you choose: a retry with the same key answers the first result ( |
labels | string[] | 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 |
parts | ThreadPart[] | The post, or a thread of 1 to 25 parts in order, part 1 first. Text only: attach media to the saved draft with |
parts[].delay_seconds | integer | 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[].text | string | The part's text, up to 25,000 characters (each network's own limit is checked at publish: |
posts | NewPost[] | Several posts in one request instead of |
posts[].connection_ids | string[] | This post's accounts ( |
posts[].first_comment | string | This post's first comment. Omitted: the request's |
posts[].labels | string[] | This post's label names. Omitted: the request's |
posts[].partsrequired | ThreadPart[] | This post's thread, 1 to 25 parts in order, part 1 first; text only. 1–25 items |
posts[].parts[].delay_seconds | integer | 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[].text | string | The part's text, up to 25,000 characters (each network's own limit is checked at publish: |
posts[].scheduled_at | string | 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 |
scheduled_at | string | Also schedule the post (with |
share_preview | boolean |
|
share_with_followers | boolean | X only, with |
topic_tag | string | Threads only: the post's topic tag, up to 50 characters. Up to 50 characters |
versions | NewVersion[] | An account's own text where it differs from |
versions[].connection_idrequired | string | The account this version is for: one of the draft's |
versions[].partsrequired | NewPart[] | That account's own thread, text only, 1 to 25 parts; media stays on the shared parts. 1–25 items |
versions[].parts[].text | string | The part's text, up to 25,000 characters (each network's own limit is checked at publish: |
Example
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>"]
}'{"post_id": "<post_id>", "preview_url": "<preview_url>"}Other responses
400The 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 version401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A 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 it429Rate 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.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
Example
curl "https://postory.io/api/v1/drafts/<post_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{"post_id": "<post_id>"}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
422A request parameter is not valid
429Rate limit spent; see Retry-After
PATCH /api/v1/drafts/{post_id}
Edit a draft: only what is sent changes; parts replaces the thread.
- Scope
postory:drafts - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
Request body
| Field | Type | Description |
|---|---|---|
community_id | string | X only: the id of a Community to post in. |
connection_ids | string[] | REPLACES the draft's accounts, the first primary; at most 10. Up to 10 items |
event_date | string | The post's slot on the Postory calendar (ISO 8601, UTC when it has no offset). Not a publish time: scheduling is |
first_comment | string | A reply to part 1 sent after the last part, by the post's X, Threads or Bluesky accounts only ( |
first_comment_delay_seconds | integer | Seconds after the last part before the first comment goes out: 0 (straight after) or 60-7200. From 0 to 7200 |
labels | string[] | REPLACES the post's labels by name ( |
parts | EditPart[] | REPLACES the thread: send every part to keep, each with the |
parts[].delay_seconds | integer | 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[].id | string | The part's |
parts[].media_ids | string[] | Omitted: the part keeps its media. A list (ids from |
parts[].text | string | 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_followers | boolean | X only, with |
topic_tag | string | Threads only: the post's topic tag, up to 50 characters. |
versions | EditVersion[] | Per account: |
versions[].connection_idrequired | string | The account this version is for: one of the draft's accounts. Up to 36 characters |
versions[].parts | NewPart[] | REPLACES that account's own thread, text only, 1 to 25 parts. 1–25 items |
versions[].parts[].text | string | The part's text, up to 25,000 characters (each network's own limit is checked at publish: |
versions[].use_shared_text | boolean |
|
Example
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>"}'{"post_id": "<post_id>", "preview_url": "<preview_url>"}Other responses
400The 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 version401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A 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 it429Rate limit spent; see Retry-After
DELETE /api/v1/drafts/{post_id}
Delete a draft permanently, with its attachments. POST …/archive is reversible.
- Scope
postory:drafts - Limit class
DELETE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
Example
curl -X DELETE "https://postory.io/api/v1/drafts/<post_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"deleted": true,
"id": "<post_id>",
"acting_as": {
"postory": "[email protected]",
"x": "yourhandle",
"label": "@yourhandle · X",
"plan": "free"
}
}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A request parameter is not valid
429Rate limit spent; see Retry-After
POST /api/v1/drafts/{post_id}/archive
Move a draft to the archive (restorable in Postory).
- Scope
postory:drafts - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
Example
curl -X POST "https://postory.io/api/v1/drafts/<post_id>/archive" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"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
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A request parameter is not valid
429Rate 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.
- Scope
postory:publish - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
Example
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>"}'{
"approval_url": "<approval_url>",
"confirmation_token": "<confirmation_token>",
"ok": true
}Other responses
400The 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 version401No API key, or an invalid or revoked one
402Not enough credits for this delivery; see
buy_url403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A 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 it429Rate 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.
- Scope
postory:publish - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
Idempotency-Key | header | string | Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours ( |
Request body
| Field | Type | Description |
|---|---|---|
allow_republish | boolean |
|
confirmation_tokenrequired | string | From |
connection_id | string | The account to publish to. Omitted: the account the token was issued for. Up to 36 characters |
idempotency_key | string | A UUID you choose: a retry with the same key answers the first result ( |
Example
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>"}'{"status": "<status>", "task_id": "<task_id>"}Other responses
400The 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 version401No API key, or an invalid or revoked one
402Not enough credits for this delivery; see
buy_url403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A 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 it429Rate 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.
- Scope
postory:publish - Limit class
WRITE - Success
201
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
Idempotency-Key | header | string | Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours ( |
Request body
| Field | Type | Description |
|---|---|---|
connection_id | string | With 2+ accounts on the draft: only this account (a |
idempotency_key | string | 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_atrequired | string | When to publish: ISO 8601 (UTC when it has no offset), 2 minutes to 30 days from now; or |
share_preview | boolean |
|
Example
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>"}'{
"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
400The 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 version401No API key, or an invalid or revoked one
402Not enough credits for this delivery; see
buy_url403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A 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 it429Rate 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.
- Scope
postory:drafts - Limit class
NONE - Success
200
Request body
| Field | Type | Description |
|---|---|---|
actionrequired | "archive" | "delete" |
|
itemsrequired | BulkDraftItem[] | 1 to 10 drafts, each |
items[].post_idrequired | string | The draft's |
Example
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>"}]}'{"applied": 0, "refused": 0}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
422A request parameter is not valid
429Rate limit spent; see Retry-After