Deliveries
GET /api/v1/deliveries
Scheduled and queued deliveries (default active), soonest first, of one account or, unnamed with 2+ and no default, of all of them. tag: only posts with that label. Each row names its account (connection_id, platform, handle), media_count, media_url and url; include adds the drafts and published posts of the same range.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
status | query | "active" | "failed" | "published" | "all" |
|
connection_id | query | string | The account: a |
since | query | string | Only deliveries scheduled from this time (ISO 8601, UTC when no offset). Up to 40 characters |
until | query | string | Only deliveries scheduled up to this time (ISO 8601, UTC when no offset); a bare date includes that whole day. Up to 40 characters |
limit | query | integer | At most this many deliveries, 1-100 (default 20). A larger value is read as 100, 0 or less as 20. |
cursor | query | string |
|
tag | query | string | Only posts with this label (its name). Up to 40 characters |
include | query | "drafts" | "published"[] | First page only: |
Example
curl https://postory.io/api/v1/deliveries \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"items": [
{
"id": "<scheduled_post_id>",
"post_id": "<post_id>",
"text": "Hello from the Postory API",
"part_count": 1,
"scheduled_at": "2026-12-01T09:00:00+00:00",
"status": "pending",
"mode": "auto",
"created_via": "api"
}
],
"has_more": false,
"account": {
"id": "<connection_id>",
"platform": "x",
"handle": "yourhandle"
},
"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
422A request parameter is not valid
429Rate limit spent; see Retry-After
POST /api/v1/deliveries/{scheduled_post_id}/cancel
Cancel a queued delivery. With return_to_draft (the default) the post becomes an editable draft again. Nothing is deleted or published.
- Scope
postory:publish - Limit class
DELETE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
scheduled_post_idrequired | path | string | Up to 36 characters |
Example
curl "https://postory.io/api/v1/deliveries/<scheduled_post_id>/cancel" \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"return_to_draft": true}'{
"scheduled_at": "<scheduled_at>",
"scheduled_at_local": "<scheduled_at_local>",
"status": "<status>"
}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/deliveries/{scheduled_post_id}/reschedule
Move a queued delivery to scheduled_at (2 minutes to 30 days away), keeping its text, media and price. Free; the posting pace is checked.
- Scope
postory:publish - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
scheduled_post_idrequired | path | string | Up to 36 characters |
Request body
| Field | Type | Description |
|---|---|---|
scheduled_atrequired | string | The new time: ISO 8601 (UTC when it has no offset), 2 minutes to 30 days from now. Up to 40 characters |
Example
curl "https://postory.io/api/v1/deliveries/<scheduled_post_id>/reschedule" \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scheduled_at": "<scheduled_at>"}'{
"previous_scheduled_at": "<previous_scheduled_at>",
"scheduled_at": "<scheduled_at>",
"scheduled_at_local": "<scheduled_at_local>",
"scheduled_post_id": "<scheduled_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
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
GET /api/v1/deliveries/{task_id}
Where one publish stands: queued, publishing, published or failed, per part.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
task_idrequired | path | string | Up to 36 characters |
Example
curl "https://postory.io/api/v1/deliveries/<task_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{"status": "<status>"}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
POST /api/v1/deliveries/bulk
Schedule, re-time or cancel 1-10 deliveries (times 2 minutes to 30 days away; a several-account draft is one delivery per account). A schedule batch the balance cannot cover queues nothing: 402 credit_limit with credits_needed and affordable. Credits are charged when each post publishes.
- Scope
postory:publish - Limit class
WRITE - Success
200
Request body
| Field | Type | Description |
|---|---|---|
actionrequired | "schedule" | "reschedule" | "cancel" |
|
connection_id | string |
|
itemsrequired | BulkDeliveryItem[] | 1 to 10 items. |
items[].post_id | string |
|
items[].return_to_draft | boolean |
|
items[].scheduled_at | string |
|
items[].scheduled_post_id | string |
|
Example
curl https://postory.io/api/v1/deliveries/bulk \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action": "schedule"}'{"applied": 0, "refused": 0}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
422A request parameter is not valid
429Rate limit spent; see Retry-After
GET /api/v1/deliveries/published
Posts published through Postory between since and until.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sincerequired | query | string | From this send time (inclusive): ISO 8601 with an offset, or a date or date-time read in |
untilrequired | query | string | Up to this send time (exclusive): ISO 8601 with an offset, or a date or date-time read in |
connection_id | query | string | The account: a |
timezone | query | string | An IANA time zone (e.g. |
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 |
|
Example
curl "https://postory.io/api/v1/deliveries/published?since=<since>&until=<until>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{"has_more": true, "next_cursor": "<next_cursor>"}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