Skip to main content
POST
/
sandboxes
Create sandbox
curl --request POST \
  --url https://api.blaxel.ai/v0/sandboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "name": "my-resource",
    "displayName": "My Resource",
    "labels": {}
  },
  "spec": {
    "enabled": true,
    "lifecycle": {
      "expirationPolicies": [
        {
          "action": "delete",
          "type": "ttl-idle",
          "value": "24h"
        }
      ]
    },
    "network": {
      "egressGatewayName": "my-egress-gateway",
      "vpcName": "my-vpc"
    },
    "region": "us-pdx-1",
    "runtime": {
      "envs": [
        {
          "name": "MY_ENV_VAR",
          "secret": true,
          "value": "my-value"
        }
      ],
      "expires": "2025-12-31T23:59:59Z",
      "image": "blaxel/base-image:latest",
      "memory": 4096,
      "ports": [
        {
          "target": 8080,
          "name": "http",
          "protocol": "HTTP"
        }
      ],
      "ttl": "24h"
    },
    "volumes": [
      {
        "mountPath": "/mnt/data",
        "name": "my-volume",
        "readOnly": false
      }
    ]
  }
}
'
{
  "metadata": {
    "name": "my-resource",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "createdBy": "<string>",
    "updatedBy": "<string>",
    "displayName": "My Resource",
    "labels": {},
    "plan": "<string>",
    "url": "<string>",
    "workspace": "<string>"
  },
  "spec": {
    "enabled": true,
    "lifecycle": {
      "expirationPolicies": [
        {
          "action": "delete",
          "type": "ttl-idle",
          "value": "24h"
        }
      ]
    },
    "network": {
      "egressGatewayName": "my-egress-gateway",
      "vpcName": "my-vpc"
    },
    "region": "us-pdx-1",
    "runtime": {
      "envs": [
        {
          "name": "MY_ENV_VAR",
          "secret": true,
          "value": "my-value"
        }
      ],
      "expires": "2025-12-31T23:59:59Z",
      "image": "blaxel/base-image:latest",
      "memory": 4096,
      "ports": [
        {
          "target": 8080,
          "name": "http",
          "protocol": "HTTP"
        }
      ],
      "ttl": "24h"
    },
    "volumes": [
      {
        "mountPath": "/mnt/data",
        "name": "my-volume",
        "readOnly": false
      }
    ]
  },
  "events": [
    {
      "canaryRevision": "<string>",
      "message": "Deployment successful",
      "revision": "rev-abc123",
      "status": "DEPLOYED",
      "time": "2025-01-15T10:30:00Z",
      "type": "deployment"
    }
  ],
  "expiresIn": 123,
  "lastUsedAt": "<string>",
  "status": "DELETING"
}

Authorizations

​
Authorization
string
header
required

OAuth2 authentication with JWT tokens

Query Parameters

​
createIfNotExist
boolean
default:false

If true, return existing sandbox instead of 409 error when sandbox exists and is not in FAILED/TERMINATED/TERMINATING state

Body

application/json

Lightweight virtual machine for secure AI code execution. Sandboxes resume from standby in under 25ms and automatically scale to zero after inactivity, preserving memory state including running processes and filesystem.

​
metadata
object
required

Common metadata fields shared by all Blaxel resources including name, labels, timestamps, and ownership information

​
spec
object
required

Configuration for a sandbox including its image, memory, ports, region, and lifecycle policies

Response

successful operation

Lightweight virtual machine for secure AI code execution. Sandboxes resume from standby in under 25ms and automatically scale to zero after inactivity, preserving memory state including running processes and filesystem.

​
metadata
object
required

Common metadata fields shared by all Blaxel resources including name, labels, timestamps, and ownership information

​
spec
object
required

Configuration for a sandbox including its image, memory, ports, region, and lifecycle policies

​
events
object[]

Events happening on a resource deployed on Blaxel

​
expiresIn
integer

Time in seconds until the sandbox is automatically deleted based on TTL and lifecycle policies. Only present for sandboxes with lifecycle configured.

​
lastUsedAt
string

Last time the sandbox was used (read-only, managed by the system)

​
status
enum<string>

Deployment status of a resource deployed on Blaxel

Available options:
DELETING,
TERMINATED,
FAILED,
DEACTIVATED,
DEACTIVATING,
UPLOADING,
BUILDING,
DEPLOYING,
DEPLOYED