CodeSandbox SDK API

openapi: 3.0.0
info:
  title: CodeSandbox 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: meta
    description: API metadata and auth context
  - name: sandbox
    description: Browser and VM sandbox management
  - name: vm
    description: Virtual machine lifecycle management
  - name: templates
    description: Sandbox template management
  - name: preview_token
    description: Preview token management for private sandboxes
  - name: preview_host
    description: Trusted preview host management
  - name: token
    description: API token management
  - name: workspace
    description: Workspace and organization management

paths:
  /meta/info:
    get:
      operationId: meta/info
      summary: Metadata about the API
      tags: [meta]
      parameters: []
      responses:
        "200":
          description: Meta Info Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetaInformation"
      security:
        - {}

  /org/workspace:
    post:
      operationId: workspace/create
      summary: Create a Workspace
      description: |
        Create a new, empty, workspace in the current organization
      tags: [workspace]
      parameters: []
      requestBody:
        description: Workspace Create Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkspaceCreateRequest"
      responses:
        "201":
          description: Workspace Create Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceCreateResponse"
      security:
        - authorization: [workspace:create]

  /org/workspace/{team_id}/tokens:
    post:
      operationId: token/create
      summary: Create an API Token
      description: |
        Create a new API token for a workspace that is part of the current organization.
      tags: [token]
      parameters:
        - name: team_id
          in: path
          required: true
          description: ID of the workspace to create the token in
          example: ws_123abcdef
          schema:
            type: string
      requestBody:
        description: Token Create Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenCreateRequest"
      responses:
        "201":
          description: Token Create Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenCreateResponse"
      security:
        - authorization: [token:manage]

  /org/workspace/{team_id}/tokens/{token_id}:
    patch:
      operationId: token/update
      summary: Update an API Token
      description: |
        Update an API token for a workspace that is part of the current organization.
      tags: [token]
      parameters:
        - name: team_id
          in: path
          required: true
          description: ID of the workspace the token belongs to
          example: ws_123abcdef
          schema:
            type: string
        - name: token_id
          in: path
          required: true
          description: ID of token to update
          example: tok_123abcdef
          schema:
            type: string
      requestBody:
        description: Token Update Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenUpdateRequest"
      responses:
        "201":
          description: Token Update Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenUpdateResponse"
      security:
        - authorization: [token:manage]

  /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]

  /sandbox/{id}/tokens:
    get:
      operationId: preview_token/list
      summary: List Preview Tokens
      description: |
        List information about the preview tokens associated with the current sandbox
      tags: [preview_token]
      parameters:
        - name: id
          in: path
          required: true
          description: Shortid of the sandbox to list the tokens for
          example: 1ab3c
          schema:
            type: string
      responses:
        "201":
          description: Token List Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewTokenListResponse"
      security:
        - authorization: [preview_token:manage]

    post:
      operationId: preview_token/create
      summary: Create a Preview Token
      description: |
        Create a new Preview token that allow access to a private sandbox
      tags: [preview_token]
      parameters:
        - name: id
          in: path
          required: true
          description: Shortid of the sandbox to create the token for
          example: 1ab3c
          schema:
            type: string
      requestBody:
        description: Token Create Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreviewTokenCreateRequest"
      responses:
        "201":
          description: Token Create Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewTokenCreateResponse"
      security:
        - authorization: [preview_token:manage]

    delete:
      operationId: preview_token/revoke_all
      summary: Revoke preview tokens
      description: |
        Immediately expires all active preview tokens associated with this sandbox
      tags: [preview_token]
      parameters:
        - name: id
          in: path
          required: true
          description: Shortid of the sandbox to revoke tokens for
          example: 1ab3c
          schema:
            type: string
      responses:
        "200":
          description: RevokeAllPreviewTokensResponse
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewTokenRevokeAllResponse"
      security:
        - authorization: [preview_token:manage]

  /sandbox/{id}/tokens/{token_id}:
    patch:
      operationId: preview_token/update
      summary: Update a Preview Token
      description: |
        Update a Preview token that allow access to a private sandbox
      tags: [preview_token]
      parameters:
        - name: id
          in: path
          required: true
          description: Shortid of the sandbox to create the token for
          example: 1ab3c
          schema:
            type: string
        - name: token_id
          in: path
          required: true
          description: ID of the token to update. Does not accept the token itself.
          example: prv_abcd12345
          schema:
            type: string
      requestBody:
        description: Token Update Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreviewTokenUpdateRequest"
      responses:
        "201":
          description: Token Update Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewTokenUpdateResponse"
      security:
        - authorization: [preview_token:manage]

  /templates:
    post:
      operationId: templates/create
      summary: Create a template
      description: |
        Create a new template in the current workspace (creates 3 sandboxes and tags them)
      tags: [templates]
      parameters: []
      requestBody:
        description: Template Create Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateCreateRequest"
      responses:
        "201":
          description: Template Create Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateCreateResponse"
      security:
        - authorization: [template:create]

  /vm/alias/{namespace}/{alias}:
    put:
      operationId: vm/assign_tag_alias
      summary: Assign a tag alias to a VM tag
      description: |
        Assign a tag alias to a VM tag.
      tags: [vm]
      parameters:
        - name: namespace
          in: path
          required: true
          description: Tag alias namespace
          example: my-project
          schema:
            type: string
        - name: alias
          in: path
          required: true
          description: Tag alias
          example: latest
          schema:
            type: string
      requestBody:
        description: VM Assign Tag Alias Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VMAssignTagAliasRequest"
      responses:
        "200":
          description: VM Assign Tag Alias Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMAssignTagAliasResponse"
      security:
        - authorization: [vm:manage]

  /vm/clusters:
    get:
      operationId: vm/list_clusters
      summary: List all available clusters
      description: |
        List all available clusters.
      tags: [vm]
      parameters: []
      responses:
        "200":
          description: VM List Clusters Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMListClustersResponse"
      security:
        - authorization: [vm:manage]

  /vm/running:
    get:
      operationId: vm/list_running_vms
      summary: List information about currently running VMs
      description: |
        List information about currently running VMs. This information is updated roughly every 30 seconds,
        so this data is not guaranteed to be perfectly up-to-date.
      tags: [vm]
      parameters: []
      responses:
        "200":
          description: VM List Running VMs Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMListRunningVMsResponse"
      security:
        - authorization: [vm:manage]

  /vm/tag:
    post:
      operationId: vm/create_tag
      summary: Create a new tag for a VM
      description: |
        Creates a new tag for a VM.
      tags: [vm]
      parameters: []
      requestBody:
        description: VM Create Tag Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VMCreateTagRequest"
      responses:
        "200":
          description: VM Create Tag Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMCreateTagResponse"
      security:
        - authorization: [vm:manage]

  /vm/{id}:
    delete:
      operationId: vm/delete
      summary: Delete a VM
      description: |
        Deletes a VM, permanently removing it from the system.

        This endpoint can only be used on VMs that belong to your team's workspace.
        Deleting a VM is irreversible and will permanently delete all data associated with it.
      tags: [vm]
      parameters:
        - name: id
          in: path
          required: true
          description: Sandbox ID
          example: new
          schema:
            type: string
      responses:
        "200":
          description: VM Delete Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMDeleteResponse"
      security:
        - authorization: [vm:manage]

  /vm/{id}/hibernate:
    post:
      operationId: vm/hibernate
      summary: Hibernate a VM
      description: |
        Suspends a running VM, saving a snapshot of its memory and running processes

        This endpoint may take an extended amount of time to return (30 seconds). If the VM is not
        currently running, it will return an error (404).

        Unless later shut down by request or due to inactivity, a hibernated VM can be resumed with
        minimal latency.
      tags: [vm]
      parameters:
        - name: id
          in: path
          required: true
          description: Sandbox ID
          example: new
          schema:
            type: string
      requestBody:
        description: VM Hibernate Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VMHibernateRequest"
      responses:
        "200":
          description: VM Hibernate Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMHibernateResponse"
      security:
        - authorization: [vm:manage]

  /vm/{id}/hibernation_timeout:
    put:
      operationId: vm/update_hibernation_timeout
      summary: Update VM Hibernation Timeout
      description: |
        Updates the hibernation timeout of a running VM.

        This endpoint can only be used on VMs that belong to your team's workspace.
        The new timeout must be greater than 0 and less than or equal to 86400 seconds (24 hours).
      tags: [vm]
      parameters:
        - name: id
          in: path
          required: true
          description: Sandbox ID
          example: new
          schema:
            type: string
      requestBody:
        description: VM Update Hibernation Timeout Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VMUpdateHibernationTimeoutRequest"
      responses:
        "200":
          description: VM Update Hibernation Timeout Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMUpdateHibernationTimeoutResponse"
      security:
        - authorization: [vm:manage]

  /vm/{id}/sessions:
    post:
      operationId: vm/create_session
      summary: Create a new session on a VM
      description: |
        Creates a new session on a running VM. A session represents an isolated Linux user, with their own container.
        A session has a single use token that the user can use to connect to the VM. This token has specific permissions
        (currently, read or write). The session is identified by a unique session ID, and the Linux username is based on
        the session ID.

        The Git user name and email can be configured via parameters.

        This endpoint requires the VM to be running. If the VM is not running, it will return a 404 error.
      tags: [vm]
      parameters:
        - name: id
          in: path
          required: true
          description: Sandbox ID
          example: new
          schema:
            type: string
      requestBody:
        description: VM Create Session Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VMCreateSessionRequest"
      responses:
        "200":
          description: VM Create Session Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMCreateSessionResponse"
      security:
        - authorization: [vm:manage]

  /vm/{id}/shutdown:
    post:
      operationId: vm/shutdown
      summary: Shutdown a VM
      description: |
        Stops a running VM, ending all currently running processes

        This endpoint may take an extended amount of time to return (30 seconds). If the VM is not
        currently running, it will return an error (404).

        Shutdown VMs require additional time to start up.
      tags: [vm]
      parameters:
        - name: id
          in: path
          required: true
          description: Sandbox ID
          example: new
          schema:
            type: string
      requestBody:
        description: VM Shutdown Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VMShutdownRequest"
      responses:
        "200":
          description: VM Shutdown Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMShutdownResponse"
      security:
        - authorization: [vm:manage]

  /vm/{id}/specs:
    put:
      operationId: vm/update_specs
      summary: Update VM Specs
      description: |
        Updates the specifications (CPU, memory, storage) of a running VM.

        This endpoint can only be used on VMs that belong to your team's workspace.
        The new tier must not exceed your team's maximum allowed tier.
      tags: [vm]
      parameters:
        - name: id
          in: path
          required: true
          description: Sandbox ID
          example: new
          schema:
            type: string
      requestBody:
        description: VM Update Specs Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VMUpdateSpecsRequest"
      responses:
        "200":
          description: VM Update Specs Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMUpdateSpecsResponse"
      security:
        - authorization: [vm:manage]

  /vm/{id}/start:
    post:
      operationId: vm/start
      summary: Start a VM
      description: |
        Start a virtual machine for the sandbox (devbox) with the given ID.

        While the `sandbox:read` scope is required for this endpoint, the resulting VM will have
        permissions according to the `sandbox:edit_code` scope. If present, the returned token will
        have write permissions to the contents of the VM. Otherwise, the returned token will grant
        only read-only permissions.

        This endpoint is subject to special rate limits related to concurrent VM usage.
      tags: [vm]
      parameters:
        - name: id
          in: path
          required: true
          description: Sandbox ID
          example: new
          schema:
            type: string
      requestBody:
        description: VM Start Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VMStartRequest"
      responses:
        "200":
          description: VM Start Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VMStartResponse"
      security:
        - authorization: [sandbox:read, vm:manage]

  /workspace/preview_hosts:
    get:
      operationId: preview_host/list
      summary: List Preview Hosts
      description: |
        List all trusted preview hosts for the current team
      tags: [preview_host]
      parameters: []
      responses:
        "201":
          description: Preview Host List Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewHostListResponse"
      security:
        - authorization: [vm:manage]

    post:
      operationId: preview_host/create
      summary: Create Preview Hosts
      description: |
        Add one or more trusted domains that are allowed to access sandbox previews for this workspace.
      tags: [preview_host]
      parameters: []
      requestBody:
        description: Preview Host Create Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreviewHostRequest"
      responses:
        "201":
          description: Preview Host List Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewHostListResponse"
      security:
        - authorization: [vm:manage]

    put:
      operationId: preview_host/update
      summary: Update Preview Hosts
      description: |
        Replace the list of trusted domains that are allowed to access sandbox previews for this workspace.
      tags: [preview_host]
      parameters: []
      requestBody:
        description: Preview Host Update Request
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreviewHostRequest"
      responses:
        "201":
          description: Preview Host List Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewHostListResponse"
      security:
        - authorization: [vm:manage]

