> ## Documentation Index > Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt > Use this file to discover all available pages before exploring further. # List all sandboxes > Returns sandboxes belonging to the authenticated team, ordered by creation time (newest first) by default. ## Pagination, sorting, and search Pass `limit` (and `offset`) to fetch one page at a time; the `X-Total-Count` response header reports the total across all pages. Omitting `limit` returns the full list, so existing unpaginated callers are unaffected. Sort with `sort` + `order`, filter by exact `status`, and search names with `q` (case-insensitive substring). ## Filtering by metadata Any query parameter prefixed `metadata.` is treated as a filter clause: `?metadata.env=prod&metadata.owner=agent-7`. Multiple filters AND together — a sandbox matches only if every key/value pair is present in its metadata. Values are compared as exact strings; there is no type coercion or substring matching. ## OpenAPI ````yaml https://raw.githubusercontent.com/superserve-ai/sandbox/refs/heads/main/api/openapi.yaml get /sandboxes openapi: 3.1.0 info: title: Superserve API version: 0.1.0 description: > Superserve provides sandbox infrastructure to run AI agents in the cloud. Powered by Firecracker MicroVMs. ## Sandbox lifecycle ``` active <--> paused --> deleted ``` A sandbox is `active` when running and `paused` after being paused. Resuming a paused sandbox returns it to `active`. Deleting releases all resources. | Endpoint | What it does | |----------|-------------| | `POST /sandboxes` | Create a new sandbox (optionally `from_template`) | | `PATCH /sandboxes/:id` | Partially update a running sandbox (e.g. network rules) | | `POST /sandboxes/:id/pause` | Snapshot full state, suspend the VM | | `POST /sandboxes/:id/resume` | Restore from snapshot, continue where it left off | | `DELETE /sandboxes/:id` | Delete sandbox and all resources | ## Sandbox environment By default sandboxes boot from the curated `superserve/base` template (Ubuntu 24.04, 1 vCPU, 1 GB RAM, 4 GB disk, with Python 3.12, Node.js 22, npm, git, curl, and build-essential pre-installed). Callers can override with any template name (e.g. `superserve/python-3.11`, `superserve/node-22`) or a team-owned template UUID via the `from_template` field on `POST /sandboxes`. ## Files and commands `/files`, `/exec`, and `/exec/stream` run against a single sandbox and use its `X-Access-Token` (returned by create, resume, and activate), not the team API key. Two host forms reach them: - `https://sandbox.superserve.ai/...` with `X-Superserve-Sandbox-Id: `. - `https://boxd-{sandbox_id}.sandbox.superserve.ai/...` — no routing header needed. contact: name: Superserve Team license: name: Proprietary servers: - url: https://api.superserve.ai description: Production security: [] paths: /sandboxes: get: tags: - Sandboxes summary: List all sandboxes description: | Returns sandboxes belonging to the authenticated team, ordered by creation time (newest first) by default. ## Pagination, sorting, and search Pass `limit` (and `offset`) to fetch one page at a time; the `X-Total-Count` response header reports the total across all pages. Omitting `limit` returns the full list, so existing unpaginated callers are unaffected. Sort with `sort` + `order`, filter by exact `status`, and search names with `q` (case-insensitive substring). ## Filtering by metadata Any query parameter prefixed `metadata.` is treated as a filter clause: `?metadata.env=prod&metadata.owner=agent-7`. Multiple filters AND together — a sandbox matches only if every key/value pair is present in its metadata. Values are compared as exact strings; there is no type coercion or substring matching. operationId: listSandboxes parameters: - name: metadata.{key} in: query required: false description: | Filter sandboxes whose metadata contains an exact `{key}: ` pair. Repeat with different keys to AND multiple filters. Values are always strings. Example: `?metadata.env=prod`. schema: type: string - $ref: '#/components/parameters/ListSearch' - name: status in: query required: false description: Filter by exact sandbox status. Unknown values are a `400`. schema: type: string enum: - starting - active - pausing - paused - resuming - failed - deleted - name: sort in: query required: false description: Column to sort by (paired with `order`). schema: type: string enum: - created_at - name - status default: created_at - $ref: '#/components/parameters/SortOrder' - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/PageOffset' responses: '200': description: List of sandboxes belonging to the authenticated team headers: X-Total-Count: $ref: '#/components/headers/TotalCount' content: application/json: schema: type: array items: $ref: '#/components/schemas/SandboxListItem' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - apiKey: [] components: parameters: ListSearch: name: q in: query required: false description: Case-insensitive substring match on the resource `name`. schema: type: string SortOrder: name: order in: query required: false description: Sort direction applied to `sort`. schema: type: string enum: - asc - desc default: desc PageLimit: name: limit in: query required: false description: | Maximum rows to return (page size). Omit to return the full list unpaginated — the default, preserved for backward compatibility with callers that page client-side. Values above 200 are clamped to 200. schema: type: integer minimum: 1 maximum: 200 PageOffset: name: offset in: query required: false description: Rows to skip before the page. Combine with `limit` to paginate. schema: type: integer minimum: 0 default: 0 headers: TotalCount: description: | Total rows matching the query across all pages, ignoring `limit` and `offset`. Read this alongside a `limit`/`offset` request to render pagination controls (page count, "X–Y of Z"). schema: type: integer format: int64 schemas: SandboxListItem: description: Sandbox shape returned by list endpoints. type: object properties: id: $ref: '#/components/schemas/PublicSandboxId' name: type: string status: type: string enum: - active - paused - resuming description: > Current state of the sandbox. `active` means running; `paused` means paused and awaiting resume. `resuming` is a transient state observed while the platform restores a paused sandbox (e.g. via auto-resume on `/exec`); clients should retry shortly. vcpu_count: type: integer memory_mib: type: integer snapshot_id: type: string format: uuid description: ID of the latest snapshot (present after a pause). created_at: type: string format: date-time timeout_seconds: type: integer format: int32 description: > Auto-pause timeout in seconds, if configured. Absent when auto-pause is disabled. auto_delete_seconds: type: integer format: int32 description: > Garbage-collection window for the paused state, if configured. Absent when auto-delete is disabled. auto_delete_at: type: string format: date-time description: > When the sandbox will be deleted. Present only while the sandbox is paused with `auto_delete_seconds` configured. The deadline is armed when the sandbox pauses (or when the setting is applied to an already-paused sandbox) and cleared on resume. network: $ref: '#/components/schemas/NetworkConfig' description: > Current egress allow/deny rules, if any have been configured. Absent when the sandbox uses default network settings. metadata: type: object additionalProperties: type: string description: > User-supplied tags attached at creation. Always present — sandboxes created without metadata return `{}` rather than being absent. example: env: prod owner: agent-7 preview_access: type: string enum: - legacy_public - public - private description: | Default access for newly published ports. `public` and `private` are strict modes; existing published rows keep their own access. `legacy_public` may be returned for an older sandbox and preserves all-port behavior until updated to a strict mode. PublicSandboxId: type: string pattern: >- ^(sb-[a-z0-9]+-)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ description: > Public sandbox ID: a bare UUID, or the region-tagged form `sb--` (e.g. `sb-use-1b4e28ba-…`). Treat as an opaque string; the tagged form routes the request to the sandbox's home region. Endpoints accept both forms interchangeably. NetworkConfig: type: object description: > Egress network rules for a sandbox. `allow_out` accepts CIDRs (e.g. `8.8.8.8/32`) and domain names (e.g. `api.openai.com`, `*.github.com`). `deny_out` accepts CIDRs only. Private ranges (10/8, 172.16/12, 192.168/16, 127/8, 169.254/16) are always blocked regardless of rules. properties: allow_out: type: array items: type: string description: CIDRs or domains to allow. example: - api.openai.com - '*.github.com' - 8.8.8.8/32 deny_out: type: array items: type: string description: >- CIDRs to deny. Use `0.0.0.0/0` to block all traffic not in `allow_out`. example: - 0.0.0.0/0 Error: type: object description: | Error envelope. `error.code` is a stable, machine-readable identifier (e.g. `bad_request`, `not_found`, `conflict`, `rate_limited`, `too_many_builds`, `too_many_templates`, `too_many_sandboxes`, `image_pull_failed`, `step_failed`, `snapshot_failed`, `start_cmd_failed`, `ready_cmd_failed`, `build_failed`). `error.message` is human-readable and may change between releases; clients should branch on `code`, not `message`. properties: error: type: object properties: code: type: string message: type: string responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: > Rate limit hit — the caller's per-team request budget is temporarily exhausted. Response body uses error code `rate_limited`. Retry after a short backoff; the bucket refills continuously. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: X-API-Key ````