---
title: "Files · API reference · Promigence"
description: "The Promigence API's files routes: 12 in all, with parameters, request bodies and answers."
url: "https://www.promigence.ai/docs/reference/api/files"
site: "Promigence"
---

[API reference](https://www.promigence.ai/docs/reference/api)

# Files

12 routes of the published API contract, generated from it.

### GET/v1/sandboxes/{id}/files

Auth: API key

Stream a file out. `?path=`.

#### Parameters

idrequiredpath · string

pathquery · string

#### Answer 200 · string · application/octet-stream

### 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 is `644`.

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; `null` when 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. `null` from 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 `truncated` is true: `entries` — a search looks at the first 10,000 entries under `path` (by name, a directory's own entries before its subdirectories') and stopped there, so files past them were not searched; `matches` — it found `limit` matches 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.

[Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors)