# Upload message media

**POST** `/media/uploads`

Uploads a file and returns a `mediaId` handle for later message sends.
Pass the handle as `content.media.mediaId` when sending media content.
Use the same Idempotency-Key when retrying the same upload request.

Authentication: bearerAuth
Required scopes: `message:create`
Allowed roles: `owner`, `admin`, `agent`
Authorization: Upload media for a future message send.

## Request body

- `multipart/form-data`: `CreateMediaUploadRequest` required.

## Responses

- `201`: Media uploaded
- `default`: Error