> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primeintellect.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Sandbox Endpoint

> Create a new code sandbox

## Rate Limit

500 requests per 60 seconds per IP and token.


## OpenAPI

````yaml https://api.primeintellect.ai/openapi.json post /api/v1/sandbox
openapi: 3.1.0
info:
  title: PI API
  version: 0.1.0
servers:
  - url: https://api.primeintellect.ai
security: []
paths:
  /api/v1/sandbox:
    post:
      tags:
        - Sandbox
      summary: Create Sandbox Endpoint
      description: Create a new code sandbox
      operationId: create_sandbox_endpoint_api_v1_sandbox_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxResponse'
        '401':
          description: Authorization failed
        '422':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateSandboxRequest:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Sandbox name
        docker_image:
          type: string
          minLength: 1
          title: Docker Image
          description: Docker image to run
        start_command:
          anyOf:
            - type: string
            - type: 'null'
          title: Start Command
          description: Command to run in container
        cpu_cores:
          type: number
          maximum: 16
          minimum: 0.1
          title: Cpu Cores
          description: CPU cores required
          default: 1
        memory_gb:
          type: number
          maximum: 64
          minimum: 0.1
          title: Memory Gb
          description: Memory in GB
          default: 2
        disk_size_gb:
          type: number
          maximum: 1000
          minimum: 0.1
          title: Disk Size Gb
          description: Disk size in GB
          default: 10
        gpu_count:
          type: integer
          maximum: 8
          minimum: 0
          title: Gpu Count
          description: Number of GPUs
          default: 0
        gpu_type:
          anyOf:
            - $ref: '#/components/schemas/GPUType'
            - type: 'null'
          description: GPU type (e.g. H100, A100). Required when gpu_count > 0
        vm:
          type: boolean
          title: Vm
          description: >-
            Create a VM sandbox on the VM sandbox infra. Required when
            requesting GPUs.
          default: false
        network_access:
          type: boolean
          title: Network Access
          description: Allow outbound internet access (enabled by default)
          default: true
        timeout_minutes:
          type: integer
          maximum: 1440
          minimum: 1
          title: Timeout Minutes
          description: Max execution time in minutes
          default: 60
        environment_vars:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Environment Vars
          description: Environment variables
        secrets:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Secrets
          description: >-
            Sensitive environment variables. Currently supported for CPU
            sandboxes only; VM sandboxes reject this field.
        labels:
          items:
            type: string
          type: array
          title: Labels
          description: Tags/labels for the sandbox
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
          description: Team ID for team sandboxes
        advanced_configs:
          anyOf:
            - $ref: '#/components/schemas/AdvancedConfigs'
            - type: 'null'
          description: Advanced configuration options
        registry_credentials_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Registry Credentials Id
          description: Registry credentials ID for pulling private images
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
          description: >-
            Cluster region for the sandbox (e.g. us, india). Omit to allow
            automatic placement.
        guaranteed:
          type: boolean
          title: Guaranteed
          description: >-
            Admin/manager only. When true, schedule the sandbox with CPU/memory
            requests equal to its limits (Guaranteed QoS), bypassing the default
            oversubscription multiplier. Not applicable to VM sandboxes.
          default: false
        idempotency_key:
          anyOf:
            - type: string
              maxLength: 128
              minLength: 1
            - type: 'null'
          title: Idempotency Key
          description: Client-generated key used to deduplicate retried create requests.
      type: object
      required:
        - name
        - docker_image
      title: CreateSandboxRequest
    SandboxResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        dockerImage:
          type: string
          title: Dockerimage
        startCommand:
          anyOf:
            - type: string
            - type: 'null'
          title: Startcommand
        cpuCores:
          type: number
          title: Cpucores
        memoryGB:
          type: number
          title: Memorygb
        diskSizeGB:
          type: number
          title: Disksizegb
        diskMountPath:
          type: string
          title: Diskmountpath
        gpuCount:
          type: integer
          title: Gpucount
        gpuType:
          anyOf:
            - $ref: '#/components/schemas/GPUType'
            - type: 'null'
        vm:
          type: boolean
          title: Vm
          default: false
        networkAccess:
          type: boolean
          title: Networkaccess
        status:
          $ref: '#/components/schemas/SandboxStatus'
        timeoutMinutes:
          type: integer
          title: Timeoutminutes
        environmentVars:
          anyOf:
            - type: object
            - type: 'null'
          title: Environmentvars
        advancedConfigs:
          anyOf:
            - type: object
            - type: 'null'
          title: Advancedconfigs
        labels:
          items:
            type: string
          type: array
          title: Labels
        createdAt:
          type: string
          format: date-time
          title: Createdat
        updatedAt:
          type: string
          format: date-time
          title: Updatedat
        startedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Startedat
        terminatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Terminatedat
        exitCode:
          anyOf:
            - type: integer
            - type: 'null'
          title: Exitcode
        errorType:
          anyOf:
            - type: string
            - type: 'null'
          title: Errortype
        errorMessage:
          anyOf:
            - type: string
            - type: 'null'
          title: Errormessage
        userId:
          anyOf:
            - type: string
            - type: 'null'
          title: Userid
        teamId:
          anyOf:
            - type: string
            - type: 'null'
          title: Teamid
        kubernetesJobId:
          anyOf:
            - type: string
            - type: 'null'
          title: Kubernetesjobid
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
        registryCredentialsId:
          anyOf:
            - type: string
            - type: 'null'
          title: Registrycredentialsid
      type: object
      required:
        - id
        - name
        - dockerImage
        - startCommand
        - cpuCores
        - memoryGB
        - diskSizeGB
        - diskMountPath
        - gpuCount
        - networkAccess
        - status
        - timeoutMinutes
        - environmentVars
        - advancedConfigs
        - createdAt
        - updatedAt
        - startedAt
        - terminatedAt
        - userId
        - teamId
        - kubernetesJobId
      title: SandboxResponse
    ErrorResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
          title: Errors
      type: object
      required:
        - errors
      title: ErrorResponse
    GPUType:
      type: string
      enum:
        - CPU_NODE
        - A10_24GB
        - A100_80GB
        - A100_40GB
        - A30_24GB
        - A40_48GB
        - B200_180GB
        - B300_262GB
        - GB200
        - GB300
        - RTX3070_8GB
        - RTX3070_8GB
        - RTX3080_10GB
        - RTX3080Ti_12GB
        - RTX3090_24GB
        - RTX3090Ti_24GB
        - RTX4070Ti_12GB
        - RTX4080_16GB
        - RTX4080Ti_16GB
        - RTX4090_24GB
        - RTX5090_32GB
        - H100_80GB
        - H200_96GB
        - GH200_96GB
        - H200_141GB
        - GH200_480GB
        - GH200_624GB
        - L4_24GB
        - L40_48GB
        - L40S_48GB
        - RTX4000_8GB
        - RTX5000_16GB
        - RTX6000_24GB
        - RTX8000_48GB
        - RTX2000Ada_16GB
        - RTX4000Ada_20GB
        - RTX5000Ada_32GB
        - RTX6000Ada_48GB
        - A2000_6GB
        - A4000_16GB
        - A4500_20GB
        - A5000_24GB
        - A6000_48GB
        - V100_16GB
        - V100_32GB
        - P100_16GB
        - T4_16GB
        - P4_8GB
        - P40_24GB
        - RTX_PRO_6000B_96GB
      title: GPUType
    AdvancedConfigs:
      properties: {}
      additionalProperties: true
      type: object
      title: AdvancedConfigs
    SandboxStatus:
      type: string
      enum:
        - PENDING
        - PROVISIONING
        - RUNNING
        - PAUSED
        - ERROR
        - TERMINATED
      title: SandboxStatus
    ErrorDetail:
      properties:
        param:
          type: string
          title: Param
        details:
          type: string
          title: Details
      type: object
      required:
        - param
        - details
      title: ErrorDetail
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````