Skip to content

Files

Get an uploaded file

Returns the file object of an uploaded file. Use it to check whether a file has been sent (sent_at) or when it will be deleted (expires_at).

GET/api/v1/files/{id}
  • 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

Response

200 OKapplication/json

  • 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

  • 200OK. The file.
  • 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.