POST
/v2/agents/sessions/{session_id}/workspace/uploadUpload a file to a session workspace
Upload a file or tar archive to a path in a session's sandbox workspace. Send the raw bytes in the request body and use is_archive to have the guest extract a tar stream under the destination path. Include X-Content-Sha256 to verify the payload after it is written; uploads are capped at 500 MiB.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
session_idstringrequired
The UUID of the session whose sandbox workspace receives the upload.
pathstringrequired
Destination path inside the sandbox workspace. Relative paths resolve under the workspace root; paths that escape it are rejected.
is_archivebooleanoptional
Set to true when the request body is a tar stream for extraction under `path`. Defaults to false when omitted.
X-Content-Sha256stringoptional
Optional hex SHA-256 digest of the full payload. The guest verifies the digest after writing the payload.
200Returns the absolute guest path where the payload was written and the number of bytes committed to the workspace.
pathstringoptional
Absolute guest path the payload was written to.
bytes_writtenintegeroptional
Number of bytes committed to the workspace.
400Returned when `path` is missing or invalid, a query parameter is invalid, or the SHA-256 digest does not match the payload.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Returned when authentication fails because the credentials are invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
402Returned when the team is blocked by the prepayment gate.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403Returned when the path resolves outside the workspace or the session belongs to another team.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404Returned when the resource is not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
409Returned when the session has no sandbox or the sandbox is not ready.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
413Returned when the payload exceeds the maximum allowed size.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
423Returned when the session is unavailable; contact support.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
501Returned when workspace file transfer is not supported by the active sandbox driver.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
502Returned when the upstream sandbox transfer fails.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
503Returned when workspace transfer capacity is exhausted; retry later.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Error handling
A 400 is returned when the path query parameter is missing or invalid, or the X-Content-Sha256 header digest does not match; a 401 indicates invalid authentication credentials; a 402 indicates the team is blocked by the prepayment gate; a 403 indicates the path resolves outside the workspace or the session belongs to another team; a 404 indicates the resource was not found. A 409 is returned when the session has no sandbox or it is not ready; a 413 when the payload exceeds the maximum size; a 423 when the session is unavailable; a 429 when the API rate limit is exceeded; a 500 for a server error; a 501 when the active sandbox driver does not support workspace file transfers; a 502 when the upstream sandbox transfer fails; and a 503 when workspace transfer capacity is exhausted. The session_id path parameter must identify a session with an available sandbox, the path query parameter must stay within the workspace, and the request body must not exceed 500 MiB; if provided, the X-Content-Sha256 header must contain the payload's hex SHA-256 digest.