DigitalOcean API (unofficial showcase)
GET/v2/agents/sessions/{session_id}/workspace/download

Download a file or tar archive from the session's sandbox workspace.

Streams the workspace payload back as application/octet-stream using chunked transfer encoding, followed by a fixed integrity footer.

Response body layout: <payload> + <footer>, where the footer is exactly 73 bytes: DOWSSHA1 (8 bytes) + 64-char lowercase SHA-256 hex + \n. The client MUST strip the trailing 73 bytes before saving, verify SHA-256(payload) equals the footer digest, and treat a tail that does not match this shape (magic + 64 hex + newline) as a failed (truncated/corrupt) transfer.

Other metadata:

  • X-Workspace-Is-Archive: true when the payload is a tar archive.
  • X-Workspace-Size-Bytes is a progress hint (not Content-Length) and excludes the footer.
  • The X-Content-Sha256 trailer also carries the digest but is best-effort: edge proxies may strip HTTP trailers, so the body footer is authoritative.

Concurrent transfers (upload + download) are capped server-side; over the cap the request blocks and may return 503.

3 parameters
session_idstringrequired
The session UUID.
pathstringrequired
Source path inside the sandbox workspace. Relative paths resolve under the workspace root; paths that escape the workspace are rejected. Required.
as_archivebooleanoptional
If true, the guest returns a tar stream of `path` (e.g. for a directory). Defaults to false (single file).

13 status codes
200Streaming workspace payload (octet-stream) followed by a fixed 73-byte integrity footer (`DOWSSHA1` + 64-char sha256 hex + newline). The digest is also delivered best-effort in the X-Content-Sha256 trailer.
400Missing path, invalid query parameter, or invalid path.
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.
401Authentication failed due to invalid credentials.
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.
403Path 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.
404The resource was 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.
409Session 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.
423This 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.
429The 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.
500There was a server 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.
501Workspace 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.
502Upstream sandbox transfer failed.
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.
503Workspace transfer capacity 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: Missing path, invalid query parameter, or invalid path. A 401 is returned: Authentication failed due to invalid credentials. A 403 is returned: Path resolves outside the workspace, or the session belongs to another team. A 404 is returned: The resource was not found. A 409 is returned: Session has no sandbox, or the sandbox is not ready. A 423 is returned: This session is unavailable; contact support. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. A 501 is returned: Workspace file transfer is not supported by the active sandbox driver. A 502 is returned: Upstream sandbox transfer failed. A 503 is returned: Workspace transfer capacity exhausted; retry later. Any other status is an error: There was an unexpected error.