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.
- Scope
postory:read - Limit class
READ - Success
200
Example
curl https://postory.io/api/v1/accounts \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"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
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
422A request parameter is not valid
429Rate 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.
- Scope
postory:drafts - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
connection_idrequired | path | string | Up to 36 characters |
Example
curl -X PUT "https://postory.io/api/v1/accounts/<connection_id>/default" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"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
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
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.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
connection_idrequired | path | string | Up to 36 characters |
count | query | integer | How many slots, 1-10 (default 5). From 1 to 10 |
after | query | string | Slots from this time: ISO 8601 (UTC when it has no offset), within 30 days (default now). Up to 40 characters |
queue | query | boolean | Default |
prefer_best_hours | query | boolean | With |
Example
curl "https://postory.io/api/v1/accounts/<connection_id>/slots" \
-H "Authorization: Bearer $POSTORY_API_KEY"{"source": "<source>", "tz": "<tz>"}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
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.
- Scope
postory:drafts - Limit class
WRITE - Success
200
Example
curl -X DELETE https://postory.io/api/v1/accounts/default \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"default_account": null,
"acting_as": {"postory": "[email protected]", "plan": "free"}
}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
422A request parameter is not valid
429Rate limit spent; see Retry-After
GET /api/v1/networks/{network}/connect-link
A link that opens Postory's connect flow on network (connect_url, Settings → Channels): a new account, or a revoked or expired one reconnected (reconnect names it). The user opens it in a browser signed in to Postory and signs in to the network there. GET /accounts then lists the account.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
networkrequired | path | "x" | "threads" | "bluesky" | "linkedin" | |
connection_id | query | string | An account on |
Example
curl "https://postory.io/api/v1/networks/<network>/connect-link" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"connect_url": "<connect_url>",
"label": "<label>",
"network": "<network>"
}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