components:
  securitySchemes:
    authorization:
      type: http
      scheme: bearer

  schemas:
    Response:
      title: Response
      type: object
      properties:
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"

    Error:
      title: Error
      oneOf:
        - type: string
        - type: object
          additionalProperties: 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

    PreviewToken:
      title: PreviewToken
      type: object
      required: [expires_at, last_used_at, token_id, token_prefix]
      properties:
        token_id:
          type: string
        token_prefix:
          type: string
        expires_at:
          type: string
          nullable: true
        last_used_at:
          type: string
          nullable: true

    MetaInformation:
      title: MetaInformation
      type: object
      required: [api]
      properties:
        api:
          type: object
          description: Meta information about the CodeSandbox API
          required: [name, latest_version]
          properties:
            name:
              type: string
            latest_version:
              type: string
        auth:
          type: object
          description: Meta information about the current authentication context
          required: [scopes, team, version]
          properties:
            scopes:
              type: array
              items:
                type: string
            team:
              type: string
              format: uuid
              nullable: true
            version:
              type: string
        rate_limits:
          type: object
          description: Current workspace rate limits
          required: [concurrent_vms, sandboxes_hourly, requests_hourly]
          properties:
            concurrent_vms:
              type: object
              properties:
                limit:
                  type: integer
                remaining:
                  type: integer
            sandboxes_hourly:
              type: object
              properties:
                limit:
                  type: integer
                remaining:
                  type: integer
                reset:
                  type: integer
            requests_hourly:
              type: object
              properties:
                limit:
                  type: integer
                remaining:
                  type: integer
                reset:
                  type: integer

    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.

    SandboxGetResponse:
      title: SandboxGetResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/Sandbox"

    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.

    SandboxCreateRes

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/codesandbox/refs/heads/main/openapi/codesandbox-sdk-openapi.yml