Docs menuArchive

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.

  • Scopepostory:data
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 100 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
media_indexqueryinteger

Which image of the item's media_urls, from 0 (default 0).

At least 0

Example

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

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

410

Gone: the upload or link expired, or the file was not uploaded yet (upload_not_found)

413

The file is too large for the account or the plan

415

The file or the URL's answer is not an image or video this route takes (unsupported_media_type)

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

GET /api/v1/archive/posts

The user's own posts with their counts, newest first or by sort.

  • Scopepostory:data
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
limitqueryinteger

At most this many posts, 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 1024 characters
daysqueryinteger

Only the last days days (1-365250). Give days or since, not both.

sincequerystring

From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
untilquerystring

Up to this time: ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
qquerystring

Only items whose text has a word starting with this (case-insensitive; anywhere in the text for $, @, # and other punctuation).

Up to 200 characters
connection_idquerystring

The account: a connection_id from GET /accounts. Omitted: the default account, else the only one; 2+ accounts with an archive and no default: every one, one page newest first (accounts).

Up to 36 characters
include_totalqueryboolean

true adds total: how many items match the filters, not the page size.

sortquery"recent" | "views" | "likes" | "replies" | "reposts" | "engagement"

recent (default, newest first) or a count, highest first: views, likes, replies, reposts, engagement (likes + replies + reposts + quotes).

refreshqueryboolean

Default true: a stale archive is refreshed from the network first, free. false reads only what Postory already holds.

selectionquery"list" | "latest" | "unique"

list (default) pages the matches; latest answers the newest match only (no cursor); unique answers one identified item, selection.status matched, not_found or ambiguous (up to 5 candidates). latest and unique need sort=recent.

post_idquerystring

One post by its network's post id (a Bluesky AT-URI too) or its link.

Up to 200 characters

Example

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

GET /api/v1/archive/received-replies

Replies other people left under the account's posts (unanswered by default).

  • 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
unanswered_onlyqueryboolean

Default true: only replies the account has not answered; false lists answered ones too.

daysqueryinteger

Only the last days days (1-365250). Give days or since, not both.

sincequerystring

From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
untilquerystring

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_idquerystring

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_idquerystring

Only replies one import run saved.

Up to 36 characters
include_low_qualityqueryboolean

true also lists replies taken for spam (hidden by default).

under_my_posts_onlyqueryboolean

true: only replies under the account's own posts (on X a walk also reads those under its replies).

full_contextqueryboolean

true adds the thread above each reply and the post's whole text (otherwise 280 characters).

limitqueryinteger

At most this many replies, 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 1024 characters
refreshqueryboolean

Default true: a stale archive is refreshed from the network first, free. false reads only what Postory already holds.

selectionquery"list" | "latest" | "unique"

list (default) pages the matches; latest answers the newest match only (no cursor); unique answers one identified item, selection.status matched, not_found or ambiguous (up to 5 candidates).

qquerystring

Only items whose text has a word starting with this (case-insensitive; anywhere in the text for $, @, # and other punctuation).

Up to 200 characters
authorquerystring

Only replies by this handle: exact and whole, case-insensitive, a leading @ optional.

Up to 256 characters
reply_idquerystring

One received reply by its id or link.

Up to 200 characters

Example

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

GET /api/v1/archive/replies

The replies the user wrote, with the post each answered.

  • Scopepostory:data
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
limitqueryinteger

At most this many replies, 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 1024 characters
daysqueryinteger

Only the last days days (1-365250). Give days or since, not both.

sincequerystring

From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
untilquerystring

Up to this time: ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
qquerystring

Only items whose text has a word starting with this (case-insensitive; anywhere in the text for $, @, # and other punctuation). Matches the account's reply text.

Up to 200 characters
connection_idquerystring

The account: a connection_id from GET /accounts. Omitted: the default account, else the only one; 2+ accounts with an archive and no default: every one, one page newest first (accounts).

Up to 36 characters
include_totalqueryboolean

true adds total: how many items match the filters, not the page size.

full_parentqueryboolean

true: the answered post's whole text (otherwise its first 280 characters).

sortquery"recent" | "views" | "likes" | "replies" | "reposts" | "engagement"

recent (default, newest first) or a count, highest first: views, likes, replies, reposts, engagement (likes + replies + reposts + quotes).

parent_post_idquerystring

Only replies to this post: its parent.id.

Up to 100 characters
refreshqueryboolean

Default true: a stale archive is refreshed from the network first, free. false reads only what Postory already holds.

Example

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

GET /api/v1/archive/search/posts

The user's own posts closest in meaning to query, with their counts (limit up to 25).

  • Scopepostory:data
  • Limit classSEARCH
  • Success200

Parameters

NameInTypeDescription
queryrequiredquerystring

What to look for, in words: matched by meaning, not by spelling.

Up to 500 characters
limitqueryinteger

At most this many posts, 1-25 (default 10). A larger value is read as 25, 0 or less as 10.

min_similarityquerynumber

The lowest similarity kept, 0 to 1 (default 0.3); a value above 1 is a percentage (30 = 0.3).

daysqueryinteger

Only the last days days (1-365250). Give days or since, not both.

sincequerystring

From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
untilquerystring

Up to this time: ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
connection_idquerystring

The account: a connection_id from GET /accounts. Omitted: the default account, else the only one; 2+ accounts with an archive and no default: every one, hits ranked together (accounts).

Up to 36 characters
refreshqueryboolean

Default true: a stale archive is refreshed from the network first, free. false reads only what Postory already holds.

Example

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

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/archive/search/replies

The user's own replies closest in meaning to query, each with the post it answered (limit up to 25).

  • Scopepostory:data
  • Limit classSEARCH
  • Success200

Parameters

NameInTypeDescription
queryrequiredquerystring

What to look for, in words: matched by meaning, not by spelling.

Up to 500 characters
limitqueryinteger

At most this many replies, 1-25 (default 10). A larger value is read as 25, 0 or less as 10.

min_similarityquerynumber

The lowest similarity kept, 0 to 1 (default 0.3); a value above 1 is a percentage (30 = 0.3).

daysqueryinteger

Only the last days days (1-365250). Give days or since, not both.

sincequerystring

From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
untilquerystring

Up to this time: ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
connection_idquerystring

The account: a connection_id from GET /accounts. Omitted: the default account, else the only one; 2+ accounts with an archive and no default: every one, hits ranked together (accounts).

Up to 36 characters
refreshqueryboolean

Default true: a stale archive is refreshed from the network first, free. false reads only what Postory already holds.

Example

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

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

  • Scopepostory:data
  • Limit classSEARCH
  • Success200

Parameters

NameInTypeDescription
queryrequiredquerystring

What to look for, in words: matched by meaning, not by spelling.

Up to 500 characters
limitqueryinteger

At most this many answered posts, 1-15 (default 5). A larger value is read as 15, 0 or less as 5.

min_similarityquerynumber

The lowest similarity kept, 0 to 1 (default 0.3); a value above 1 is a percentage (30 = 0.3).

daysqueryinteger

Only the last days days (1-365250). Give days or since, not both.

sincequerystring

From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
untilquerystring

Up to this time: ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
connection_idquerystring

The account: a connection_id from GET /accounts. Omitted: the default account, else the only one; 2+ accounts with an archive and no default: every one, hits ranked together (accounts).

Up to 36 characters
refreshqueryboolean

Default true: a stale archive is refreshed from the network first, free. false reads only what Postory already holds.

Example

Request
curl "https://postory.io/api/v1/archive/search/replies-by-parent?query=<query>" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "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

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/archive/summary

What Postory holds for the account: counts, date range, last import, credits.

  • 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

Example

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

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

  • Scopepostory:data
  • Limit classSEARCH
  • Success200

Parameters

NameInTypeDescription
reply_idsquerystring[]

Up to 10 received replies by id (from GET /archive/received-replies); repeat the parameter for each. Give reply_ids, post_id or neither (the newest replies).

Up to 10 items
post_idquerystring

Only replies under this post of the account (an id or its link).

Up to 200 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
unanswered_onlyqueryboolean

Default true: only replies the account has not answered; false lists answered ones too.

daysqueryinteger

Only the last days days (1-365250). Give days or since, not both.

sincequerystring

From this time (inclusive): ISO 8601 date or date-time, UTC when it has no offset.

Up to 40 characters
untilquerystring

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_qualityqueryboolean

true also lists replies taken for spam (hidden by default).

under_my_posts_onlyqueryboolean

true: only replies under the account's own posts (on X a walk also reads those under its replies).

limitqueryinteger

At most this many replies, 1-10 (default 5). A larger value is read as 10, 0 or less as 5.

examples_per_replyqueryinteger

How many of the user's own past replies each item carries as style examples, 0-5 (default 5; 0 = none).

cursorquerystring

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

Up to 1024 characters
refreshqueryboolean

Default true: a stale archive is refreshed from the network first, free. false reads only what Postory already holds.

Example

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