Skip to content
Subako Docs
English
Esc
↑↓navigate↵open⌘Jpreview

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}/uploads
Authorization
AuthorizationBearer token · headerrequired
Path parameters
session_idstring<uuid>required
Session id
Query parameters
namestringrequired
The 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-Keystring
Retry 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-stream
The file's bytes, at most 1 GiB.
string<binary>
Responses
200The file as stored.
bytesinteger<int64>required
The file's length in bytes.
min 0
expires_atstring<date-time>required
When the file is removed if no message has carried it.
idstring<uuid>required
What an input's `upload_ids` names the file by, and the id it keeps as an attachment once a message carries it.
media_typestringrequired
What the file is taken to hold, by its name's extension.
namestringrequired
400Malformed path parameter, a name that is not one path segment of 1 to 200 bytes, or a body over 1 GiB.
errorErrorDetailrequired
What 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 properties
codeErrorCoderequired
The 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_requestsinternal
messagestringrequired
401Missing, malformed, or invalid bearer token.
errorErrorDetailrequired
What 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 properties
codeErrorCoderequired
The 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_requestsinternal
messagestringrequired
403A 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.
errorErrorDetailrequired
What 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 properties
codeErrorCoderequired
The 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_requestsinternal
messagestringrequired
404No such session, or the caller cannot see it.
errorErrorDetailrequired
What 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 properties
codeErrorCoderequired
The 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_requestsinternal
messagestringrequired
409The 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.
errorErrorDetailrequired
What 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 properties
codeErrorCoderequired
The 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_requestsinternal
messagestringrequired
Try it
Server
Authorization
Parameters
Bodyapplication/octet-stream
Request
curl -X POST "https://api.us.cloud.subako.ai/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/uploads?name=string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -d '"string"'
Response
{
  "bytes": 0,
  "expires_at": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "media_type": "string",
  "name": "string"
}