Files

The files API operates on the workspace — the working filesystem area at /workspace inside a live sandbox. Every path must resolve inside /workspace; anything else is rejected with path_outside_workspace. Direct reads and writes are capped at 256 KB per file; use download URLs for larger files.

FileEntry and FileStat

List, stat, and write operations return file records with this shape:

List a directory

GET /v1/sandboxes/{sandboxId}/files — requires scope file:read.

Returns the entries of a directory.

curl "https://api.crownest.dev/v1/sandboxes/sbx_abc123/files?path=/workspace/src" \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

{
  "data": [
    {
      "name": "main.py",
      "path": "/workspace/src/main.py",
      "type": "file",
      "sizeBytes": 1204,
      "modifiedAt": "2026-06-11T13:00:00.000Z"
    }
  ]
}

Stat a path

GET /v1/sandboxes/{sandboxId}/files/stat — requires scope file:read.

Returns metadata for a single file or directory.

curl "https://api.crownest.dev/v1/sandboxes/sbx_abc123/files/stat?path=/workspace/src/main.py" \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

Returns 200 with { "file": { ... } }. Errors: file_not_found, path_outside_workspace.

Read a file

GET /v1/sandboxes/{sandboxId}/files/read — requires scope file:read.

Returns file content directly, up to 256 KB. Larger files return file_too_large — fetch those through a download URL instead.

curl "https://api.crownest.dev/v1/sandboxes/sbx_abc123/files/read?path=/workspace/results.json" \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

{
  "content": "{\"accuracy\": 0.97}",
  "encoding": "utf8",
  "sizeBytes": 19,
  "path": "/workspace/results.json"
}

Use encoding=base64 for binary files.

Write a file

PUT /v1/sandboxes/{sandboxId}/files — requires scope file:write.

Writes content to a path, up to 256 KB per request.

curl -X PUT https://api.crownest.dev/v1/sandboxes/sbx_abc123/files \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/workspace/src/config.json",
    "content": "{\"debug\": true}",
    "createParents": true
  }'

Returns 200 with { "file": { ... } }. Errors: file_too_large, file_already_exists (with overwrite: false), parent_directory_not_found (with createParents: false), invalid_file_encoding.

Delete a file

DELETE /v1/sandboxes/{sandboxId}/files — requires scope file:write.

Deletes a file or an empty directory. There is no recursive delete: a non-empty directory returns directory_not_empty.

curl -X DELETE "https://api.crownest.dev/v1/sandboxes/sbx_abc123/files?path=/workspace/tmp.txt" \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

{ "deleted": true }

Create a directory

POST /v1/sandboxes/{sandboxId}/files/mkdir — requires scope file:write.

Creates a directory.

curl -X POST https://api.crownest.dev/v1/sandboxes/sbx_abc123/files/mkdir \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "path": "/workspace/data/raw", "parents": true }'

Returns 200 with { "file": { ... } }.

Move a file

POST /v1/sandboxes/{sandboxId}/files/move — requires scope file:write.

Moves or renames a file or directory.

curl -X POST https://api.crownest.dev/v1/sandboxes/sbx_abc123/files/move \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "/workspace/draft.md", "to": "/workspace/final.md" }'

Returns 200 with { "file": { ... } }. Errors: file_not_found, file_already_exists (with overwrite: false).

Get a file download URL

POST /v1/sandboxes/{sandboxId}/files/download-url — requires scope file:read.

Returns a short-lived URL for downloading a file of any size. This is the path for files over the 256 KB direct read limit.

curl -X POST https://api.crownest.dev/v1/sandboxes/sbx_abc123/files/download-url \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "path": "/workspace/dataset.csv" }'

{
  "url": "https://api.crownest.dev/v1/...",
  "method": "GET",
  "expiresAt": "2026-06-11T13:15:00.000Z"
}

File error codes

These codes are specific to file operations, in addition to the common error codes:

Next steps

• Keep files beyond the sandbox lifetime in Artifacts.
• Generate files with Commands.