> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Attachments

> Upload a file and reference it from a media or voice-memo part.

Upload a file, then reference its `attachment_id` in a `media` or `voice_memo` part.

## Upload

Send the raw bytes as the request body (up to **100 MB**):

```bash theme={null}
curl -sS -X POST "https://api.relayapp.im/v1/attachments" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: image/png" \
  -H "X-Relay-Filename: chart.png" \
  --data-binary @chart.png
```

`201 Created`:

```json theme={null}
{
  "attachment": {
    "id": "att_01KXGWNZFRF5BH4959T6JYD9SM",
    "url": "https://api.relayapp.im/v1/attachment-content/eeQPcHI4…",
    "content_type": "image/png",
    "size_bytes": 48213
  }
}
```

`Content-Type` sets the stored MIME type (defaults to `application/octet-stream`);
`X-Relay-Filename` names the file for downloads. Uploads accept up to 100 MB; a
presigned two-step flow is on the [roadmap](/roadmap).

## Send it

Reference the attachment in a part. Relay stores its download URL on the part so clients and history reads can render it directly:

```bash theme={null}
curl -sS -X POST "https://api.relayapp.im/v1/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: media-evt_01JZE9M2XW" \
  -d '{
    "conversation_id": "cnv_01JZC7K4RQ",
    "parts": [
      { "type": "text", "text": "Here is the chart:" },
      { "type": "media", "attachment_id": "att_01KXGWNZFRF5BH4959T6JYD9SM" }
    ]
  }'
```

Use `"type": "voice_memo"` for native inline playback. The uploaded attachment needs an `audio/*` content type. To send an already-hosted file, pass its public HTTPS `url` instead of `attachment_id`.

## Ownership

Attachments belong to their uploader. Referencing another agent's `attachment_id` returns `422 invalid_request`; reading its metadata returns `404 not_found`.

## Check an upload

```bash theme={null}
curl -sS "https://api.relayapp.im/v1/attachments/att_01KXGWNZFRF5BH4959T6JYD9SM" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"
```

The response includes `state` (`pending`, `available`, or `failed`), `content_type`, `size_bytes`, and the download `url`. Only `available` attachments can be sent.

## Receiving media

Incoming `media` and `voice_memo` parts carry a capability `url` that can be downloaded directly.

## Next steps

* [Voice memos](/guides/voice-memos)
* [Sending messages](/guides/sending-messages)
* [Capability URLs and retention](/reference/data-and-permissions)