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.
- 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 |
confirm | boolean |
|
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 |
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 |
mode | "draft" | "schedule" | "queue" | "now" |
|
partsrequired | 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: |
scheduled_at | string |
|
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/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>"]
}'{
"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
202Accepted:
approval_required(openapproval_url) or a publish still in flight400The 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/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).
- Scope
postory:publish - Limit class
WRITE - Success
200
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 |
|---|---|---|
confirmation_token | string | 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_id | string | The account the replies were received on (a |
idempotency_key | string | 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 |
items | ReplyItem[] | The answers, 1 to 10, each |
items[].reply_torequired | string | The received reply to answer: an item's |
items[].textrequired | string | The answer's text, up to 25,000 characters. On X leave out a leading |
Example
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>"}'{
"approval_url": "<approval_url>",
"confirmation_token": "<confirmation_token>"
}Other responses
401No 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
429Rate limit spent; see Retry-After