List Media
List uploaded media files. Returns up to 50 items per page. Use offset to paginate. Media expires after 7 days unless used in a published post.
list_media
List uploaded media files. Returns up to 50 items per page. Use offset to paginate. Media expires after 7 days unless used in a published post.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
status | pending | ready | expired | no | Filter by status. "ready" = available for use in posts. Omit to return all. |
type | image | video | document | no | Filter by media type. Omit to return all. |
limit | number | no | Max results to return (default 50, max 100). |
offset | number | no | Number of results to skip for pagination (default 0). |
workspaceId | string | no | Workspace ID. Required if your API key accesses multiple workspaces. |
When to use
Browse the media library for a workspace. Good for agent UIs that let the user pick from previously uploaded assets rather than re-uploading every time.
Pagination and filtering
limit(default 25, max 100)cursorfor next pagetypefilter:image,video, ordocumentstatusfilter:pending,uploaded,failed
Example
{
"workspaceId": "wks_01H...",
"type": "image",
"status": "uploaded",
"limit": 50
}Returns { items: [...], cursor }.
Gotchas
- Media is workspace-scoped. An asset uploaded to workspace A is not visible from workspace B — even within the same tenant. Re-upload if needed.
- Retention: there is no automatic purge. Uploaded media accumulates over time. Use
delete_mediato clean up deprecated assets. - The
itemsarray includesurlfor each entry. Prefer referencing byidwhen constructing posts — URLs may rotate under signed-access policies.
Get Media
Get metadata for an uploaded media file. Returns id, url, type, mimeType, sizeBytes, status (pending/ready/expired), filename, and expiration date.
Delete Media
Delete an uploaded media file from storage. Removes the file from CDN and marks it as expired. Cannot delete media that is attached to a published post.