Skip to content

Files

Download an uploaded file

Returns the bytes of an uploaded file, always as a download (Content-Disposition: attachment) under its file_name. A read key is enough.

GET/api/v1/files/{id}/content
  • Bearer API key
  • Scope: read, write or admin
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Path parameters

  • iduuidrequired

    File id: the id returned by Upload a file.

    Example
    4f1c2d3e-4a5b-4c7d-8e9f-0a1b2c3d4e5f

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
  • Rangestringoptional

    Optional byte range, for example bytes=0-1048575, to download part of the file. The answer is then 206 Partial Content.

Response

Status codes

  • 200OK. The file. Content-Type is the file’s own type for photos, audio and video (image/jpeg, image/png, image/webp, video/mp4, video/3gpp, audio/ogg, audio/mpeg, audio/aac, audio/amr, audio/mp4) and application/octet-stream for everything else. Every answer has Content-Disposition: attachment with the file name, X-Content-Type-Options: nosniff and a Content-Security-Policy that sandboxes the file.
  • 206Partial content. The requested part of the file, when you send a Range header.
  • 400Bad request. The id is not a valid UUID (invalid file id).
  • 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 X-Tenant-ID header or tenant query does not match the API key’s workspace (API key belongs to a different workspace), a signed-in user is not a member of the workspace (forbidden), or the key is limited to other IP addresses (this API key is not allowed from your IP address, with code: "ip_not_allowed").
  • 404Not found. No such file in this workspace (file not found): the id is unknown, the file was deleted or has expired, or it belongs to another workspace.
  • 500Server error. Something went wrong on our side. Retry with backoff.

-OJ makes cURL save the file under the name the server sends. The file’s media_url serves the same file; see Download a message’s file. Downloads made with an API key are recorded in the audit log as file.downloaded.