Sandbox API Reference

Base URL: /v1

All endpoints require a Bearer token in the Authorization header unless otherwise noted.

Authorization: Bearer <API-KEY>

Error Format

All errors return a JSON body:

{
  "error": "Human-readable error message"
}

Common error codes used across endpoints:

Code	Meaning
401	Missing or invalid authentication
403	Authenticated but not authorized for the resource
404	Resource not found
500	Internal server / sandbox execution error
503	Database service unavailable

POST /v1/execute

Execute Python or Bash code in a sandboxed Modal environment.

Request Body

Field	Type	Required	Default	Description
`language`	`string`	Yes	—	`"python"` or `"bash"`
`code`	`string`	Yes	—	Code to execute (min 1 character)
`session_id`	`string \| null`	No	`null`	Session ID for a persistent sandbox. If omitted a one-shot sandbox is created and destroyed after execution.
`env_vars`	`object \| null`	No	`null`	Key-value map of environment variables to inject into the sandbox.
`file_ids`	`string[] \| null`	No	`null`	List of file IDs to inject into `/workspace` before execution.

{
  "language": "python",
  "code": "print('hello')",
  "session_id": null,
  "env_vars": { "MY_VAR": "value" },
  "file_ids": ["f-abc123", "f-def456"]
}

Response `200 OK`

Field	Type	Description
`session_id`	`string`	The session the code ran in (generated if not provided)
`stdout`	`string`	Standard output from execution
`stderr`	`string`	Standard error from execution
`return_code`	`int`	Process exit code (`0` = success)
`files`	`FileRef[]`	Output files produced during execution

Each FileRef:

Field	Type	Description
`file_id`	`string`	Unique file identifier (use with `/v1/files/{file_id}`)
`filename`	`string`	Original filename

{
  "session_id": "abc123",
  "stdout": "hello\n",
  "stderr": "",
  "return_code": 0,
  "files": [
    { "file_id": "f-xyz", "filename": "output.png" }
  ]
}

Errors

Code	Cause
401	Invalid or missing Bearer token
403	One or more file IDs belong to a different user
404	One or more file IDs not found
422	Validation error (bad `language` value, empty `code`, etc.)
500	Sandbox execution failure

Notes

When file_ids is provided, files are injected into /workspace before code execution.
File ownership is validated — users can only inject their own files.
File injection is atomic: if any file ID is invalid or access is denied, execution does not proceed.

POST /v1/sessions

Create a new persistent sandbox session, optionally pre-populated with existing files.

Request Body

Field	Type	Required	Default	Description
`env_vars`	`object \| null`	No	`null`	Key-value map of environment variables to inject into the sandbox.
`file_ids`	`string[] \| null`	No	`null`	List of file IDs to inject into the session's `/workspace` directory on creation.

{
  "env_vars": { "API_TOKEN": "secret" },
  "file_ids": ["f-abc123", "f-def456"]
}

Response `201 Created`

Field	Type	Description
`session_id`	`string`	ID of the newly created session
`created`	`bool`	Always `true` for this endpoint

{
  "session_id": "sess-abc123",
  "created": true
}

Errors

Code	Cause
401	Invalid or missing Bearer token
403	One or more file IDs belong to a different user
404	One or more file IDs not found
500	Sandbox creation failure

Notes

File ownership is validated — users can only inject their own files.
The operation is atomic: if any file ID is invalid or access is denied, no session is created.

GET /v1/sessions

List all active sandbox sessions.

Parameters

None.

Response `200 OK`

Field	Type	Description
`sessions`	`string[]`	List of active session IDs

{
  "sessions": ["sess-abc123", "sess-def456"]
}

Errors

Code	Cause
401	Invalid or missing Bearer token

GET /v1/sessions/{session_id}

Get information about a specific session.

Path Parameters

Parameter	Type	Description
`session_id`	`string`	The session ID

Response `200 OK`

Field	Type	Description
`session_id`	`string`	The requested session ID
`created`	`bool`	Always `false` for this endpoint (session already existed)

{
  "session_id": "sess-abc123",
  "created": false
}

Errors

Code	Cause
401	Invalid or missing Bearer token
404	Session not found

DELETE /v1/sessions/{session_id}

Destroy a sandbox session and terminate its underlying sandbox.

Path Parameters

Parameter	Type	Description
`session_id`	`string`	The session ID to destroy

Response `204 No Content`

Empty body.

Errors

Code	Cause
401	Invalid or missing Bearer token
404	Session not found

POST /v1/sessions/{session_id}/files

Inject existing files into a running session's /workspace directory.

Path Parameters

Parameter	Type	Description
`session_id`	`string`	The session ID to inject files into

Request Body

Field	Type	Required	Description
`file_ids`	`string[]`	Yes	List of file IDs to inject (minimum 1)

{
  "file_ids": ["f-abc123", "f-def456"]
}

Response `204 No Content`

Empty body.

Errors

Code	Cause
401	Invalid or missing Bearer token
403	One or more file IDs belong to a different user
404	Session not found, or one or more file IDs not found

Notes

File ownership is validated — users can only inject their own files.
The operation is atomic: if any file ID is invalid or access is denied, no files are injected.
Files are copied to the session's /workspace directory with their original filenames.

GET /v1/files

List files owned by the authenticated user (paginated).

Query Parameters

Parameter	Type	Required	Default	Constraints	Description
`limit`	`int`	No	`50`	`1 – 100`	Number of files per page
`offset`	`int`	No	`0`	`>= 0`	Number of files to skip

Response `200 OK`

Field	Type	Description
`files`	`FileInfo[]`	Array of file metadata objects
`total`	`int`	Total number of files owned by the user
`limit`	`int`	Limit used for this request
`offset`	`int`	Offset used for this request

