# Media

## Upload media

**post** `/v1/media`

Uploads media bytes and returns the durable `upload_ref` used by an
outbound `media` part. Send the raw bytes as the request body and their
exact media type in `Content-Type`; the body is never JSON-normalized.

`media_id` is a different namespace: it is the channel's transient,
inbound-only identifier and expires after seven days. It is never an
outbound address. Handles returned here visibly begin `upload.` and are
reusable within this key's account and test/live partition. Outbound
uploads have no fixed beta expiry and are not routinely pruned, but this
is not a permanence promise: account deletion or offboarding may remove
them. Reusing a handle does not create or refresh an expiry clock.
Inbound media bytes are not readable through this route and are deleted
30 days after server receipt.

Size ceilings are applied by kind: image 5,000,000 bytes; audio and
video 16,000,000; document 100,000,000; static sticker 100,000 and
animated sticker 500,000. A larger body is refused, never truncated.
Images accept JPEG or PNG; video accepts MP4 or 3GPP; audio accepts AAC,
AMR, MPEG, MP4 or Ogg; stickers accept WebP; documents accept `text/plain`,
`application/pdf`, the legacy Word/Excel/PowerPoint media types, and the
three Open XML Word/Excel/PowerPoint media types. The media type must
match the kind; an invented vendor suffix is not accepted.

### Query Parameters

- `kind: "image" or "video" or "audio" or 2 more`

  The kind this upload will be sent as.

  - `"image"`

  - `"video"`

  - `"audio"`

  - `"document"`

  - `"sticker"`

### Returns

- `Upload object { byte_size, kind, mime_type, 2 more }`

  A durable upload that can be reused by outbound media parts. No fixed beta expiry is promised.

  - `byte_size: number`

    Exact byte count stored.

  - `kind: "image" or "video" or "audio" or 2 more`

    The media kind chosen at upload. A send using this handle must use the same kind.

    - `"image"`

    - `"video"`

    - `"audio"`

    - `"document"`

    - `"sticker"`

  - `mime_type: string`

    The normalized media type stored with the bytes.

  - `sha256: string`

    Lowercase hexadecimal SHA-256 over the exact stored bytes.

  - `upload_ref: string`

    Our reusable handle. It always begins `upload.` and is supplied as a media part's `upload_ref`. It has no fixed beta expiry or scheduled pruning, but is not permanent and may be removed by account deletion or offboarding.

### Example

```http
curl https://whatsapp.messages.api.linqapp.com/v1/media \
    -H 'Content-Type: */*' \
    -H "Authorization: Bearer $LINQ_WHATSAPP_API_KEY" \
    -d '{}'
```

#### Response

```json
{
  "byte_size": 0,
  "kind": "image",
  "mime_type": "mime_type",
  "sha256": "sha256",
  "upload_ref": "upload_ref"
}
```

## Domain Types

### Upload

- `Upload object { byte_size, kind, mime_type, 2 more }`

  A durable upload that can be reused by outbound media parts. No fixed beta expiry is promised.

  - `byte_size: number`

    Exact byte count stored.

  - `kind: "image" or "video" or "audio" or 2 more`

    The media kind chosen at upload. A send using this handle must use the same kind.

    - `"image"`

    - `"video"`

    - `"audio"`

    - `"document"`

    - `"sticker"`

  - `mime_type: string`

    The normalized media type stored with the bytes.

  - `sha256: string`

    Lowercase hexadecimal SHA-256 over the exact stored bytes.

  - `upload_ref: string`

    Our reusable handle. It always begins `upload.` and is supplied as a media part's `upload_ref`. It has no fixed beta expiry or scheduled pruning, but is not permanent and may be removed by account deletion or offboarding.