Attachment uploads¶

A client normally uploads each file first and then references it when creating the message. The flow has three steps (four for large files):

1. Request an upload plan for the files.
2. Send each file's bytes with PUT to its upload URL, or each part to its part URL.
3. For a multipart upload, complete it.
4. Create the message with the returned upload keys.

Small files can instead travel inside the message request itself as multipart/form-data; see Multipart body.

Attachment uploads accept user sessions and bot tokens. The caller needs VIEW_CHANNEL, SEND_MESSAGES and ATTACH_FILES in a guild channel, must not be timed out, and must be a recipient of a private channel.

Size limits¶

The maximum size of one file depends on the uploader's plan and on the guild's boost level. The effective limit is the larger of the two.

A private channel has no boost level, so only the account limit applies there. A file above the limit is rejected with 400 BAD_REQUEST when the plan is requested. A message can carry at most 10 attachments.

Requesting an upload plan¶

POST /channels/{channel_id}/attachments

Requests upload URLs for 1 to 10 files at once.

Rate limit: channel:attachment:upload, 10 per 10 seconds per account and channel.

The response is {"attachments": [...]} with one entry per requested file:

curl -X POST https://tebhos.com/api/v1/channels/1489002177550843904/attachments \
  -H "Authorization: Bearer $TEBHOS_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"attachments": [{"id": 0, "filename": "photo.png", "file_size": 48213, "content_type": "image/png"}]}'

{
  "attachments": [
    {
      "id": 0,
      "upload_mode": "singlepart",
      "filename": "photo.png",
      "upload_filename": "3f6c2a8e-6d1b-4f0e-9a52-1c7f4b2d9e10",
      "upload_url": "https://storage.example.com/attachments/1489002177550843904/1489002299998765056/photo.png?X-Amz-Signature=...",
      "file_size": 48213,
      "content_type": "image/png",
      "attachment_id": "3f6c2a8e-6d1b-4f0e-9a52-1c7f4b2d9e10",
      "storage_key": "attachments/1489002177550843904/1489002299998765056/photo.png",
      "url": "https://cdn.tebhos.com/attachments/1489002177550843904/1489002299998765056/photo.png"
    }
  ]
}

Part size¶

A multipart plan aims at about 20 parts: the part size is the file size divided by 20, rounded up to a whole MiB, and never below 10 MiB. Part n covers bytes (n - 1) × part_size up to the next part; the last part holds the remainder.

Single-file variant¶

POST /channels/{channel_id}/attachments/upload-url requests a plan for one file with the body {"filename": string, "content_type": string, "size": integer}. It returns attachment_id, upload_url, storage_key, url, expires_in (seconds) and max_size. It shares the same bucket and limits.

Transferring the bytes¶

Send a PUT request to upload_url with the file's bytes as the body. Do not send an Authorization header, and do not change the URL's path or query string.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

A single upload URL is valid for 5 minutes (300 seconds); a part URL is valid for 1 hour. An expired URL cannot be refreshed; request a new plan.

For a multipart file, PUT each part's bytes to its part URL, in any order and in parallel if you like.

Where the upload URL points depends on the instance: with presigned uploads (presigned_attachment_uploads true in instance features) it is a signed object storage URL; otherwise it is a path under the API itself. The client flow is the same in both cases.

Completing a multipart upload¶

POST /channels/{channel_id}/attachments/complete

Joins the uploaded parts of one or more multipart uploads into their files. Call it after every part has been sent and before creating the message.

Rate limit: channel:attachment:upload (shared with upload plans), 10 per 10 seconds per account and channel.

For each entry the server checks that the upload was planned by the caller in this channel as a multipart upload, lists the parts in storage, and joins them. The joined file then goes through the same processing as metadata confirmation: its size is checked against the caller's limit, its SHA-256 digest against the blocked-file list, and image dimensions and a placeholder are computed. A separate confirmation call is not needed.

The response is {"uploads": [{"upload_filename": string}]}, one entry per completed upload.

curl -X POST https://tebhos.com/api/v1/channels/1489002177550843904/attachments/complete \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uploads": [{"upload_filename": "3f6c2a8e-6d1b-4f0e-9a52-1c7f4b2d9e10", "upload_id": "2~abc..."}]}'

Optional metadata confirmation¶

POST /channels/{channel_id}/attachments/{attachment_id}/confirm

After the upload, a client may record metadata on the pending attachment. Every field is optional. This step is not required; the same metadata can be sent when creating the message.

Claiming the upload¶

Reference each uploaded file in Create message with an attachments array of objects carrying its upload_filename:

{
  "content": "Here is the photo",
  "attachments": [
    {
      "upload_filename": "3f6c2a8e-6d1b-4f0e-9a52-1c7f4b2d9e10",
      "width": 1280,
      "height": 720,
      "flags": 0
    }
  ]
}

Metadata sent here fills only fields that were not already set by the confirmation step. Alternatively, send attachment_ids (an array of upload_filename values) and spoiler_attachment_ids.

An upload key is single-use and belongs to the account that requested it. A key that is unknown, already used, or owned by another account is skipped without an error, so check the returned message's attachments to confirm every file was attached. Uploading alone creates no message and dispatches no Gateway event.

Retention¶

A stored attachment is kept for a period that depends on its size: files up to 5 MiB are kept for about three years, and the period shrinks with size down to 14 days for files of 500 MiB. Expired attachments are removed automatically.

Profile and guild images¶

Avatars, banners, guild icons, emojis and stickers use their own upload-URL routes, described on the pages for the current user, guilds, guild emojis and guild stickers.

Stream previews¶

A stream preview is a JPEG image attached to a screen share. It uses the Streams API, not the attachment flow. A preview can be sent inline or through an upload URL from POST /streams/{stream_key}/preview/upload-url; the image must be at most 1000000 bytes, and the upload URL is valid for one day.

Failures¶

API requests return the standard error response. A failed PUT to object storage returns the storage provider's own error format.