Download a sandbox file
Reads a single file inside the sandbox by absolute path; the response body is the raw byte stream.
Three ways this differs from the rest of the platform
- Not served under
/api/v2— see this operation’sservers. - The auth header is
X-Access-Token(thesandbox_access_tokenvalue), notAuthorization: Bearer. Control-plane tokens are invalid here, and vice versa. - Successful responses are not wrapped in the
{request_id, data}envelope (the body is a byte stream), and neither are errors — see the error notes below.
Optional capabilities: Content-Length and resumable downloads
Both vary by data center; clients must not assume they exist:
| Capability | When supported | When not supported |
|---|---|---|
Accept-Ranges | bytes | none |
Content-Length | Declares the byte count; enables progress display | Absent; Transfer-Encoding: chunked |
Range requests | Returns 206 + Content-Range per RFC 7233 | Returns 200 with the full file |
Accept-Ranges is the only runtime capability probe: issue one request without Range, or read the header on the first response, before deciding whether to resume.
Data centers without resume support never fake a 206: a request with Range gets 200 and the entire file. This is deliberate — a client that mistakes the response for a range would write bytes at the wrong offset and produce a silently corrupted file, which is far worse than an ignored Range. The correct resumable-download logic is therefore “resume only when Accept-Ranges: bytes, otherwise re-download the whole file” — never key off any signal other than 206.
The server returns no checksum headers (neither backend provides them); clients that need integrity verification should compute and compare checksums themselves.
Authorizations
Sandbox data-plane token — the sandbox_access_token returned by the create/connect endpoints. Used for /files, Sandbox-Exec, and other data-plane endpoints; the control plane (/api/v2) does not accept it, and conversely the control plane's Authorization: Bearer is invalid on the data plane.
The token is bound to its sandbox: using sandbox A's token against sandbox B's host fails. It stays valid until the sandbox's lifetime ends; there is no separate rotation endpoint (rotate_traffic_token rotates the port traffic token traffic_access_token and does not affect this one).
Headers
Only honored in data centers with Accept-Ranges: bytes; format bytes=<start>-<end>. Other data centers ignore the header and return 200 + the full file (not 206).
Query Parameters
Absolute path inside the sandbox. Must start with /; relative segments such as . / .. are rejected. No semantic interpretation is applied beyond existence checks; for writes, the parent directory must already exist.
1Perform the file operation as this user; defaults to the sandbox's default user. Optional capability: some data centers ignore this parameter and always act as the default user, so do not rely on it for permission isolation.
Response
The full file. Requests with Range also take this branch when the data center does not support resuming.
The response is of type file.