Media

Upload files, inspect attachments, and download their bytes.

2 endpoints API 0.5.1-rc.3

Upload raw media bytes

Operation ID: uploadMedia

relayToken

POST/v1/media

Stores files outside Messages. The size limit defaults to 25 MiB and can be configured lower. Filenames cannot contain path separators, controls, quotes, or semicolons. MIME types cannot contain parameters. Images must decode within bounded dimensions, frame count, and total pixels. No multipart wrapper or base64 encoding.

Request

Request headers

X-FilenamestringRequired

Original filename, at most 255 UTF-8 bytes.

Validation rules

Minimum length: 1
Maximum length: 255

Body Required

Nonempty raw file bytes using the file MIME type as Content-Type.

Content type application/octet-stream

Raw bytes. No JSON schema applies.

Content type application/pdf

Raw bytes. No JSON schema applies.

Content type audio/*

Raw bytes. No JSON schema applies.

Content type image/*

Raw bytes. No JSON schema applies.

Content type text/*

Raw bytes. No JSON schema applies.

Content type video/*

Raw bytes. No JSON schema applies.

Responses

201Stored upload metadata and download URL.

Content type application/json

UploadMediaResponse

401, 413, 422, 500Error responses

401: Missing or invalid bearer token.
413: The request body or media exceeds its configured size limit.
422: A destination, payload field, filename, or media file failed validation.
500: The request failed.

Content type application/json

APIError

Headers on every response

X-Request-IDstringRequired: Request correlation identifier.

Read media metadata or download its bytes

Operation ID: getMedia

relayToken

GET/v1/media/{media_id}

Without download=true, returns JSON metadata. With download=true, streams the original file using its MIME type. OpenAPI cannot fully select the response schema from a query value. The JSON metadata schema applies only to metadata mode. A download with a JSON MIME type is still raw file content, not MediaReference. Filesystem paths are never exposed.

Request

Path parameters

media_idstringRequired

Percent-encoded public resource identifier, not a database row ID.

Validation rules

Minimum length: 1
Pattern: ^[^\p{Cc}\p{Cf}]+$

Query parameters

downloadstringOptional

Stream the original bytes instead of metadata. Accepts true, false, 1, or 0. Word spellings are case-insensitive.

Default: "false"

Validation rules

Pattern: ^([Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee]|[01])$

Responses

200MediaReference JSON, or raw bytes when download=true.

Content-DispositionstringOptional: Attachment filename, present only for downloads.

Content type */*

Raw bytes. No JSON schema applies.

Content type application/json

MediaReference

400, 401, 404, 500, 503Error responses

400: Malformed JSON, query parameter, cursor, destination selection, or resource identifier.
401: Missing or invalid bearer token.
404: The requested resource was not found.
500: The request failed.
503: The database, sender, Messages access, or request store is unavailable.

Content type application/json

APIError

Headers on every response

X-Request-IDstringRequired: Request correlation identifier.