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.

    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

    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

    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.

    PreviewTokenListResponse:
      title: PreviewTokenListResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [tokens, sandbox_id]
              properties:
                sandbox_id:
                  type: string
                tokens:
                  type: array
                  items:
                    $ref: "#/components/schemas/PreviewToken"

    PreviewTokenCreateRequest:
      title: PreviewTokenCreateRequest
      type: object
      properties:
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: UTC Timestamp until when this token is valid. Omitting this field will create a token without an expiry.

    PreviewTokenCreateResponse:
      title: PreviewTokenCreateResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [sandbox_id, token]
              properties:
                sandbox_id:
                  type: string
                token:
                  allOf:
                    - $ref: "#/components/schemas/PreviewToken"
                    - type: object
                      required: [token]
                      properties:
                        token:
                          type: string

    PreviewTokenUpdateRequest:
      title: PreviewTokenUpdateRequest
      type: object
      properties:
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: UTC Timestamp until when this token is valid.

    PreviewTokenUpdateResponse:
      title: PreviewTokenUpdateResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [sandbox_id, token]
              properties:
                sandbox_id:
                  type: string
                token:
                  $ref: "#/components/schemas/PreviewToken"

    PreviewTokenRevokeAllResponse:
      title: PreviewTokenRevokeAllResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              properties: {}

    TemplateCreateRequest:
      title: TemplateCreateRequest
      type: object
      required: [forkOf]
      properties:
        forkOf:
          type: string
          example: pt_1234567890
          description: Short ID of the sandbox to fork.
        title:
          type: string
          maxLength: 255
          description: Template title. Maximum 255 characters.
        description:
          type: string
          maxLength: 255
          description: Template description. Maximum 255 characters.
        tags:
          type: array
          items:
            type: string
          default: []
          description: Tags to set on the new sandbox.

    TemplateCreateResponse:
      title: TemplateCreateResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [tag, sandboxes]
              properties:
                tag:
                  type: string
                sandboxes:
                  type: array
                  items:
                    type: object
                    required: [id, cluster]
                    properties:
                      id:
                        type: string
                      cluster:
                        type: string

    VMStartRequest:
      title: VMStartRequest
      type: object
      properties:
        tier:
          type: string
          enum: [Pico, Nano, Micro, Small, Medium, Large, XLarge]
          example: Micro
          description: Determines which specs to start the VM with.
        hibernation_timeout_seconds:
          type: integer
          minimum: 1
          maximum: 86400
          example: 300
          description: The time in seconds after which the VM will hibernate due to inactivity.
        ipcountry:
          type: string
          pattern: "^[A-Z]{2}$"
          example: NL
          description: ISO-3166-1 alpha-2 country code for cluster selection.
        automatic_wakeup_config:
          type: object
          description: Configuration for when the VM should automatically wake up from hibernation
          properties:
            http:
              type: boolean
              default: true
              description: Whether the VM should automatically wake up on HTTP requests
            websocket:
              type: boolean
              default: false
              description: Whether the VM should automatically wake up on WebSocket connections

    VMStartResponse:
      title: VMStartResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required:
                - bootup_type
                - cluster
                - id
                - latest_pitcher_version
                - pitcher_manager_version
                - pitcher_token
                - pitcher_url
                - pitcher_version
                - reconnect_token
                - use_pint
                - user_workspace_path
                - workspace_path
              properties:
                id:
                  type: string
                cluster:
                  type: string
                bootup_type:
                  type: string
                pitcher_url:
                  type: string
                pitcher_token:
                  type: string
                pitcher_version:
                  type: string
                pitcher_manager_version:
                  type: string
                latest_pitcher_version:
                  type: string
                reconnect_token:
                  type: string
                workspace_path:
                  type: string
                user_workspace_path:
                  type: string
                use_pint:
                  type: boolean
                pint_url:
                  type: string
                pint_token:
                  type: string

    VMHibernateRequest:
      title: VMHibernateRequest
      type: object
      properties: {}

    VMHibernateResponse:
      title: VMHibernateResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              properties: {}

    VMShutdownRequest:
      title: VMShutdownRequest
      type: object
      properties: {}

    VMShutdownResponse:
      title: VMShutdownResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              properties: {}

    VMDeleteResponse:
      title: VMDeleteResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              properties: {}

    VMUpdateSpecsRequest:
      title: VMUpdateSpecsRequest
      type: object
      required: [tier]
      properties:
        tier:
          type: string
          enum: [Pico, Nano, Micro, Small, Medium, Large, XLarge]
          example: Micro
          description: Determines which specs to update the VM with.

    VMUpdateSpecsResponse:
      title: VMUpdateSpecsResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [id, tier]
              properties:
                id:
                  type: string
                tier:
                  type: string

    VMUpdateHibernationTimeoutRequest:
      title: VMUpdateHibernationTimeoutRequest
      type: object
      required: [hibernation_timeout_seconds]
      properties:
        hibernation_timeout_seconds:
          type: integer
          minimum: 1
          maximum: 86400
          example: 300
          description: The new hibernation timeout in seconds.

    VMUpdateHibernationTimeoutResponse:
      title: VMUpdateHibernationTimeoutResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [id, hibernation_timeout_seconds]
              properties:
                id:
                  type: string
                hibernation_timeout_seconds:
                  type: integer

    VMCreateTagRequest:
      title: VMCreateTagRequest
      description: Create a tag for a list of VM IDs
      type: object
      required: [vm_ids]
      properties:
        vm_ids:
          type: array
          items:
            type: string

    VMCreateTagResponse:
      title: VMCreateTagResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [tag_id]
              properties:
                tag_id:
                  type: string

    VMAssignTagAliasRequest:
      title: VMAssignTagAliasRequest
      description: Assign a tag alias to a VM
      type: object
      required: [tag_id]
      properties:
        tag_id:
          type: string

    VMAssignTagAliasResponse:
      title: VMAssignTagAliasResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [tag_alias_id, team_id, tag_id, namespace, alias]
              properties:
                tag_alias_id:
                  type: string
                team_id:
                  type: string
                tag_id:
                  type: string
                namespace:
                  type: string
                alias:
                  type: string

    VMListClustersResponse:
      title: VMListClustersResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [clusters]
              properties:
                clusters:
                  type: array
                  items:
                    type: object
                    required: [host, slug]
                    properties:
                      slug:
                        type: string
                      host:
                        type: string

    VMListRunningVMsResponse:
      title: VMListRunningVMsResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [vms, concurrent_vm_count, concurrent_vm_limit]
              properties:
                vms:
                  type: array
                  items:
                    type: object
                    required: [id, last_active_at, session_started_at, specs, credit_basis]
                    properties:
                      id:
                        type: string
                      last_active_at:
                        type: string
                        format: date-time
                      session_started_at:
                        type: string
                        format: date-time
                      specs:
                        type: object
                        properties:
                          cpu:
                            type: integer
                          memory:
                            type: integer
                          storage:
                            type: integer
                      credit_basis:
                        type: string
                concurrent_vm_count:
                  type: integer
                concurrent_vm_limit:
                  type: integer

    VMCreateSessionRequest:
      title: VMCreateSessionRequest
      type: object
      required: [session_id, permission]
      properties:
        session_id:
          type: string
          pattern: "^[a-zA-Z0-9_-]+$"
          example: my-session-1
          description: Unique identifier for the session
        permission:
          type: string
          enum: [read, write]
          example: write
          description: Permission level for the session
        git_user_name:
          type: string
          description: Git user name to configure for this session
        git_user_email:
          type: string
          description: Git user email to configure for this session
        git_access_token:
          type: string
          description: GitHub token for the session

    VMCreateSessionResponse:
      title: VMCreateSessionResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required:
                - username
                - pitcher_token
                - user_workspace_path
                - capabilities
                - permissions
                - pitcher_url
              properties:
                username:
                  type: string
                  description: The Linux username created for this session
                pitcher_token:
                  type: string
                  description: Token to authenticate with Pitcher (the agent running inside the VM)
                pitcher_url:
                  type: string
                  description: WebSocket URL to connect to Pitcher
                user_workspace_path:
                  type: string
                  description: Path to the user's workspace in the VM
                capabilities:
                  type: array
                  items:
                    type: string
                  description: List of capabilities that Pitcher has
                permissions:
                  type: object
                  description: The permissions of the current session

    WorkspaceCreateRequest:
      title: WorkspaceCreateRequest
      type: object
      required: [name]
      properties:
        name:
          type: string
          maxLength: 64
          description: Name for the new workspace. Maximum length 64 characters.

    WorkspaceCreateResponse:
      title: WorkspaceCreateResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [id, name]
              properties:
                id:
                  type: string
                name:
                  type: string

    TokenCreateRequest:
      title: TokenCreateRequest
      type: object
      properties:
        description:
          type: string
          maxLength: 255
          description: Description of this token.
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: UTC Timestamp until when this token is valid.
        scopes:
          type: array
          items:
            enum: [sandbox_create, sandbox_edit_code, sandbox_read, vm_manage]
          description: Which scopes to grant this token.
        default_version:
          type: string
          format: date
          nullable: true
          description: API Version to use, formatted as YYYY-MM-DD.

    TokenCreateResponse:
      title: TokenCreateResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [description, expires_at, scopes, team_id, token, token_id]
              properties:
                token_id:
                  type: string
                team_id:
                  type: string
                token:
                  type: string
                description:
                  type: string
                  nullable: true
                scopes:
                  type: array
                  items:
                    type: string
                expires_at:
                  type: string
                  nullable: true

    TokenUpdateRequest:
      title: TokenUpdateRequest
      description: Updateable fields for API Tokens.
      type: object
      properties:
        description:
          type: string
          maxLength: 255
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
        scopes:
          type: array
          items:
            enum: [sandbox_create, sandbox_edit_code, sandbox_read, vm_manage]
        default_version:
          type: string
          format: date
          nullable: true

    TokenUpdateResponse:
      title: TokenUpdateResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [description, scopes, team_id, token_id]
              properties:
                token_id:
                  type: string
                team_id:
                  type: string
                description:
                  type: string
                  nullable: true
                scopes:
                  type: array
                  items:
                    type: string
                expires_at:
                  type: string
                  format: date-time
                  nullable: true

    PreviewHostListResponse:
      title: PreviewHostListResponse
      type: object
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            data:
              type: object
              required: [preview_hosts]
              properties:
                preview_hosts:
                  type: array
                  items:
                    type: object
                    required: [host, inserted_at]
                    properties:
                      host:
                        type: string
                      inserted_at:
                        type: string
                        format: date-time

    PreviewHostRequest:
      title: PreviewHostRequest
      type: object
      required: [hosts]
      properties:
        hosts:
          type: array
          items:
            type: string
            description: Trusted domains that are allowed to access sandbox previews.
            example: https://example.com