GET/v1/sandboxes/{id}/files
Auth: API key
Stream a file out. ?path=.
Parameters
- idrequiredpath · string
- pathquery · string
Files
12 routes of the published API contract, generated from it.
PUT/v1/sandboxes/{id}/files
Auth: API key
Write a file in. ?path=; the body is the bytes. ?mode= (octal, e.g. 755) sets the file's permission bits; without it a file that already exists keeps its mode, as a shell > or an editor's save does, and a new file is 644. A directory on the path that does not exist is created first (mkdir -p, mode 755). Large files are chunked by the SDKs at 16 MiB. &offset=N writes at byte N instead of replacing the file, so an interrupted upload resumes: its error's evidence says how many bytes were written. A body over the request limit is refused 413.
Parameters
- idrequiredpath · string
- modequery · string
- offsetquery · integer
- pathquery · string
Request body string · application/octet-stream
Answer 200 · FileWritten · application/json
- bytesrequiredinteger
- Bytes written by this request.
- chunksrequiredinteger
- How many pieces the write was sent in.
- moderequiredstring
- The file's permission bits after the write, octal (
644). Without?mode=a file that already existed keeps its own, and a new file is644. - offsetrequiredinteger
- Where this request's bytes start in the file (
?offset=, else 0). - okrequiredboolean
- pathrequiredstring
- sandbox_idrequiredstring
- statFileStat | null
- The file as the sandbox describes it after the write;
nullwhen it could not say.
DELETE/v1/sandboxes/{id}/files
Auth: API key
Delete a path. Idempotent: a missing path answers existed: false, not 404. ?recursive=1 for a tree.
Parameters
- idrequiredpath · string
- pathquery · string
- recursivequery · string
Answer 200 · FileDeleted · application/json
- deletedrequiredboolean
- existedrequiredboolean
- False when there was nothing at that path to begin with.
- okrequiredboolean
- pathrequiredstring
- sandbox_idrequiredstring
POST/v1/sandboxes/{id}/files/archive
Auth: API key
Pack a directory into a tar **inside the sandbox** and answer with where it landed and how big it is. Download it with the ordinary chunked file read. Splitting it this way is what lets a directory of any size come out: the transfer is the byte path you already have, not a second one with its own limit. exclude takes name globs like .git.
Parameters
- idrequiredpath · string
Request body FileArchive · application/json
- excludestring[]
- Name globs left out, e.g.
[".git"]. - outstring | null
- Where the archive is written (absolute). Default: beside the source.
- pathrequiredstring
Answer 200 · ArchiveInfo · application/json
- archive_pathrequiredstring
- Where the tar landed inside the sandbox.
- sandbox_idrequiredstring
- served_bystring | null
- sizerequiredinteger
- sourcerequiredstring
- The directory that was packed.
POST/v1/sandboxes/{id}/files/chmod
Auth: API key
Change permissions and ownership. mode is a number or an octal string like "755". Ownership is changed on the symlink itself, never on what it points at.
Parameters
- idrequiredpath · string
Request body FileChmod · application/json
- gidinteger | null
- modeFileMode | null
- pathrequiredstring
- recursiveboolean | null
- uidinteger | null
Answer 200 · FileInfo · application/json
- is_dirrequiredboolean
- is_symlinkrequiredboolean
- moderequiredstring
- mtime_unix_nsrequiredinteger
- pathrequiredstring
- sandbox_idrequiredstring
- served_bystring | null
- sizerequiredinteger
POST/v1/sandboxes/{id}/files/copy
Auth: API key
Copy a file, or a whole tree with recursive. A symlink is copied as a symlink, never followed.
Parameters
- idrequiredpath · string
Request body FileCopy · application/json
- fromrequiredstring
- overwriteboolean | null
- recursiveboolean | null
- torequiredstring
Answer 200 · FileInfo · application/json
- is_dirrequiredboolean
- is_symlinkrequiredboolean
- moderequiredstring
- mtime_unix_nsrequiredinteger
- pathrequiredstring
- sandbox_idrequiredstring
- served_bystring | null
- sizerequiredinteger
POST/v1/sandboxes/{id}/files/extract
Auth: API key
Unpack a tar that is already inside the sandbox. strip drops leading path components, like tar --strip-components. An entry that is absolute or contains .. is refused.
Parameters
- idrequiredpath · string
Request body FileExtract · application/json
- archiverequiredstring
- intorequiredstring
- stripinteger | null
- Leading path components dropped from each entry, 0–32.
Answer 200 · ExtractResult · application/json
- archiverequiredstring
- entriesinteger | null
- Entries written.
nullfrom the fallback path, which cannot count them without a second pass over the archive — and a number nobody counted is worse than no number. - intorequiredstring
- sandbox_idrequiredstring
- served_bystring | null
GET/v1/sandboxes/{id}/files/list
Auth: API key
List a directory. ?path=, plus ?recursive=1, ?depth=N, ?limit=N and ?hidden=0. Entries carry name, size, mode, uid, gid, mtime and kind. A listing cut short by limit says truncated: true rather than looking like the end of the directory.
Parameters
- idrequiredpath · string
- containsquery · string
- hiddenquery · string
- ignore_casequery · string
- limitquery · integer
- pathquery · string
- patternquery · string
- recursivequery · string
Answer 200 · FileListing · application/json
- entriesrequiredDirEntry[]
- pathrequiredstring
- sandbox_idrequiredstring
- served_bystring | null
- truncatedrequiredboolean
- The listing stopped at
limit. **Not** "the directory ended" — a caller that treats a truncated page as a complete one will report a file as missing when it is merely past the cut.
POST/v1/sandboxes/{id}/files/mkdir
Auth: API key
Create a directory. parents is mkdir -p and makes an existing directory a success; without it a missing parent is a 404 and an existing path is a conflict, which is what a caller using the call as a lock wants.
Parameters
- idrequiredpath · string
Request body FileMkdir · application/json
- modeFileMode | null
- parentsboolean | null
- Create missing parents too.
- pathrequiredstring
Answer 200 · FileInfo · application/json
- is_dirrequiredboolean
- is_symlinkrequiredboolean
- moderequiredstring
- mtime_unix_nsrequiredinteger
- pathrequiredstring
- sandbox_idrequiredstring
- served_bystring | null
- sizerequiredinteger
POST/v1/sandboxes/{id}/files/move
Auth: API key
Rename or move a path. Works across filesystems. Without overwrite an existing destination is a conflict rather than something silently destroyed.
Parameters
- idrequiredpath · string
Request body FileMove · application/json
- fromrequiredstring
- overwriteboolean | null
- torequiredstring
Answer 200 · FileInfo · application/json
- is_dirrequiredboolean
- is_symlinkrequiredboolean
- moderequiredstring
- mtime_unix_nsrequiredinteger
- pathrequiredstring
- sandbox_idrequiredstring
- served_bystring | null
- sizerequiredinteger
GET/v1/sandboxes/{id}/files/search
Auth: API key
Find files under ?path=. ?pattern= is a glob over the file name (*.py); ?contains= is literal text to find inside the files that match, which answers with the line number and the line. ?ignore_case=1, ?limit=N, ?hidden=0. Binary files are skipped rather than printed.
Parameters
- idrequiredpath · string
- containsquery · string
- hiddenquery · string
- ignore_casequery · string
- limitquery · integer
- pathquery · string
- patternquery · string
- recursivequery · string
Answer 200 · SearchResult · application/json
- matchesrequiredSearchMatch[]
- notestring | null
- The cut in words, and how to search the rest. Absent when nothing was cut.
- pathrequiredstring
- sandbox_idrequiredstring
- served_bystring | null
- truncatedrequiredboolean
- truncated_bystring | null
- Why
truncatedis true:entries— a search looks at the first 10,000 entries underpath(by name, a directory's own entries before its subdirectories') and stopped there, so files past them were not searched;matches— it foundlimitmatches and stopped. Absent when nothing was cut.
GET/v1/sandboxes/{id}/files/stat
Auth: API key
Size, mode, mtime and kind for one path. ?path=.
Parameters
- idrequiredpath · string
- pathquery · string
Answer 200 · FileStatView · application/json
- pathrequiredstring
- sandbox_idrequiredstring
- statrequiredFileStat
- Size, mode, modification time and kind for one path, as the sandbox reports them. Every field is optional because the answer is the sandbox's, not ours: a path the sandbox could not describe comes back named but otherwise empty, rather than filled in with zeroes.