Docs Files

Files

Uploading a file, sending it, and who may read it.

Documentation

Sending a file takes two steps: upload it, then send a message with its id.

FILE=$(curl -s -X POST $API/files -H "Authorization: Bearer $ALICE" -F file=@photo.jpg | jq -r .id)
curl -s -X POST $API/conversations/$CID/messages -H "Authorization: Bearer $ALICE" \
     -H 'Content-Type: application/json' -d "{\"text\":\"Look\",\"attachments\":[\"$FILE\"]}"
{ "id": "…", "name": "photo.jpg", "contentType": "image/jpeg", "kind": "IMAGE", "size": 482113,
  "width": 3024, "height": 4032,
  "url": "/api/v1/files/…/content?expires=1791568800&signature=…",
  "thumbnailUrl": "/api/v1/files/…/thumbnail?expires=1791568800&signature=…",
  "urlExpiresAt": "2026-10-09T19:00:00Z" }
  • Any file is taken, up to the app's maxFileBytes, ten to a message.
  • What a file is, is read from its bytes, not from its name or the type the upload claimed. kind is IMAGE, VIDEO or AUDIO for what was recognised as something a browser plays, and FILE for everything else. Only the first three are served to be shown in place; the rest, an HTML page or an SVG among them, is a download. Every file is served with nosniff and a sandboxing content security policy.
  • Images (JPEG, PNG, GIF) are measured and given a JPEG preview of 320 pixels, turned the way the photo was taken. WebP is measured.
  • url and thumbnailUrl need no credentials, so they work in an <img> or a <video>. They are signed, good for an hour or a little more, and stay the same for a while so that a browser's cache is of use. Every time a message is read it comes with fresh ones; GET /files/{id} gives fresh ones for one file. With credentials, GET /files/{id}/content works without a signature. Ranges are served.
  • Who may read a file: its uploader, anybody who can read a message it is attached to, and the app's server. Until a file is sent its id opens nothing for anybody else, and a user can attach only a file they uploaded or can already read (which is what forwarding is).
  • A file that no message carries (never sent, or its message deleted) is cleared away a day after it was uploaded.
  • How much: a user with a token of their own uploads up to 1 GB in 24 hours. The upload that goes past it is still taken; the next is answered 429 until enough of the day has gone by. Your server is not held to it. While the storage has less than 1 GB of room left, every upload is answered 507: a disk that fills up stops the uploads, and not the server. And the files of an app take as much room together as its plan allows, 5 GB on the Free plan: an upload to an app that has as much is answered 402 (plans). The storage is every app's, and one app is not to leave the others without room.