Create an MMS media upload
Create an upload slot for MMS media that is not already hosted at a public
URL. The endpoint validates the mime_type and byte_size (up to 1 MiB)
and returns a single-use pre-signed upload URL, valid for 30 minutes,
along with a media_id.
Upload the file with an HTTP PUT to the returned URL, then reference the
media_id in the media array of a POST /v1/messages request.
Requires the messages:send scope. If MMS is not available, the call
returns 503 MMS_DISABLED.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/messages/media-upload" \ -H "Content-Type: application/json" \ -d '{ "mime_type": "image/png", "byte_size": 102400 }'{
"success": true,
"data": {
"media_id": "1f2c3a4d-5e6f-4789-9abc-0d1e2f3a4b5c",
"upload_url": "https://AgentMessage-mms-uploads.r2.cloudflarestorage.com/uploads/{org}/{media_id}?X-Amz-Signature=...",
"expires_at": "2026-01-01T00:30:00Z",
"max_byte_size": 1048576
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "rate limited",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "MMS_DISABLED",
"message": "mms subsystem disabled",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}