openapi: 3.0.0
info:
  title: CodeSandbox meta sandbox API
  version: '2023-07-01'
  description: The CodeSandbox API provides programmatic access to create, manage, and control sandboxes and virtual machines (devboxes) backed by Firecracker microVMs. Authenticated via Bearer token obtained from codesandbox.io/t/api.
  contact:
    url: https://codesandbox.io/docs/sdk
  x-source: https://raw.githubusercontent.com/codesandbox/codesandbox-sdk/main/openapi.json
servers:
- url: https://api.codesandbox.io
security: []
tags:
- name: sandbox
  description: Browser and VM sandbox management
paths:
  /sandbox:
    get:
      operationId: sandbox/list
      summary: List Sandboxes
      description: 'List sandboxes from the current workspace with optional filters.

        Results are limited to a maximum of 50 sandboxes per request.

        '
      tags:
      - sandbox
      parameters:
      - name: tags
        in: query
        required: false
        description: Comma-separated list of tags to filter by
        example: sha-123,feature-x
        schema:
          type: string
      - name: order_by
        in: query
        required: false
        description: Field to order results by
        example: updated_at
        schema:
          default: updated_at
          enum:
          - inserted_at
          - updated_at
      - name: direction
        in: query
        required: false
        description: Order direction
        example: desc
        schema:
          default: desc
          enum:
          - asc
          - desc
      - name: page_size
        in: query
        required: false
        description: Maximum number of sandboxes to return in a single response
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 50
      - name: page
        in: query
        required: false
        description: Page number to return
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: status
        in: query
        required: false
        description: If true, only returns VMs for which a heartbeat was received in the last 30 seconds.
        schema:
          enum:
          - running
      responses:
        '200':
          description: Sandbox List Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxListResponse'
      security:
      - authorization:
        - sandbox:read
    post:
      operationId: sandbox/create
      summary: Create a Sandbox
      description: 'Create a new sandbox in the current workspace with file contents

        '
      tags:
      - sandbox
      parameters: []
      requestBody:
        description: Sandbox Create Request
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxCreateRequest'
      responses:
        '201':
          description: Sandbox Create Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxCreateResponse'
      security:
      - authorization:
        - sandbox:create
  /sandbox/{id}:
    get:
      operationId: sandbox/get
      summary: Get a Sandbox
      description: 'Retrieve a sandbox by its ID

        '
      tags:
      - sandbox
      parameters:
      - name: id
        in: path
        required: true
        description: Short ID of the sandbox to retrieve
        example: new
        schema:
          type: string
      responses:
        '200':
          description: Sandbox Get Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxGetResponse'
      security:
      - authorization:
        - sandbox:read
  /sandbox/{id}/fork:
    post:
      operationId: sandbox/fork
      summary: Fork a Sandbox
      description: 'Fork an existing sandbox to the current workspace

        '
      tags:
      - sandbox
      parameters:
      - name: id
        in: path
        required: true
        description: Short ID of the sandbox to fork
        example: new
        schema:
          type: string
      requestBody:
        description: Sandbox Fork Request
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxForkRequest'
      responses:
        '201':
          description: Sandbox Fork Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxForkResponse'
      security:
      - authorization:
        - sandbox:create
