Imports
GET /api/v1/imports
Import, update and scan runs, newest first.
- Scope
postory:data - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
connection_id | query | string | The account: a |
limit | query | integer | At most this many runs, 1-50 (default 20). A larger value is read as 50, 0 or less as 20. |
cursor | query | string |
|
kind | query | "connect" | "import" | "update" | "scan" | "voice_refresh" | "reset" | Only runs of this kind: |
trigger | query | "user" | "auto" | "mcp" | "mcp_auto" | "admin" | "scan" | Only runs started this way: |
Example
curl https://postory.io/api/v1/imports \
-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
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.
- Scope
postory:import - Limit class
IMPORT - Success
200
Request body
| Field | Type | Description |
|---|---|---|
confirmation_token | string | From |
connection_id | string | The account (a |
days | integer |
|
mode | "update" | "import" | "metrics" | Without a token: |
post_ids | string[] | Up to 5 posts of this account (ids or links), with |
streams | "posts" | "replies" | "received_replies"[] | Which data: |
wait_s | integer | Seconds to wait for the run to finish before answering, up to 25 (default 25; 0 answers at once). |
Example
curl https://postory.io/api/v1/imports \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"confirmation_token": "<confirmation_token>"}'{"status": "<status>"}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
GET /api/v1/imports/{run_id}
One run's status and counts; wait_s waits for it to finish, briefly.
- Scope
postory:data - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
run_idrequired | path | string | Up to 36 characters |
wait_s | query | integer | Seconds to wait for the run to finish before answering, 0-25 (default 0). |
Example
curl "https://postory.io/api/v1/imports/<run_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/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.
- Scope
postory:import - Limit class
DELETE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
run_idrequired | path | string | Up to 36 characters |
Example
curl -X POST "https://postory.io/api/v1/imports/<run_id>/cancel" \
-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
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/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.
- Scope
postory:import - Limit class
IMPORT - Success
200
Request body
| Field | Type | Description |
|---|---|---|
connection_id | string | The account (a |
moderequired | "update" | "import" |
|
post_ids | string[] | Up to 5 posts of this account (ids or links), with |
posts_count | integer |
|
received_replies_count | integer |
|
replies_count | integer |
|
streams | "posts" | "replies" | "received_replies"[] | Which data: |
Example
curl https://postory.io/api/v1/imports/quote \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode": "update"}'{"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
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).
- Scope
postory:import - Limit class
WRITE - Success
200
Request body
| Field | Type | Description |
|---|---|---|
autoupdate_enabled | boolean | Turn the automatic updates on or off. Turning them on clears a pause after failed runs. |
autoupdate_interval_days | integer | 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: |
connection_id | string | The account (a |
rewrite_existing | boolean |
|
Example
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}'{
"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
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