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 /v5/attachments/upload/signedurl
Content-Type: application/json

{
  "files": [
    {
      "filename": "document.pdf",
      "mimetype": "application/pdf",
      "idempotency_key": "<optional-client-uuid>"
    }
  ]
}

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.
`idempotency_key`	Client-provided UUID, or server-generated if omitted. Use this to resume a failed upload so new requests don't result in a new file path in storage.

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.

{
  "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 /v6/messages/text.