List media

GET /media

Returns media files in your library. Supports filtering by type and pagination.

Pulling media IDs for a post

The top-level media_ids array in the response is a convenience array of every UUID in items[], in the same order. If you want to attach all returned media to a post, you can copy media_ids straight into POST /v1/posts.

No url or storage_url field

This endpoint does not return direct storage URLs. See GET /v1/media/{media_id} for the reasoning. Each items[] entry has media_id, dimensions, and content type — enough to identify and filter, but no raw file URL.

Query Parameters

Parameter	Type	Required	Description
`type`	string	No	Filter by media type: `image`, `video`, or `document`
`limit`	integer	No	Number of items to return. Min 1, max 100, default 20.
`offset`	integer	No	Number of items to skip. Default 0.

Response Example

200 — List of media

{
  "data": {
    "items": [
      {
        "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "ready",
        "type": "image",
        "filename": "product-photo.jpg",
        "content_type": "image/jpeg",
        "size": 2048576,
        "width": 1920,
        "height": 1080,
        "duration": null,
        "created_at": "2026-04-10T12:00:00.000Z"
      }
    ],
    "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "pagination": {
      "limit": 20,
      "offset": 0
    }
  },
  "error": null,
  "meta": {
    "request_id": "a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

Item object fields

Field	Type	Description
`media_id`	string (UUID)	Canonical media identifier (use in `media_ids` arrays)
`status`	string	`ready`, `processing`, or `failed`
`type`	string	`image`, `video`, or `document`
`filename`	string	Original filename
`content_type`	string	MIME type
`size`	integer	File size in bytes
`width`	integer or null	Pixel width
`height`	integer or null	Pixel height
`duration`	number or null	Duration in seconds (videos)
`created_at`	string (ISO 8601)	UTC timestamp

Request

Responses

List of media

List media

/media

Query Parameters​

Response Example​

200 — List of media​

Item object fields​

Request​

Responses​