Docs menuDeliveries

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.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
statusquery"active" | "failed" | "published" | "all"

active (default: queued or in flight, soonest first), failed, published or all (those three newest first).

connection_idquerystring

The account: a connection_id from GET /accounts. Omitted: the default account, else the only one; 2+ accounts and no default: every account in one list (accounts names them).

Up to 36 characters
sincequerystring

Only deliveries scheduled from this time (ISO 8601, UTC when no offset).

Up to 40 characters
untilquerystring

Only deliveries scheduled up to this time (ISO 8601, UTC when no offset); a bare date includes that whole day.

Up to 40 characters
limitqueryinteger

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

cursorquerystring

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

Up to 512 characters
tagquerystring

Only posts with this label (its name).

Up to 40 characters
includequery"drafts" | "published"[]

First page only: drafts adds drafts (the listed accounts' drafts dated in the range), published adds published (what went out in the range, publish-now too; no since: the 7 days before until).

Up to 2 items

Example

Request
curl https://postory.io/api/v1/deliveries \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "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

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

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.

  • Scopepostory:publish
  • Limit classDELETE
  • Success200

Parameters

NameInTypeDescription
scheduled_post_idrequiredpathstringUp to 36 characters

Example

Request
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}'
Response 200
{
  "scheduled_at": "<scheduled_at>",
  "scheduled_at_local": "<scheduled_at_local>",
  "status": "<status>"
}

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/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.

  • Scopepostory:publish
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
scheduled_post_idrequiredpathstringUp to 36 characters

Request body

FieldTypeDescription
scheduled_atrequiredstring

The new time: ISO 8601 (UTC when it has no offset), 2 minutes to 30 days from now.

Up to 40 characters

Example

Request
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>"}'
Response 200
{
  "previous_scheduled_at": "<previous_scheduled_at>",
  "scheduled_at": "<scheduled_at>",
  "scheduled_at_local": "<scheduled_at_local>",
  "scheduled_post_id": "<scheduled_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

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

GET /api/v1/deliveries/{task_id}

Where one publish stands: queued, publishing, published or failed, per part.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
task_idrequiredpathstringUp to 36 characters

Example

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

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

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.

  • Scopepostory:publish
  • Limit classWRITE
  • Success200

Request body

FieldTypeDescription
actionrequired"schedule" | "reschedule" | "cancel"

schedule queues drafts, reschedule re-times queued deliveries, cancel cancels them.

connection_idstring

schedule only: queue only this account of a several-account draft.

Up to 36 characters
itemsrequiredBulkDeliveryItem[]

1 to 10 items. schedule: {post_id, scheduled_at} ("next_slot" = the account's next free slot); reschedule: {scheduled_post_id, scheduled_at}; cancel: {scheduled_post_id, return_to_draft}.

1–10 items
items[].post_idstring

schedule: the draft's post_id.

Up to 36 characters
items[].return_to_draftboolean

cancel: default true, the post becomes an editable draft again.

Default: true
items[].scheduled_atstring

schedule and reschedule: ISO 8601 (UTC when it has no offset), 2 minutes to 30 days from now; schedule also takes "next_slot".

Up to 40 characters
items[].scheduled_post_idstring

reschedule and cancel: the queued delivery's id (GET /deliveries).

Up to 36 characters

Example

Request
curl https://postory.io/api/v1/deliveries/bulk \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "schedule"}'
Response 200
{"applied": 0, "refused": 0}

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

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

GET /api/v1/deliveries/published

Posts published through Postory between since and until.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
sincerequiredquerystring

From this send time (inclusive): ISO 8601 with an offset, or a date or date-time read in timezone.

Up to 40 characters
untilrequiredquerystring

Up to this send time (exclusive): ISO 8601 with an offset, or a date or date-time read in timezone.

Up to 40 characters
connection_idquerystring

The account: a connection_id from GET /accounts. Omitted: the default account, else the only one (2+ accounts and no default: 409 account_choice_required).

Up to 36 characters
timezonequerystring

An IANA time zone (e.g. Europe/Warsaw) for a since/until without an offset, daylight saving included; without it both need an offset.

Up to 64 characters
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

Example

Request
curl "https://postory.io/api/v1/deliveries/published?since=<since>&until=<until>" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{"has_more": true, "next_cursor": "<next_cursor>"}

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