Docs menuSocial accounts

Social accounts

GET /api/v1/accounts

Every connected account, its limits and the default. limits.text_max is what the network accepts in one part from that account (a draft part's limit); an X account whose tier is not read yet also has text_advice (280): past it, X refuses the post unless the account has Premium.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Example

Request
curl https://postory.io/api/v1/accounts \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "accounts": [
    {
      "connection_id": "<connection_id>",
      "platform": "x",
      "handle": "yourhandle",
      "id": "<connection_id>",
      "label": "@yourhandle · X",
      "display_name": "Your Name",
      "is_default": false,
      "can_publish": true,
      "suspended": false,
      "needs_reconnect": false,
      "limits": {
        "text_max": 25000,
        "text_advice": 280,
        "text_unit": "characters",
        "max_parts": 25,
        "media": "per part up to 4 images, or 1 GIF, or 1 video up to 512 MB; no link in part 1"
      },
      "archive": {"posts": 0, "replies": 0}
    },
    {
      "id": "<connection_id>",
      "connection_id": "<connection_id>",
      "platform": "bluesky",
      "handle": "yourhandle.bsky.social",
      "label": "@yourhandle.bsky.social · Bluesky",
      "display_name": "Your Name",
      "is_default": false,
      "can_publish": true,
      "suspended": false,
      "needs_reconnect": false,
      "limits": {
        "text_max": 300,
        "text_unit": "graphemes",
        "max_parts": 25,
        "media": "per part up to 4 images or 1 video up to 100 MB, not mixed"
      },
      "archive": {"posts": 0, "replies": 0}
    }
  ],
  "default_account": null,
  "write_choice": "No account named and no default: a write needs connection_id (a draft: connection_ids), or set a default with PUT /api/v1/accounts/{connection_id}/default.",
  "hint_id": "write_choice",
  "acting_as": {"postory": "[email protected]", "plan": "free"}
}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

PUT /api/v1/accounts/{connection_id}/default

Make this account the default: the one every write and read uses when a request names no connection_id (in every AI app too). A request that names an account still wins.

  • Scopepostory:drafts
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
connection_idrequiredpathstringUp to 36 characters

Example

Request
curl -X PUT "https://postory.io/api/v1/accounts/<connection_id>/default" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "default_account": {
    "connection_id": "<connection_id>",
    "platform": "x",
    "handle": "yourhandle",
    "label": "@yourhandle · X"
  },
  "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

GET /api/v1/accounts/{connection_id}/slots

The account's next free posting slots. By default (queue=true) in the order POST /posts with mode: queue takes them (weekly: its slot times — saved, or its best hours, else 09:00, 13:00 and 18:00 — in tz); each is at least 2 minutes away, pace-clean, and within 30 days. queue=false: the soonest times the posting pace allows (10+ minutes apart, 30 per 24 hours), or with prefer_best_hours=true the free times in the hours the account's posts did best.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
connection_idrequiredpathstringUp to 36 characters
countqueryinteger

How many slots, 1-10 (default 5).

From 1 to 10
afterquerystring

Slots from this time: ISO 8601 (UTC when it has no offset), within 30 days (default now).

Up to 40 characters
queuequeryboolean

Default true: the queue's next free slots, as mode: queue takes them. false: the soonest times the posting pace allows.

prefer_best_hoursqueryboolean

With queue=false: true picks times in the hours the account's posts did best (90 days).

Example

Request
curl "https://postory.io/api/v1/accounts/<connection_id>/slots" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{"source": "<source>", "tz": "<tz>"}

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

DELETE /api/v1/accounts/default

Clear the default account: with 2+ accounts, a request that names none is refused account_choice_required until one is named or set.

  • Scopepostory:drafts
  • Limit classWRITE
  • Success200

Example

Request
curl -X DELETE https://postory.io/api/v1/accounts/default \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "default_account": null,
  "acting_as": {"postory": "[email protected]", "plan": "free"}
}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

422

A request parameter is not valid

429

Rate limit spent; see Retry-After