# How to Attach a File

File attachments require three steps: get a signed upload URL → upload the file → attach to the message.

## Step 1 — Request a signed upload URL

```
POST /v3/attachments/signedurl
Content-Type: application/json
```

```json
{
  "files": [
    {
      "filename": "document.pdf",
      "mimetype": "application/pdf"
    }
  ]
}
```

**Response** — An array of objects (one per file in the request):

| Field | Description |
| --- | --- |
| `url` | Pre-signed S3 URL to `PUT` your file to. |
| `filename` | Echo of the filename from the request. |
| `mimetype` | Echo of the mimetype from the request. |

## Step 2 — Upload the file

```
PUT <url from step 1>
Content-Type: <mimetype from step 1>
Body: <raw file bytes>
```

This is a direct upload to cloud storage — no auth headers needed.

## Step 3 — Attach to the message

```
POST /messages/{message_id}/attachments
Content-Type: application/json
```

After uploading, use the URL from step 1 as the `link`. The backend uses the URL path to locate the uploaded file in storage.

```json
{
  "attachments": [
    {
      "type": "file",
      "link": "<url from step 1, after upload>",
      "filename": "document.pdf",
      "mime_type": "application/pdf"
    }
  ]
}
```

The `message_id` is returned in the response from [`POST /v3/messages/start`](./how-to-send-a-message.md).