Each FileInfo:

Field	Type	Description
`file_id`	`string`	Unique file identifier
`filename`	`string`	Original filename
`mime_type`	`string`	MIME type (default `application/octet-stream`)
`size_bytes`	`int`	File size in bytes
`session_id`	`string \| null`	Session that produced the file, if any
`created_at`	`string`	ISO 8601 creation timestamp

{
  "files": [
    {
      "file_id": "f-xyz",
      "filename": "output.png",
      "mime_type": "image/png",
      "size_bytes": 24576,
      "session_id": "sess-abc123",
      "created_at": "2025-06-01T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Errors

Code	Cause
401	Invalid or missing Bearer token
422	Invalid `limit` or `offset` value
503	Database service unavailable

POST /v1/files

Upload a file to cloud storage, optionally injecting it into a sandbox session's /workspace directory.

Query Parameters

Parameter	Type	Required	Default	Description
`session_id`	`string \| null`	No	`null`	Optional session ID to inject the file into the sandbox's `/workspace`

Request Body

Content-Type: multipart/form-data

Field	Type	Required	Description
`file`	`binary`	Yes	The file to upload

Response `200 OK`

Field	Type	Description
`file_id`	`string`	Unique file identifier
`filename`	`string`	Original filename
`mime_type`	`string`	MIME type (default `application/octet-stream`)
`size_bytes`	`int`	File size in bytes
`session_id`	`string \| null`	Session the file was injected into, if any
`created_at`	`string`	ISO 8601 creation timestamp

{
  "file_id": "f-abc123",
  "filename": "data.csv",
  "mime_type": "text/csv",
  "size_bytes": 1024,
  "session_id": "sess-xyz789",
  "created_at": "2025-06-01T12:00:00Z"
}

Errors

Code	Cause
401	Invalid or missing Bearer token
422	Validation error (missing file, etc.)

GET /v1/files/{file_id}

Download a file by its ID. Returns the raw file content with the appropriate Content-Type header. Ownership is enforced — authenticated users can only access their own files.

Path Parameters

Parameter	Type	Description
`file_id`	`string`	The file ID

Response `200 OK`

Body: Raw file bytes
Content-Type: The file's MIME type (e.g. image/png, text/csv)
Content-Disposition: inline; filename="<original_filename>"

Errors

Code	Cause
401	Invalid or missing Bearer token
403	File belongs to a different user
404	File not found (or file storage not configured)

DELETE /v1/files/{file_id}

Delete a file by its ID. Removes both the stored blob and the database record. Ownership is enforced.

Path Parameters

Parameter	Type	Description
`file_id`	`string`	The file ID to delete

Response `204 No Content`

Empty body.

Errors

Code	Cause
401	Invalid or missing Bearer token
403	File belongs to a different user
404	File not found (or file storage not configured)

GET /v1/executions/{execution_id}

Retrieve a detailed execution log including the code that was run and its output.

Path Parameters

Parameter	Type	Description
`execution_id`	`string`	UUID of the execution log entry

Response `200 OK`

Field	Type	Description
`id`	`string`	Execution log ID
`endpoint`	`string`	The API endpoint that was called (e.g. `/v1/execute`)
`method`	`string`	HTTP method (`POST`)
`status_code`	`int \| null`	HTTP status code of the execution
`duration_ms`	`float \| null`	Execution duration in milliseconds
`session_id`	`string \| null`	Session the code ran in
`language`	`string \| null`	`"python"` or `"bash"`
`code`	`string \| null`	The code that was executed
`stdout`	`string \| null`	Standard output
`stderr`	`string \| null`	Standard error
`return_code`	`int \| null`	Process exit code
`files_count`	`int`	Number of output files produced
`error`	`string \| null`	Error message if the execution failed
`request_meta`	`object \| null`	Additional metadata (e.g. `has_env_vars`, `file_ids`, `files`)
`created_at`	`string`	ISO 8601 timestamp

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "endpoint": "/v1/execute",
  "method": "POST",
  "status_code": 200,
  "duration_ms": 1234.56,
  "session_id": "sess-abc123",
  "language": "python",
  "code": "print('hello')",
  "stdout": "hello\n",
  "stderr": "",
  "return_code": 0,
  "files_count": 0,
  "error": null,
  "request_meta": { "has_env_vars": false, "file_ids": [], "files": [] },
  "created_at": "2025-06-01T12:00:00Z"
}

Errors

Code	Cause
401	Invalid or missing Bearer token
403	Execution belongs to a different user
404	Execution not found or `execution_id` is not a valid UUID
503	Database service unavailable

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

Sandbox API Reference

Error Format

POST /v1/execute

Request Body

Response 200 OK

Errors

Notes

POST /v1/sessions

Request Body

Response 201 Created

Errors

Notes

GET /v1/sessions

Parameters

Response 200 OK

Errors

GET /v1/sessions/{session_id}

Path Parameters

Response 200 OK

Errors

DELETE /v1/sessions/{session_id}

Path Parameters

Response 204 No Content

Errors

POST /v1/sessions/{session_id}/files

Path Parameters

Request Body

Response 204 No Content

Errors

Notes

GET /v1/files

Query Parameters

Response 200 OK

Errors

POST /v1/files

Query Parameters

Request Body

Response 200 OK

Errors

GET /v1/files/{file_id}

Path Parameters

Response 200 OK

Errors

DELETE /v1/files/{file_id}

Path Parameters

Response 204 No Content

Errors

GET /v1/executions/{execution_id}

Path Parameters

Response 200 OK

Errors

Response `200 OK`

Response `201 Created`

Response `200 OK`

Response `200 OK`

Response `204 No Content`

Response `204 No Content`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `204 No Content`

Response `200 OK`