Media
PATCH /api/v1/drafts/{post_id}/media/{media_id}
Set or clear one attachment's alt text (sent on X, Threads or Bluesky).
- Scope
postory:drafts - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
media_idrequired | path | string | Up to 36 characters |
Request body
| Field | Type | Description |
|---|---|---|
alt_text | string | The new alt text, up to 1000 characters; |
Example
curl -X PATCH "https://postory.io/api/v1/drafts/<post_id>/media/<media_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"alt_text": "<alt_text>"}'{
"draft": {
"id": "<post_id>",
"status": "draft",
"created_via": "api",
"connection_id": "<connection_id>",
"handle": "yourhandle",
"parts": [
{
"n": 1,
"id": null,
"media_ids": ["<media_id>"],
"chars": 26,
"limit": 25000,
"fits": true,
"advice": 280,
"over_advice": false
}
],
"share_with_followers": true,
"event_date": "2026-12-01T09:00:00+00:00",
"created_at": "2026-12-01T09:00:00+00:00",
"updated_at": "2026-12-01T09:00:00+00:00",
"delivered_to": [],
"schedules": [],
"validation": {"ok": true, "issues": [], "warnings": []},
"platform": "x",
"url": "https://postory.io/calendar?view=list&focus=<post_id>"
},
"media": {"id": "<media_id>", "alt_text": "A lake below a mountain"},
"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
DELETE /api/v1/drafts/{post_id}/media/{media_id}
Delete one attachment from a draft (the stored file too).
- Scope
postory:drafts - Limit class
DELETE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
media_idrequired | path | string | Up to 36 characters |
Example
curl -X DELETE "https://postory.io/api/v1/drafts/<post_id>/media/<media_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"draft": {
"id": "<post_id>",
"status": "draft",
"created_via": "api",
"connection_id": "<connection_id>",
"handle": "yourhandle",
"parts": [
{
"n": 1,
"id": null,
"media_ids": [],
"chars": 26,
"limit": 25000,
"fits": true,
"advice": 280,
"over_advice": false
}
],
"share_with_followers": true,
"event_date": "2026-12-01T09:00:00+00:00",
"created_at": "2026-12-01T09:00:00+00:00",
"updated_at": "2026-12-01T09:00:00+00:00",
"delivered_to": [],
"schedules": [],
"validation": {"ok": true, "issues": [], "warnings": []},
"platform": "x",
"url": "https://postory.io/calendar?view=list&focus=<post_id>"
},
"removed": {"id": "<media_id>"},
"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
POST /api/v1/drafts/{post_id}/media/from-library
Copy a media-library file onto a draft part (the library keeps it). The same file already on that part answers that attachment with duplicate: true, its alt unchanged even when alt_text is given. Without alt_text the attachment takes the file's own alt.
- Scope
postory:drafts - Limit class
MEDIA - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
Request body
| Field | Type | Description |
|---|---|---|
alt_text | string | Alt text for screen readers, up to 1000 characters; sent with the post on X, Threads or Bluesky. Omitted: the library file's own alt. Up to 1000 characters |
asset_idrequired | string | The library file: an |
part | integer | The 1-based thread part to attach to (default 1); the part must exist. From 1 to 25 |
Example
curl "https://postory.io/api/v1/drafts/<post_id>/media/from-library" \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"asset_id": "<asset_id>"}'{
"draft": {
"id": "<post_id>",
"status": "draft",
"created_via": "api",
"connection_id": "<connection_id>",
"handle": "yourhandle",
"parts": [
{
"n": 1,
"id": null,
"media_ids": ["<media_id>"],
"chars": 26,
"limit": 25000,
"fits": true,
"advice": 280,
"over_advice": false
}
],
"share_with_followers": true,
"event_date": "2026-12-01T09:00:00+00:00",
"created_at": "2026-12-01T09:00:00+00:00",
"updated_at": "2026-12-01T09:00:00+00:00",
"delivered_to": [],
"schedules": [],
"validation": {"ok": true, "issues": [], "warnings": []},
"platform": "x",
"url": "https://postory.io/calendar?view=list&focus=<post_id>"
},
"media": {
"id": "<media_id>",
"part": 1,
"type": "image",
"mime_type": "image/jpeg",
"size_bytes": 44891,
"file_name": "lake.jpg",
"url": "<media_url>",
"alt_text": "Mountain lake"
},
"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
code413The file is too large for the account or the plan
422A request parameter is not valid
429Rate limit spent; see Retry-After
POST /api/v1/drafts/{post_id}/media/from-url
Fetch an image or video from a public https:// URL onto a draft part.
- Scope
postory:drafts - Limit class
MEDIA - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
post_idrequired | path | string | Up to 36 characters |
Request body
| Field | Type | Description |
|---|---|---|
alt_text | string | Alt text for screen readers, up to 1000 characters; sent with the post on X, Threads or Bluesky. Up to 1000 characters |
file_name | string | The name to store the file under; omitted, it is taken from the URL. Up to 120 characters |
part | integer | The 1-based thread part to attach to (default 1); the part must exist. From 1 to 25 |
urlrequired | string | A public |
Example
curl "https://postory.io/api/v1/drafts/<post_id>/media/from-url" \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "<url>"}'{
"draft": {
"id": "<post_id>",
"status": "draft",
"created_via": "api",
"connection_id": "<connection_id>",
"handle": "yourhandle",
"parts": [
{
"n": 1,
"id": null,
"media_ids": ["<media_id>"],
"chars": 26,
"limit": 25000,
"fits": true,
"advice": 280,
"over_advice": false
}
],
"share_with_followers": true,
"event_date": "2026-12-01T09:00:00+00:00",
"created_at": "2026-12-01T09:00:00+00:00",
"updated_at": "2026-12-01T09:00:00+00:00",
"delivered_to": [],
"schedules": [],
"validation": {"ok": true, "issues": [], "warnings": []},
"platform": "x",
"url": "https://postory.io/calendar?view=list&focus=<post_id>"
},
"media": {
"id": "<media_id>",
"part": 1,
"type": "image",
"mime_type": "image/jpeg",
"size_bytes": 44891,
"file_name": "lake.jpg",
"url": "<media_url>",
"alt_text": "Mountain lake"
},
"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
code413The 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
POST /api/v1/media
Start an upload to a draft part: answers a presigned PUT URL (send the bytes with the given Content-Type), then call attach. Images: JPEG, PNG, WEBP, GIF up to 8 MB; video: MP4 or MOV within the plan's and the accounts' caps. Idempotency-Key replays the first answer for 24 hours, so a retry reserves no second upload.
- Scope
postory:drafts - Limit class
MEDIA - Success
201
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours ( |
Request body
| Field | Type | Description |
|---|---|---|
alt_text | string | Alt text for screen readers, up to 1000 characters; sent with the post on X, Threads or Bluesky. Up to 1000 characters |
file_namerequired | string | The file's name, up to 120 characters (cleaned for storage). Up to 120 characters |
file_sizerequired | integer | The file's size in bytes. Images up to 8 MB; videos within the accounts' and the plan's caps. The attach checks the stored size again. |
mime_typerequired | "image/jpeg" | "image/png" | "image/webp" | "image/gif" | "video/mp4" | "video/quicktime" | The file's type, also the |
part | integer | The 1-based thread part to attach to (default 1); the part must exist. From 1 to 25 |
post_idrequired | string | The draft to attach to (its |
Example
curl https://postory.io/api/v1/media \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Idempotency-Key: <unique-key>" \
-H "Content-Type: application/json" \
-d '{
"post_id": "<post_id>",
"file_name": "photo.jpg",
"mime_type": "image/jpeg",
"file_size": 184320
}'{"media_id": "<media_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
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code413The file is too large for the account or the plan
422A request parameter is not valid
429Rate limit spent; see Retry-After
GET /api/v1/media-library
The user's media library, newest first: each file's id (what from-library takes), name, type, size, alt and how many posts hold a copy, its folder (absent = none), plus usage (files, bytes, max_bytes: null = no limit) and, on the first page, the user's folders. q filters by file name, folder by folder; page with cursor. Library files are deleted only in the Postory web app.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
q | query | string | Only files whose name contains this. Up to 120 characters |
folder | query | string | Only files in this folder. A media-library folder: its |
limit | query | integer | At most this many files, 1-60 (default 20). A larger value is read as 60, 0 or less as 20. |
cursor | query | string |
|
Example
curl https://postory.io/api/v1/media-library \
-H "Authorization: Bearer $POSTORY_API_KEY"{"has_more": true, "next_cursor": "<next_cursor>", "total": 0}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
POST /api/v1/media-library
Save a draft attachment (media_id, image or video) to the media library. duplicate: true: its bytes joined a file already there, taking no room; an attachment already in the library answers its file with duplicate: false. No room: 429 media_library_full with metric, current and limit.
- Scope
postory:drafts - Limit class
MEDIA - Success
200
Request body
| Field | Type | Description |
|---|---|---|
folder | string | A media-library folder: its |
media_idrequired | string | The draft attachment to save: |
Example
curl https://postory.io/api/v1/media-library \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"media_id": "<media_id>"}'{"duplicate": true}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
429No room in the media library (
media_library_full:metric,current,limit), or rate limit spent; see Retry-After
POST /api/v1/media/{media_id}/attach
Attach an uploaded file to its part once the PUT is done.
- Scope
postory:drafts - Limit class
NONE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
media_idrequired | path | string | Up to 36 characters |
Example
curl -X POST "https://postory.io/api/v1/media/<media_id>/attach" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"draft": {
"id": "<post_id>",
"status": "draft",
"created_via": "api",
"connection_id": "<connection_id>",
"handle": "yourhandle",
"parts": [
{
"n": 1,
"id": null,
"media_ids": ["<media_id>"],
"chars": 26,
"limit": 25000,
"fits": true,
"advice": 280,
"over_advice": false
}
],
"share_with_followers": true,
"event_date": "2026-12-01T09:00:00+00:00",
"created_at": "2026-12-01T09:00:00+00:00",
"updated_at": "2026-12-01T09:00:00+00:00",
"delivered_to": [],
"schedules": [],
"validation": {"ok": true, "issues": [], "warnings": []},
"platform": "x",
"url": "https://postory.io/calendar?view=list&focus=<post_id>"
},
"media": {
"id": "<media_id>",
"part": 1,
"type": "image",
"mime_type": "image/png",
"size_bytes": 184320,
"file_name": "photo.png",
"url": "<media_url>",
"alt_text": 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
code410Gone: 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
422A request parameter is not valid
429Rate limit spent; see Retry-After