components:
  schemas:
    Response:
      title: Response
      type: object
      properties:
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    SandboxForkResponse:
      title: SandboxForkResponse
      type: object
      allOf:
      - $ref: '#/components/schemas/Response'
      - type: object
        properties:
          data:
            type: object
            required:
            - alias
            - id
            - title
            properties:
              id:
                type: string
              alias:
                type: string
              title:
                type: string
                nullable: true
              start_response:
                type: object
                nullable: true
                description: VM start response. Only present when start_options were provided in the request.
    SandboxCreateResponse:
      title: SandboxCreateResponse
      type: object
      allOf:
      - $ref: '#/components/schemas/Response'
      - type: object
        properties:
          data:
            type: object
            required:
            - alias
            - id
            - title
            properties:
              id:
                type: string
              alias:
                type: string
              title:
                type: string
                nullable: true
    Sandbox:
      title: Sandbox
      type: object
      required:
      - id
      - privacy
      - is_frozen
      - created_at
      - updated_at
      - tags
      - settings
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        is_frozen:
          type: boolean
        privacy:
          type: integer
        title:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
        settings:
          type: object
          properties:
            use_pint:
              type: boolean
    SandboxListResponse:
      title: SandboxListResponse
      type: object
      allOf:
      - $ref: '#/components/schemas/Response'
      - type: object
        properties:
          data:
            type: object
            required:
            - sandboxes
            - pagination
            properties:
              sandboxes:
                type: array
                items:
                  $ref: '#/components/schemas/Sandbox'
              pagination:
                type: object
                required:
                - total_records
                - current_page
                - next_page
                properties:
                  total_records:
                    type: integer
                  current_page:
                    type: integer
                  next_page:
                    type: integer
                    nullable: true
                    description: The number of the next page, if any. If `null`, the current page is the last page of records.
    SandboxCreateRequest:
      title: SandboxCreateRequest
      type: object
      required:
      - files
      properties:
        files:
          type: object
          additionalProperties:
            type: object
            properties:
              code:
                type: string
                description: Plain text file contents. Should be empty if is_binary is true.
              binary_content:
                type: string
                description: Base64-encoded binary file contents. Should be empty if is_binary is false.
              is_binary:
                type: boolean
                default: false
                description: Whether the file contains binary contents.
          description: Map of path => file where each file is a map.
        title:
          type: string
          maxLength: 255
          default: ''
          description: Sandbox title. Maximum 255 characters.
        description:
          type: string
          description: Optional text description of the sandbox.
        tags:
          type: array
          items:
            type: string
          default: []
          description: List of string tags to apply to the sandbox. Only the first ten will be used.
        template:
          type: string
          description: Name of the template from which the sandbox is derived.
        entry:
          type: string
          description: Filename of the entrypoint of the sandbox.
        runtime:
          type: string
          enum:
          - browser
          - vm
          default: browser
          description: Runtime to use for the sandbox.
        privacy:
          type: integer
          minimum: 0
          maximum: 2
          default: 0
          description: 0 for public, 1 for unlisted, and 2 for private.
        is_frozen:
          type: boolean
          default: false
          description: Whether changes to the sandbox are disallowed.
        private_preview:
          type: boolean
          description: Determines whether the preview of a private sandbox is private or public.
        external_resources:
          type: array
          items:
            type: string
          description: Array of strings with external resources to load.
        npm_dependencies:
          type: object
          additionalProperties:
            type: string
          description: Map of dependencies and their version specifications.
        path:
          type: string
          default: /
          description: Path to the collection where the new sandbox should be stored.
        settings:
          type: object
          properties:
            use_pint:
              type: boolean
              description: Whether to use Pint for the sandbox.
    SandboxGetResponse:
      title: SandboxGetResponse
      type: object
      allOf:
      - $ref: '#/components/schemas/Response'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Sandbox'
    SandboxForkRequest:
      title: SandboxForkRequest
      type: object
      properties:
        title:
          type: string
          maxLength: 255
          description: Sandbox title. Maximum 255 characters.
        description:
          type: string
          maxLength: 255
          description: Sandbox description. Maximum 255 characters.
        privacy:
          type: integer
          default: 0
          description: Sandbox privacy. 0 for public, 1 for unlisted, and 2 for private.
        is_frozen:
          type: boolean
          default: false
          description: Sandbox frozen status.
        private_preview:
          type: boolean
          description: Determines whether the preview of a private sandbox is private or public.
        path:
          type: string
          default: /
          description: Path to the collection where the new sandbox should be stored.
        tags:
          type: array
          items:
            type: string
          default: []
          description: Tags to set on the new sandbox.
        start_options:
          type: object
          description: Optional VM start configuration. If provided, the sandbox VM will be started immediately after creation.
          properties:
            tier:
              type: string
              enum:
              - Pico
              - Nano
              - Micro
              - Small
              - Medium
              - Large
              - XLarge
              example: Micro
            hibernation_timeout_seconds:
              type: integer
              minimum: 1
              maximum: 86400
              example: 300
            ipcountry:
              type: string
              pattern: ^[A-Z]{2}$
              example: NL
            automatic_wakeup_config:
              type: object
              properties:
                http:
                  type: boolean
                  default: true
                websocket:
                  type: boolean
                  default: false
    Error:
      title: Error
      oneOf:
      - type: string
      - type: object
        additionalProperties: true
  securitySchemes:
    authorization:
      type: http
      scheme: bearer