Media

Upload a file with media:write, then reference it in a message. Ruut accepts images, documents, audio, and video in supported MIME types. The common upload limit is 20 MB; the destination connection may impose a smaller limit.

1234curl -X POST "$RUUT_BASE/api/v2/media" \
  -H "Authorization: Bearer $RUUT_TOKEN" \
  -H "Idempotency-Key: file-upload-0001" \
  -F "[email protected]"

The response returns 202 and a ready media resource with a med_ ID. An optional filename multipart field overrides the display name. Idempotency compares the file bytes and filename, so retries cannot silently replace an earlier upload.

1234567{
  "content": [
    { "type": "text", "text": "The document is attached." },
    { "type": "file", "media_id": "med_your_upload" }
  ],
  "expected_owner_version": 0
}

Use image, file, audio, or video to match the uploaded bytes. Sending requires messages:write and media:read. The server validates the media's account, application, inbox grants, size, and type before accepting the message. Arbitrary external media URLs and raw storage IDs are not accepted.

Use GET /api/v2/media/{media_id} with media:read to obtain a temporary download URL. Standard attachment links expire after five minutes. Request the media resource again for a fresh link.

Received message attachments use the same media IDs and download endpoint. Contact sessions can access only attachments from their explicitly granted conversations. Customer sessions with media:write can upload attachments for their own messages. Standalone uploads remain restricted to the issuing session. A media ID alone does not grant access.