Docs menuMedia

Media

PATCH /api/v1/drafts/{post_id}/media/{media_id}

Set or clear one attachment's alt text (sent on X, Threads or Bluesky).

  • Scopepostory:drafts
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters
media_idrequiredpathstringUp to 36 characters

Request body

FieldTypeDescription
alt_textstring

The new alt text, up to 1000 characters; null or "" clears it.

Up to 1000 characters

Example

Request
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>"}'
Response 200
{
  "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

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

DELETE /api/v1/drafts/{post_id}/media/{media_id}

Delete one attachment from a draft (the stored file too).

  • Scopepostory:drafts
  • Limit classDELETE
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters
media_idrequiredpathstringUp to 36 characters

Example

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

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

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.

  • Scopepostory:drafts
  • Limit classMEDIA
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters

Request body

FieldTypeDescription
alt_textstring

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_idrequiredstring

The library file: an id from GET /media-library.

Up to 36 characters
partinteger

The 1-based thread part to attach to (default 1); the part must exist.

From 1 to 25

Example

Request
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>"}'
Response 200
{
  "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

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

413

The file is too large for the account or the plan

422

A request parameter is not valid

429

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

  • Scopepostory:drafts
  • Limit classMEDIA
  • Success200

Parameters

NameInTypeDescription
post_idrequiredpathstringUp to 36 characters

Request body

FieldTypeDescription
alt_textstring

Alt text for screen readers, up to 1000 characters; sent with the post on X, Threads or Bluesky.

Up to 1000 characters
file_namestring

The name to store the file under; omitted, it is taken from the URL.

Up to 120 characters
partinteger

The 1-based thread part to attach to (default 1); the part must exist.

From 1 to 25
urlrequiredstring

A public https:// link to the image or video file itself (not a page showing it), on a domain name: no IP addresses, logins or private hosts.

Up to 2048 characters

Example

Request
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>"}'
Response 200
{
  "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

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

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

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.

  • Scopepostory:drafts
  • Limit classMEDIA
  • Success201

Parameters

NameInTypeDescription
Idempotency-Keyheaderstring

Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours (Idempotent-Replayed: true) without running anything again; the same key with a different request is 409 idempotency_conflict.

Up to 255 characters

Request body

FieldTypeDescription
alt_textstring

Alt text for screen readers, up to 1000 characters; sent with the post on X, Threads or Bluesky.

Up to 1000 characters
file_namerequiredstring

The file's name, up to 120 characters (cleaned for storage).

Up to 120 characters
file_sizerequiredinteger

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 Content-Type of the PUT: JPEG, PNG, WEBP, GIF, MP4 or MOV.

partinteger

The 1-based thread part to attach to (default 1); the part must exist.

From 1 to 25
post_idrequiredstring

The draft to attach to (its post_id); a scheduled, delivered or mid-delivery post is refused.

Up to 36 characters

Example

Request
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
  }'
Response 201
{"media_id": "<media_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

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

413

The file is too large for the account or the plan

422

A request parameter is not valid

429

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

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
qquerystring

Only files whose name contains this.

Up to 120 characters
folderquerystring

Only files in this folder. A media-library folder: its id or name (from folders in GET /media-library), or root for files in no folder.

Up to 100 characters
limitqueryinteger

At most this many files, 1-60 (default 20). A larger value is read as 60, 0 or less as 20.

cursorquerystring

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

Up to 512 characters

Example

Request
curl https://postory.io/api/v1/media-library \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{"has_more": true, "next_cursor": "<next_cursor>", "total": 0}

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

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.

  • Scopepostory:drafts
  • Limit classMEDIA
  • Success200

Request body

FieldTypeDescription
folderstring

A media-library folder: its id or name (from folders in GET /media-library), or root for files in no folder. Files the saved file there, one already in the library too.

Up to 100 characters
media_idrequiredstring

The draft attachment to save: parts[n].media[].id from GET /drafts/{post_id}.

Up to 36 characters

Example

Request
curl https://postory.io/api/v1/media-library \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "<media_id>"}'
Response 200
{"duplicate": true}

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

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

  • Scopepostory:drafts
  • Limit classNONE
  • Success200

Parameters

NameInTypeDescription
media_idrequiredpathstringUp to 36 characters

Example

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

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

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

422

A request parameter is not valid

429

Rate limit spent; see Retry-After