Skip to main content
POST
Create an upload

Authorizations

Authorization
string
header
required

Access token from POST /management/v1/auth/token (publishable-key exchange) or a login session. Publishable-key tokens are agent-scoped and serve the messaging surface; login tokens also serve management.

Body

application/json

The file you are about to upload: its name and its exact size.

filename
string
required

Name of the file, with its extension: one of png, jpg, jpeg, gif, webp, pdf, docx, xlsx, pptx, csv, txt, md, json. It is stored under a cleaned name, returned as file_name: only the part after the last / or , without control characters and without leading dots or spaces, Unicode-normalized (NFC), the extension lower-cased, and cut to 100 characters.

Required string length: 1 - 255
size
integer
required

Exact size of the file in bytes, at most 20 MB. The upload accepts only a body of this size.

Required range: x >= 1

Response

Successful Response

Where to upload one file, and the link to attach it to a message with.

upload_url
string
required

Upload the file's bytes here with an HTTP PUT, sending headers. Expires in 15 minutes.

headers
Headers · object
required

Every header the PUT must send, with exactly these values; the upload is refused otherwise. A Content-Length entry is the size you declared, which HTTP clients send on their own.

file_name
string
required

The name the file is stored and shown to the agent under.

file_url
string
required

Link to read the uploaded file, e.g. for a preview; expires in 15 minutes. Pass it in a message's file_urls to attach the file; the link itself may have expired by then.