Skip to content
Try for free
On this page

Sandboxes

Create sandbox

Create a uniquely named dependency environment. Requires workspace Admin access and a configured remote Function runtime. With billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Poll Get sandbox for `buildStatus`; `null` means no image build is needed. Invalid dependencies return `400` with field details. Creates and updates share a rate limit; respect `Retry-After`. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:write`.

POST/api/v2/sandboxes

Create a uniquely named dependency environment. Requires workspace Admin access and a configured remote Function runtime. With billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Poll Get sandbox for buildStatus; null means no image build is needed. Invalid dependencies return 400 with field details. Creates and updates share a rate limit; respect Retry-After. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:write.

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:write

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:write.

Request body

Required

Name, language, and dependency set of a new sandbox.

object

Name, language, and dependency set of a new sandbox.

6 fields
workspaceIdstringRequired

Workspace in which to create the sandbox.

minLength
1
maxLength
128
namestringRequired

Display name, unique within the workspace; 1 to 64 characters.

minLength
1
maxLength
64
languagestringRequired

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

enum
["javascript","python"]
dependenciesarray

Package specifiers installed into the sandbox, one per entry.

default
[]
maxItems
1000
Schema details
Array itemstring
maxLength
2000
cliToolsarray

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

default
[]
maxItems
10
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"]
systemPackagesarray

Debian packages installed into the sandbox, one per entry.

default
[]
maxItems
1000
Schema details
Array itemstring
maxLength
2000

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "name": "data-tools",
  "language": "python",
  "dependencies": [
    "pandas==2.2.2",
    "requests"
  ],
  "systemPackages": [
    "graphviz"
  ]
}

Responses

201

The sandbox was created; a build is scheduled where the deployment prebuilds images.

object

The created sandbox. buildStatus is pending while an image builds and null where nothing is built.

1 field
dataobjectRequired

Response data.

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.

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": "pending",
    "errorCode": null,
    "errorMessage": null,
    "errorDetail": null,
    "builtAt": null,
    "createdAt": "2026-06-01T09:14:00.000Z",
    "updatedAt": "2026-06-20T14:02:11.000Z"
  }
}

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