> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Media and Avatar — verified contracts

Sources: `modules/Media/Routes/api.php`, `Interfaces/Http/Controllers/{MediaController,AvatarController}.php`, `Infrastructure/AttachedAvatars.php`, Core `ApiResponse.php`.

## POST /media — authenticated, throttle 30/min

**Content-Type:** `multipart/form-data`.

| Form field | Type | Required | Validation |
|---|---|---|---|
| `file` | uploaded file | Yes | `file`; max `config('media.max_upload_kb')` KB (environment-dependent) |

**201 response shape:**
```json
{"data":{"reference":"<media-reference>","url":"<temporary-signed-media-url>"}}
```
The upload result may contain additional keys from `MediaUploader`; only `reference` and signed `url` are confirmed here. The reference is temporary until attached.

## GET /media/{reference}/file — signed URL

`reference` must match `med_[a-f0-9]{32}`; `signed` middleware validates URL signature; throttle 300/min. **Returns file bytes**, not JSON, with `Content-Type` equal to stored MIME type, `Content-Disposition: inline`, and `Cache-Control: private, max-age=3600`. Use server-issued signed URL, do not construct manually.

## PUT /me/avatar — authenticated

**JSON body:**

| Field | Type | Required | Rules |
|---|---|---|---|
| `reference` | string | Yes | max 40 |

Request: `{"reference":"<previously-uploaded-reference>"}`

**200 response:** `{"data":{"avatar_url":"<signed-url-or-null>"}}`

## POST /me/avatar — authenticated, throttle 30/min

**Content-Type:** `multipart/form-data`; form field `avatar` required file, max `config('media.max_upload_kb')` KB. Uploads and attaches in one request.

**201 response:** `{"data":{"avatar_url":"<signed-url-or-null>"}}`

## DELETE /me/avatar — authenticated

No request body. **204 No Content**. Avatar URL is a temporary signed URL, not a permanent public path.
