Docs menuImports

Imports

GET /api/v1/imports

Import, update and scan runs, newest first.

  • Scopepostory:data
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
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
limitqueryinteger

At most this many runs, 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
kindquery"connect" | "import" | "update" | "scan" | "voice_refresh" | "reset"

Only runs of this kind: connect, import, update, scan, voice_refresh or reset.

triggerquery"user" | "auto" | "mcp" | "mcp_auto" | "admin" | "scan"

Only runs started this way: user (the Postory app), auto (the schedule), mcp (an AI app or an API key), mcp_auto (a read that refreshed a stale archive), admin or scan.

Example

Request
curl https://postory.io/api/v1/imports \
  -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

POST /api/v1/imports

Start an import with the quote's confirmation_token, or a refresh with mode: update (metrics: fresh counts only) and no token. Credits are charged for what it saves; wait_s waits for the run briefly, and GET /imports/{run_id} follows it.

  • Scopepostory:import
  • Limit classIMPORT
  • Success200

Request body

FieldTypeDescription
confirmation_tokenstring

From POST /imports/quote, after the user's yes (single-use, 10 minutes); it starts what was quoted. Send it or mode, not both.

Up to 128 characters
connection_idstring

The account (a connection_id from GET /accounts). Omitted: the default account, else the only one.

Up to 36 characters
daysinteger

mode: metrics: re-read the counts of items published in the last days days, 1-90 (default 7).

mode"update" | "import" | "metrics"

Without a token: update (new items, fresh counts on the latest) or metrics (fresh counts only), started directly. import needs the quote's token.

post_idsstring[]

Up to 5 posts of this account (ids or links), with mode: update and streams: ["received_replies"] alone: walks only the replies under them.

Up to 5 items
streams"posts" | "replies" | "received_replies"[]

Which data: posts, replies (the account's own) and received_replies (other people's replies to its posts).

wait_sinteger

Seconds to wait for the run to finish before answering, up to 25 (default 25; 0 answers at once).

Example

Request
curl https://postory.io/api/v1/imports \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation_token": "<confirmation_token>"}'
Response 200
{"status": "<status>"}

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

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/imports/{run_id}

One run's status and counts; wait_s waits for it to finish, briefly.

  • Scopepostory:data
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
run_idrequiredpathstringUp to 36 characters
wait_squeryinteger

Seconds to wait for the run to finish before answering, 0-25 (default 0).

Example

Request
curl "https://postory.io/api/v1/imports/<run_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/imports/{run_id}/cancel

Stop a running import. One that has not called the network yet costs nothing; one mid-walk keeps every item it saved and settles at the 1-credit minimum. A finished run is 409 already_finished.

  • Scopepostory:import
  • Limit classDELETE
  • Success200

Parameters

NameInTypeDescription
run_idrequiredpathstringUp to 36 characters

Example

Request
curl -X POST "https://postory.io/api/v1/imports/<run_id>/cancel" \
  -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

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/imports/quote

Price an import or update and preview what it fetches; an import answer carries a single-use confirmation_token for POST /imports after the user's yes. Nothing is started or charged.

  • Scopepostory:import
  • Limit classIMPORT
  • Success200

Request body

FieldTypeDescription
connection_idstring

The account (a connection_id from GET /accounts). Omitted: the default account, else the only one.

Up to 36 characters
moderequired"update" | "import"

update walks each stream down to what Postory holds (new items, fresh counts on the latest); import fetches the latest N of each stream (its *_count).

post_idsstring[]

Up to 5 posts of this account (ids or links), with mode: update and streams: ["received_replies"] alone: walks only the replies under them.

Up to 5 items
posts_countinteger

mode: import: how many of the latest posts to fetch, up to 1,000 (a larger count is clamped and the preview says so).

received_replies_countinteger

mode: import: how many of the latest received replies to fetch, up to 1,000 (a larger count is clamped and the preview says so).

replies_countinteger

mode: import: how many of the latest replies to fetch, up to 1,000 (a larger count is clamped and the preview says so).

streams"posts" | "replies" | "received_replies"[]

Which data: posts, replies (the account's own) and received_replies (other people's replies to its posts).

Example

Request
curl https://postory.io/api/v1/imports/quote \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "update"}'
Response 200
{"confirmation_token": "<confirmation_token>"}

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

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

PATCH /api/v1/imports/settings

The account's auto-update: on or off, which streams, every 1, 3, 7, 14 or 30 days, and whether a run re-saves held items. Only what is sent changes; nothing is spent now (each scheduled X run spends credits on what it saves; Threads and Bluesky runs are free).

  • Scopepostory:import
  • Limit classWRITE
  • Success200

Request body

FieldTypeDescription
autoupdate_enabledboolean

Turn the automatic updates on or off. Turning them on clears a pause after failed runs.

autoupdate_interval_daysinteger

Days between updates: 1, 3, 7, 14 or 30 (another value snaps to the nearest).

autoupdate_streams"posts" | "replies" | "received_replies"[]

Which streams each update walks. Which data: posts, replies (the account's own) and received_replies (other people's replies to its posts).

connection_idstring

The account (a connection_id from GET /accounts). Omitted: the default account, else the only one.

Up to 36 characters
rewrite_existingboolean

true: every run re-saves items Postory already holds (text, media and counts); only new items are charged.

Example

Request
curl -X PATCH https://postory.io/api/v1/imports/settings \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoupdate_enabled": false}'
Response 200
{
  "account": {
    "id": "<connection_id>",
    "platform": "x",
    "handle": "yourhandle"
  },
  "settings": {
    "autoupdate_enabled": true,
    "autoupdate_streams": ["posts", "replies"],
    "autoupdate_interval_days": 7,
    "rewrite_existing": false,
    "next_run_at": "2026-11-26T17:00:00+00:00",
    "last_run_at": null,
    "paused_reason": null
  },
  "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