Skip to content

Files

Upload a file

Stores one or more files sent as multipart/form-data, without sending them, and returns a file object for each. Send a stored file by passing its id as file_id to Send files, as often as you like and to several chats. Files that are never sent are deleted 24 hours after the upload.

POST/api/v1/files
  • Bearer API key
  • Scope: write or admin
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Headers

  • Authorizationstringrequired

    Your API key as Bearer <key>. The word Bearer and the space are case-sensitive. Browser clients signed in to the app use the session cookie instead.

    Constraints
    Keys start with pk_live_ and are 56 characters long.
    Example
    Bearer pk_live_…
  • X-Tenant-IDuuidoptional

    Workspace id. Optional with an API key (a key always acts in its own workspace); if you send it, it must match the key’s workspace. Required with a session cookie. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Body

multipart/form-data
  • filefilerequired

    A file, as a form part with a file name. Repeat the part to upload several files (the field names files and files[] work too). Files are checked exactly like in Send files: the type is detected from the content together with the file name’s extension.

    Constraints
    1 to 10 files, at most 60 MB for the whole request. Photos: JPEG, PNG, WebP, up to 5 MB. Videos: MP4, 3GP, up to 16 MB. Audio: MP3, OGG (Opus), AAC, AMR, M4A, up to 16 MB. Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, ZIP, up to 16 MB.
    Example
    @invoice-1042.pdf

Response

201 Createdapplication/json

  • filesarray<File>

    The stored files, in the order of the request.

    Show child attributesHide child attributes8
    • iduuid

      File id. Send it as file_id to Send files, or use it in /api/v1/files/{id} paths.

    • file_namestring

      The name the file is sent under. Cleaned like the names of attachments: no folder path, no control characters and none of <>:"/\|?*, and it ends in an extension of the detected type.

    • mime_typestring

      The detected type, for example application/pdf. The same types as Send files are accepted.

    • sizeinteger

      Size in bytes.

    • media_urlstring

      Relative path of the stored file, /api/media/<workspace>/upload.<32 hex>.<ext>. Download it with your API key like a message’s media_url (Download a message’s file).

    • created_attimestamp

      When the file was uploaded (RFC 3339).

    • expires_attimestampnullable

      When the file is deleted if it is never sent: 24 hours after the upload. null once the file has been sent; it is then kept until you delete it.

    • sent_attimestampnullable

      Time of the first send. null until the file has been sent.

Status codes

  • 201Created. Every file was stored. Nothing was sent.
  • 400Bad request. send multipart/form-data with a file field, file is required, file is empty or at most 10 files per request. An error about one file names it with index and file_name.
  • 401Unauthorized. The API key is unknown, revoked or expired (invalid or expired API key), or there is no key and no signed-in session (unauthorized).
  • 402Payment required. Only when subscriptions are enforced and the workspace has no active subscription. The body includes code: "payment_required".
  • 403Forbidden. The API key has the read scope, which only allows GET requests (API key is read-only). A key in another workspace gets API key belongs to a different workspace; a key used from an IP address outside its allowed_ips gets this API key is not allowed from your IP address (code: "ip_not_allowed").
  • 413Too large. A file is over the limit of its type (file too large: images can be up to 5 MB, file too large: videos, audio and documents can be up to 16 MB, with index and file_name); the request is over 60 MB (the request is too large, request too large: at most 60 MB per request (images up to 5 MB, videos, audio and documents up to 16 MB each)); or the workspace already holds 500 MB of unsent uploads (upload storage is full: at most 500 MB of unsent uploads per workspace; send or delete files first).
  • 415Unsupported type. A file’s type cannot be sent, or its content is not what its extension says. The body names the file with index (0-based) and file_name.
  • 429Too many requests. More than 30 files uploaded in a minute in this workspace (each file counts; uploads have their own budget, separate from sending): too many attempts, please wait a minute and try again, with a Retry-After header. The API key rate limits apply as well.
  • 500Server error. Something went wrong on our side. Retry with backoff.

What if one file is refused?

Nothing is stored: an upload is all or nothing. The error names the refused file with index (its 0-based position in the request) and file_name, so you can fix it and upload again:

{
  "error": "unsupported file type (.exe): send a photo (JPG, PNG, WebP), a video (MP4, 3GP), audio (MP3, OGG/Opus, AAC, AMR, M4A) or a document (PDF, Word, Excel, PowerPoint, TXT, CSV, ZIP)",
  "index": 1,
  "file_name": "setup.exe"
}

How long is an uploaded file kept?

  • A file that is never sent is deleted 24 hours after the upload (its expires_at). The cleanup runs every 15 minutes, but an expired file answers 404 at once.
  • The first send sets sent_at and makes expires_at null: the file is then kept until you delete it.
  • A workspace can hold at most 500 MB of unsent uploads. Send or delete files to make room.

How do I send it?

Pass the id as file_id (or several ids as file_ids) to Send files. The same file can be sent any number of times, to several chats. Its media_url downloads it with your API key, like a message's file.