Media API

List assets

GET/v1/media

Query

Field	Type	Notes
`limit`	integer	range 1..100
`starting_after`	string	len 1..∞
`lifecycle`	"single_use" \| "library"
`status`	"pending" \| "ready" \| "consumed" \| "expired" \| "deleted"
`kind`	"image" \| "document" \| "audio" \| "video" \| "sticker"

Response

Field	Type	Notes
`object`required	"list"
`data`required	object[]
`has_more`required	boolean
`next_cursor`required	string \| null

Create an upload session

POST/v1/media/uploads201 Created

Request body

Field	Type	Notes
`kind`required	"image" \| "document" \| "audio" \| "video" \| "sticker"
`lifecycle`required	"single_use" \| "library"
`filename`	string	len 1..255
`mime_type`required	string	len 1..255
`byte_length`required	integer	range -∞..9007199254740991

Response

Field	Type	Notes
`id`required	string
`object`required	"media_upload"
`upload_url`required	string
`upload_method`required	"PUT"
`upload_headers`required	object
`expires_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$

Complete an upload

POST/v1/media/uploads/{'{asset_id}'}/complete

Response

Field	Type	Notes
`id`required	string
`object`required	"media_asset"
`kind`required	"image" \| "document" \| "audio" \| "video" \| "sticker"
`lifecycle`required	"single_use" \| "library"
`filename`required	string \| null
`mime_type`required	string
`byte_length`required	integer	range 0..9007199254740991
`status`required	"pending" \| "ready" \| "consumed" \| "expired" \| "deleted"
`expires_at`required	string<ISO-8601> \| null
`upload_expires_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`completed_at`required	string<ISO-8601> \| null
`consumed_at`required	string<ISO-8601> \| null
`consumed_by_message_id`required	string \| null
`deleted_at`required	string<ISO-8601> \| null
`trace_id`required	string \| null
`created_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`updated_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$

Storage usage

GET/v1/media/storage-usage

Response

Field	Type	Notes
`object`required	"media_storage_usage"
`used_bytes`required	integer	range 0..9007199254740991
`limit_bytes`required	integer	range -∞..9007199254740991
`available_bytes`required	integer	range 0..9007199254740991
`percent_used`required	number	range 0..∞

Retrieve metadata

GET/v1/media/{'{asset_id}'}

Response

Field	Type	Notes
`id`required	string
`object`required	"media_asset"
`kind`required	"image" \| "document" \| "audio" \| "video" \| "sticker"
`lifecycle`required	"single_use" \| "library"
`filename`required	string \| null
`mime_type`required	string
`byte_length`required	integer	range 0..9007199254740991
`status`required	"pending" \| "ready" \| "consumed" \| "expired" \| "deleted"
`expires_at`required	string<ISO-8601> \| null
`upload_expires_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`completed_at`required	string<ISO-8601> \| null
`consumed_at`required	string<ISO-8601> \| null
`consumed_by_message_id`required	string \| null
`deleted_at`required	string<ISO-8601> \| null
`trace_id`required	string \| null
`created_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`updated_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$

Delete media

DELETE/v1/media/{'{asset_id}'}

Response

Field	Type	Notes
`id`required	string
`object`required	"media_asset"
`deleted`required	"true"

GET /v1/media/{asset_id} returns metadata only. It never returns raw bytes, base64, or object storage keys. Uploads default to single_use; set lifecycle: "library" for media that must be reused. Send media through POST /v1/messages with message.media.asset_id.