Upload a file for a message
Stores a file ahead of the message it goes with. Send the message as an input whose upload_ids names the upload’s id; the file is then an attachment of that message under the same id. An upload no message carries is removed 24 hours after it was made. Only a session whose agent enables attachments takes one. A retry under one Idempotency-Key is recognized by the session, the name and the declared length, and answers the first upload.
POST
/v1/sessions/{session_id}/uploadsAuthorization
AuthorizationBearer token · headerrequiredPath parameters
session_idstring<uuid>requiredSession id
Query parameters
namestringrequiredThe file's name: one path segment of 1 to 200 bytes, such as
`report.pdf`. Its extension decides the media type the file is served
as.
min length 1 · max length 200
Header parameters
Idempotency-KeystringRetry the same operation with this key to return its saved receipt. Scoped by the operation's authenticated caller or resource. A different input under the same key returns 409. Receipts are retained for at least 7 days after completion, then removed by an hourly sweep. After removal the key can execute again. Fresh-only secrets are never included in a replay.
min length 1 · max length 255
Request body
requiredapplication/octet-streamThe file's bytes, at most 1 GiB.
string<binary>Responses
200The file as stored.
bytesinteger<int64>requiredThe file's length in bytes.
min 0
expires_atstring<date-time>requiredWhen the file is removed if no message has carried it.
idstring<uuid>requiredWhat an input's `upload_ids` names the file by, and the id it keeps
as an attachment once a message carries it.
media_typestringrequiredWhat the file is taken to hold, by its name's extension.
namestringrequired400Malformed path parameter, a name that is not one path segment of 1 to 200 bytes, or a body over 1 GiB.
errorErrorDetailrequiredWhat went wrong: a `code` to branch on and a `message` to show. The
message is written for a person and may change; the code will not.
Show propertiesHide properties
codeErrorCoderequiredThe machine-readable half of an error response, and the field a client
branches on. Closed: every error carries exactly one of these.
Allowed:
unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternalmessagestringrequired401Missing, malformed, or invalid bearer token.
errorErrorDetailrequiredWhat went wrong: a `code` to branch on and a `message` to show. The
message is written for a person and may change; the code will not.
Show propertiesHide properties
codeErrorCoderequiredThe machine-readable half of an error response, and the field a client
branches on. Closed: every error carries exactly one of these.
Allowed:
unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternalmessagestringrequired403A workspace credential lacking session.manage, or an organization suspended or out of credit. A session token may act only on its own session and never lands here.
errorErrorDetailrequiredWhat went wrong: a `code` to branch on and a `message` to show. The
message is written for a person and may change; the code will not.
Show propertiesHide properties
codeErrorCoderequiredThe machine-readable half of an error response, and the field a client
branches on. Closed: every error carries exactly one of these.
Allowed:
unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternalmessagestringrequired404No such session, or the caller cannot see it.
errorErrorDetailrequiredWhat went wrong: a `code` to branch on and a `message` to show. The
message is written for a person and may change; the code will not.
Show propertiesHide properties
codeErrorCoderequiredThe machine-readable half of an error response, and the field a client
branches on. Closed: every error carries exactly one of these.
Allowed:
unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternalmessagestringrequired409The session's agent does not enable attachments, the session's attachments and uploads already hold 10 GiB or more (a file taken short of that may run past it), or Idempotency-Key was already used for a different request.
errorErrorDetailrequiredWhat went wrong: a `code` to branch on and a `message` to show. The
message is written for a person and may change; the code will not.
Show propertiesHide properties
codeErrorCoderequiredThe machine-readable half of an error response, and the field a client
branches on. Closed: every error carries exactly one of these.
Allowed:
unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternalmessagestringrequired