Skip to content
Try for free
On this page

Sandboxes

List sandboxes

List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Requires workspace read access. Existing sandboxes remain visible after a plan downgrade. OAuth scope: `api:read`.

GET/api/v2/sandboxes

List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Requires workspace read access. Existing sandboxes remain visible after a plan downgrade.

OAuth scope: api:read.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:read.

Query parameters

workspaceIdstringRequired

Workspace that owns the sandbox.

minLength
1
maxLength
128
searchstring

Case-insensitive substring match against the sandbox name.

minLength
1
maxLength
200
sortBystring

Field used to sort the result. Do not rely on case-insensitive ordering when sorting by name.

default
name
enum
["name","createdAt","updatedAt"]
sortOrderstring

Sort direction.

default
asc
enum
["asc","desc"]
limitinteger

Maximum sandboxes to return per page. Must be a whole number from 1 to 100. Defaults to 50.

default
50
minimum
1
maximum
100
cursorstring

Opaque cursor from the previous page. Send it back with the same sort and filters; only limit may change. Change anything else and pagination must restart without a cursor.

minLength
1

Responses

200

Sandboxes defined in the workspace.

object

Sandboxes defined in the workspace.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

A workspace sandbox: a reusable dependency set that Function blocks execute against.

13 fields
idstringRequired

Unique sandbox identifier.

namestringRequired

Display name, unique within the workspace.

languagestringRequired

Dependency ecosystem: javascript installs from npm, python from PyPI.

enum
["javascript","python"]
dependenciesarrayRequired

Package specifiers installed into the sandbox, one per entry.

Schema details
Array itemstring
cliToolsarrayRequired

Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates.

Schema details
Array itemstring
enum
["google-cloud-cli@577.0.0-r1","aws-cli@2.36.15-r1","azure-cli@2.89.0-r1","doctl@1.166.0-r1","github-cli@2.97.0-r1","gitlab-cli@1.111.0-r1","kubectl@1.36.3-r1","helm@4.2.3-r1","kustomize@5.8.1-r1","argocd@3.4.6-r1","terraform@1.15.8-r1","pulumi@3.255.0-r1","supabase-cli@2.111.0-r1","firebase-cli@15.25.1-r1","flyctl@0.4.78-r1","railway-cli@5.30.4-r1","stripe-cli@1.45.0-r1","duckdb@1.5.5-r1","rclone@1.75.0-r1","restic@0.19.1-r1","minio-mc@RELEASE.2025-08-13T08-35-41Z-r1","mongosh@2.9.2-r1","sops@3.13.3-r1","age@1.3.1-r1"]
systemPackagesarrayRequired

Debian packages installed into the sandbox, one per entry.

Schema details
Array itemstring
buildStatusvalueRequired

Image build state. null when the deployment installs dependencies at run time and has nothing to build.

Schema details

Any of

Option 1string
enum
["pending","building","ready","failed"]
Option 2null
errorCodevalueRequired

Classified build failure code, or null.

Schema details

Any of

Option 1string
Option 2null
errorMessagevalueRequired

Human-readable build failure summary, or null.

Schema details

Any of

Option 1string
Option 2null
errorDetailvalueRequired

Tail of the installer log for a failed build, or null.

Schema details

Any of

Option 1string
Option 2null
builtAtvalueRequired

ISO 8601 timestamp when the current image finished building, or null.

Schema details

Any of

Option 1string
format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Option 2null
createdAtstringRequired

ISO 8601 timestamp when the sandbox was created.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAtstringRequired

ISO 8601 timestamp when the sandbox was last updated.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Additional properties are not allowed.

nextCursorvalueRequired

Opaque cursor for the next page. Send it back as cursor; null means there are no more pages. Do not construct a cursor yourself.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Response example 1

json
{
  "data": [
    {
      "id": "V1StGXR8Z5jdHi6BmyT",
      "name": "data-tools",
      "language": "python",
      "dependencies": [
        "pandas==2.2.2",
        "requests"
      ],
      "cliTools": [],
      "systemPackages": [
        "graphviz"
      ],
      "buildStatus": "ready",
      "errorCode": null,
      "errorMessage": null,
      "errorDetail": null,
      "builtAt": "2026-06-20T14:05:40.000Z",
      "createdAt": "2026-06-01T09:14:00.000Z",
      "updatedAt": "2026-06-20T14:02:11.000Z"
    }
  ],
  "nextCursor": null
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit