Archive
GET /api/v1/archive/media/{post_id}
One image of a saved post, reply or received reply (post_id: its platform id; media_index selects media_urls, from 0): the verified media_url and the image itself (data_base64, at most 8 MB). Videos are refused 415 unsupported_media_type.
- Scope
postory:data - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 100 characters |
connection_id | query | string | The account: a |
media_index | query | integer | Which image of the item's |
Example
curl "https://postory.io/api/v1/archive/media/<post_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"connection_id": "<connection_id>",
"data_base64": "<data_base64>",
"media_index": 0,
"media_url": "<media_url>",
"mime_type": "<mime_type>",
"post_id": "<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
410Gone: the upload or link expired, or the file was not uploaded yet (
upload_not_found)413The file is too large for the account or the plan
415The file or the URL's answer is not an image or video this route takes (
unsupported_media_type)422A request parameter is not valid
429Rate limit spent; see Retry-After
GET /api/v1/archive/posts
The user's own posts with their counts, newest first or by sort.
- Scope
postory:data - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integer | At most this many posts, 1-100 (default 20). A larger value is read as 100, 0 or less as 20. |
cursor | query | string |
|
days | query | integer | Only the last |
since | query | string | From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
until | query | string | Up to this time: ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
q | query | string | Only items whose text has a word starting with this (case-insensitive; anywhere in the text for |
connection_id | query | string | The account: a |
include_total | query | boolean |
|
sort | query | "recent" | "views" | "likes" | "replies" | "reposts" | "engagement" |
|
refresh | query | boolean | Default |
selection | query | "list" | "latest" | "unique" |
|
post_id | query | string | One post by its network's post id (a Bluesky AT-URI too) or its link. Up to 200 characters |
Example
curl https://postory.io/api/v1/archive/posts \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"accounts_note": "<accounts_note>",
"freshness_note": "<freshness_note>",
"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
GET /api/v1/archive/received-replies
Replies other people left under the account's posts (unanswered by default).
- Scope
postory:data - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
connection_id | query | string | The account: a |
unanswered_only | query | boolean | Default |
days | query | integer | Only the last |
since | query | string | From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
until | query | string | Up to this time: ISO 8601 date or date-time, UTC when it has no offset. The end is exclusive. Up to 40 characters |
post_id | query | string | Only replies under this post or thread of the account (an id or a link); on Threads and Bluesky its replies are fetched first, free. Up to 200 characters |
run_id | query | string | Only replies one import run saved. Up to 36 characters |
include_low_quality | query | boolean |
|
under_my_posts_only | query | boolean |
|
full_context | query | boolean |
|
limit | query | integer | At most this many replies, 1-50 (default 20). A larger value is read as 50, 0 or less as 20. |
cursor | query | string |
|
refresh | query | boolean | Default |
selection | query | "list" | "latest" | "unique" |
|
q | query | string | Only items whose text has a word starting with this (case-insensitive; anywhere in the text for |
author | query | string | Only replies by this handle: exact and whole, case-insensitive, a leading |
reply_id | query | string | One received reply by its id or link. Up to 200 characters |
Example
curl https://postory.io/api/v1/archive/received-replies \
-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
GET /api/v1/archive/replies
The replies the user wrote, with the post each answered.
- Scope
postory:data - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integer | At most this many replies, 1-100 (default 20). A larger value is read as 100, 0 or less as 20. |
cursor | query | string |
|
days | query | integer | Only the last |
since | query | string | From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
until | query | string | Up to this time: ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
q | query | string | Only items whose text has a word starting with this (case-insensitive; anywhere in the text for |
connection_id | query | string | The account: a |
include_total | query | boolean |
|
full_parent | query | boolean |
|
sort | query | "recent" | "views" | "likes" | "replies" | "reposts" | "engagement" |
|
parent_post_id | query | string | Only replies to this post: its |
refresh | query | boolean | Default |
Example
curl https://postory.io/api/v1/archive/replies \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"accounts_note": "<accounts_note>",
"freshness_note": "<freshness_note>",
"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
GET /api/v1/archive/search/posts
The user's own posts closest in meaning to query, with their counts (limit up to 25).
- Scope
postory:data - Limit class
SEARCH - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
queryrequired | query | string | What to look for, in words: matched by meaning, not by spelling. Up to 500 characters |
limit | query | integer | At most this many posts, 1-25 (default 10). A larger value is read as 25, 0 or less as 10. |
min_similarity | query | number | The lowest similarity kept, 0 to 1 (default 0.3); a value above 1 is a percentage (30 = 0.3). |
days | query | integer | Only the last |
since | query | string | From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
until | query | string | Up to this time: ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
connection_id | query | string | The account: a |
refresh | query | boolean | Default |
Example
curl "https://postory.io/api/v1/archive/search/posts?query=<query>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"items": [
{
"id": "1862000000000000001",
"text": "Shipped dark mode today. Took three tries to get the contrast right.",
"timestamp": "2026-11-17T17:15:00+00:00",
"permalink": "https://x.com/yourhandle/status/1862000000000000001",
"views": 1830,
"likes": 42,
"replies": 3,
"reposts": 6,
"quotes": 0,
"metrics_as_of": "2026-11-19T14:00:00+00:00",
"similarity": 0.56
}
],
"limit_reached": true,
"freshness": {
"stale": true,
"metrics_refreshed_at": null,
"posts": {
"last_import_at": "2026-11-19T14:00:00+00:00",
"age_hours": 3,
"age_minutes": 180
},
"hint": "Posts were last imported 3 h ago. Postory refreshes stale data during a read, at no charge; no refresh landed for this one, so this is the archive as it was. Tell the user when the data was last refreshed."
},
"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
GET /api/v1/archive/search/replies
The user's own replies closest in meaning to query, each with the post it answered (limit up to 25).
- Scope
postory:data - Limit class
SEARCH - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
queryrequired | query | string | What to look for, in words: matched by meaning, not by spelling. Up to 500 characters |
limit | query | integer | At most this many replies, 1-25 (default 10). A larger value is read as 25, 0 or less as 10. |
min_similarity | query | number | The lowest similarity kept, 0 to 1 (default 0.3); a value above 1 is a percentage (30 = 0.3). |
days | query | integer | Only the last |
since | query | string | From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
until | query | string | Up to this time: ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
connection_id | query | string | The account: a |
refresh | query | boolean | Default |
Example
curl "https://postory.io/api/v1/archive/search/replies?query=<query>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"items": [
{
"id": "1863000000000000001",
"text": "We use a weekly batch on Mondays, it works.",
"timestamp": "2026-11-16T17:15:00+00:00",
"permalink": "https://x.com/yourhandle/status/1863000000000000001",
"views": 0,
"likes": 4,
"replies": 0,
"reposts": 0,
"quotes": 0,
"parent": {
"id": "1861000000000000001",
"text": "How do you plan your posts each week?",
"timestamp": "2026-11-15T17:15:00+00:00",
"author_username": "someone",
"author_display_name": "Someone"
},
"is_nested": false,
"metrics_as_of": "2026-11-19T14:00:00+00:00",
"similarity": 0.443
}
],
"limit_reached": true,
"freshness": {
"stale": true,
"metrics_refreshed_at": null,
"replies": {
"last_import_at": "2026-11-19T14:00:00+00:00",
"age_hours": 3,
"age_minutes": 180
},
"hint": "Your replies were last imported 3 h ago. Postory refreshes stale data during a read, at no charge; no refresh landed for this one, so this is the archive as it was. Tell the user when the data was last refreshed."
},
"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
GET /api/v1/archive/search/replies-by-parent
Posts the user replied to whose text is closest in meaning to query, each with the user's replies (limit counts posts, up to 15).
- Scope
postory:data - Limit class
SEARCH - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
queryrequired | query | string | What to look for, in words: matched by meaning, not by spelling. Up to 500 characters |
limit | query | integer | At most this many answered posts, 1-15 (default 5). A larger value is read as 15, 0 or less as 5. |
min_similarity | query | number | The lowest similarity kept, 0 to 1 (default 0.3); a value above 1 is a percentage (30 = 0.3). |
days | query | integer | Only the last |
since | query | string | From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
until | query | string | Up to this time: ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
connection_id | query | string | The account: a |
refresh | query | boolean | Default |
Example
curl "https://postory.io/api/v1/archive/search/replies-by-parent?query=<query>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"items": [
{
"parent": {
"id": "1861000000000000001",
"text": "How do you plan your posts each week?",
"timestamp": "2026-11-15T17:15:00+00:00",
"author_username": "someone",
"author_display_name": "Someone"
},
"similarity": 0.339,
"replies": [
{
"id": "1863000000000000001",
"text": "We use a weekly batch on Mondays, it works.",
"timestamp": "2026-11-16T17:15:00+00:00",
"permalink": "https://x.com/yourhandle/status/1863000000000000001",
"views": 0,
"likes": 4,
"replies": 0,
"reposts": 0,
"quotes": 0,
"is_nested": false,
"metrics_as_of": "2026-11-19T14:00:00+00:00"
}
],
"replies_total": 1,
"replies_truncated": false
}
],
"limit_reached": true,
"freshness": {
"stale": true,
"metrics_refreshed_at": null,
"replies": {
"last_import_at": "2026-11-19T14:00:00+00:00",
"age_hours": 3,
"age_minutes": 180
},
"hint": "Your replies were last imported 3 h ago. Postory refreshes stale data during a read, at no charge; no refresh landed for this one, so this is the archive as it was. Tell the user when the data was last refreshed."
},
"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
GET /api/v1/archive/summary
What Postory holds for the account: counts, date range, last import, credits.
- Scope
postory:data - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
connection_id | query | string | The account: a |
Example
curl https://postory.io/api/v1/archive/summary \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"accounts": [
{
"id": "<connection_id>",
"platform": "x",
"handle": "yourhandle",
"last_updated_at": "2026-11-18T17:15:00+00:00",
"posts": {
"total": 4,
"oldest_at": "2026-11-08T17:15:00+00:00",
"newest_at": "2026-11-17T17:15:00+00:00",
"without_metrics": 0
},
"replies": {
"total": 3,
"oldest_at": "2026-11-14T17:15:00+00:00",
"newest_at": "2026-11-18T17:15:00+00:00",
"without_metrics": 0
},
"received_replies": {
"total": 0,
"oldest_at": null,
"newest_at": null
},
"voice_refreshed_at": null,
"freshness": {
"posts": {
"last_import_at": "2026-11-19T14:00:00+00:00",
"age_hours": 3,
"stale": true,
"newest_saved_at": "2026-11-17T17:15:00+00:00",
"metrics_refreshed_at": null
},
"replies": {
"last_import_at": "2026-11-19T14:00:00+00:00",
"age_hours": 3,
"stale": true,
"newest_saved_at": "2026-11-18T17:15:00+00:00",
"metrics_refreshed_at": null
},
"received_replies": {
"last_import_at": "2026-11-19T14:00:00+00:00",
"age_hours": 3,
"stale": true
},
"stale": true
},
"last_run": {
"id": "<run_id>",
"kind": "import",
"trigger": "mcp_auto",
"mode": "update",
"status": "completed",
"completed_at": "2026-11-19T14:00:00+00:00",
"new": {"replies": 0},
"credits_charged": 0
},
"active_run": null,
"autoupdate": {
"enabled": true,
"interval_days": 7,
"streams": ["posts", "replies"],
"next_run_at": "2026-11-26T17:00:00+00:00",
"last_run_at": "2026-11-19T14:00:00+00:00",
"paused_reason": null
},
"rewrite_existing": false,
"can_import": {"ok": true, "reason": null},
"credits_available": 50
}
],
"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
GET /api/v1/replies-to-answer
Received replies worth answering, each with the user's own past replies closest to it as style examples, ready to draft answers for POST /api/v1/replies.
- Scope
postory:data - Limit class
SEARCH - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
reply_ids | query | string[] | Up to 10 received replies by id (from |
post_id | query | string | Only replies under this post of the account (an id or its link). Up to 200 characters |
connection_id | query | string | The account: a |
unanswered_only | query | boolean | Default |
days | query | integer | Only the last |
since | query | string | From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset. Up to 40 characters |
until | query | string | Up to this time: ISO 8601 date or date-time, UTC when it has no offset. The end is exclusive. Up to 40 characters |
include_low_quality | query | boolean |
|
under_my_posts_only | query | boolean |
|
limit | query | integer | At most this many replies, 1-10 (default 5). A larger value is read as 10, 0 or less as 5. |
examples_per_reply | query | integer | How many of the user's own past replies each item carries as style examples, 0-5 (default 5; 0 = none). |
cursor | query | string |
|
refresh | query | boolean | Default |
Example
curl https://postory.io/api/v1/replies-to-answer \
-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