Media

Media collections hold one or more renditions for a publication. Use external media when rendition URLs are already hosted elsewhere. Use the managed upload flow when the service should reserve, receive, and complete managed rendition uploads.

Authentication

Every route requires a bearer token and the listed publication capability. Lists and new media require a publication selector. Existing media_id values identify the publication; an accompanying selector must match.

Routes

Route	Methods	Capability	Required input	Optional input and behavior	Success result
/media/list	GET, POST	media.list	Publication selector	state, kind, pagination	Paginated media_items.
/media/get	POST	media.list	media_id	Matching publication selector	media.
/media/external/save	POST	media.save	Create: publication selector, kind, renditions; update: media_id, kind	Shared media fields	Saved ready media.
/media/managed/reserve	POST	media.save	Create: publication selector, kind, managed rendition data; update: media_id, kind	Shared media fields	Reserved media.
/media/managed/save	POST	media.save	media_id, kind	Shared media fields and managed rendition updates	Saved media.
/media/managed/complete	POST	media.save	media_id, rendition_id	Multipart file upload	Completed media.
/media/rendition/delete	POST	media.delete	media_id, rendition_id	Matching publication selector	Updated media.
/media/delete	POST	media.delete	media_id	Matching publication selector	Deleted media_id.

Media object

{
  "media_id": "MEDIA_UUID",
  "publication_id": "PUBLICATION_UUID",
  "slug": "launch-image",
  "kind": "image",
  "state": "ready",
  "title": "Launch image",
  "alt_text": "A control room at sunset",
  "caption": "M7 launch image",
  "metadata": null,
  "renditions": [
    {
      "rendition_id": "RENDITION_UUID",
      "source": "external",
      "state": "ready",
      "role": "card",
      "url": "https://cdn.example.com/launch-card.webp",
      "mime_type": "image/webp",
      "byte_size": 123456,
      "width": 1200,
      "height": 675,
      "duration_ms": null,
      "metadata": null
    }
  ]
}

kind is one of image, video, audio, document, or embed. A media slug is unique in its publication and defaults to the generated media ID when omitted.

External media

Create external media with an array of one or more renditions:

{
  "publication_slug": "engineering-notes",
  "kind": "image",
  "slug": "launch-image",
  "title": "Launch image",
  "alt_text": "A control room at sunset",
  "renditions": [
    {
      "role": "card",
      "external_url": "https://cdn.example.com/launch-card.webp",
      "mime_type": "image/webp",
      "byte_size": 123456,
      "width": 1200,
      "height": 675
    }
  ]
}

Each external rendition requires role, external_url, mime_type, and byte_size; original_filename, width, height, duration_ms, and metadata are optional. Roles must be unique within the media collection. Updating with renditions replaces the collection's external renditions; omit renditions to retain them.

Managed upload flow

1. Call /media/managed/reserve with one or more managed rendition descriptions. Each rendition needs original_filename, mime_type, and byte_size; role defaults to full, and filename, dimensions, duration, and metadata are optional.
2. For each reserved rendition, submit a multipart request to /media/managed/complete with media_id, rendition_id, and file. The uploaded file size must match the reserved byte_size.
3. Use /media/managed/save to update shared media fields or optional mime_type, width, and height for existing managed rendition IDs.

{
  "publication_slug": "engineering-notes",
  "kind": "image",
  "title": "Launch image",
  "renditions": [
    {
      "role": "full",
      "original_filename": "launch.webp",
      "mime_type": "image/webp",
      "byte_size": 123456
    }
  ]
}

Shared fields for all save routes are slug, kind, title, alt_text, caption, and metadata. Empty text values clear optional text fields; metadata must be an object, array, or null. Publications, posts, and categories accept only ready media. Author profiles accept a media UUID as an avatar reference. A referenced media collection cannot be deleted until those references are removed.