openapi.base.yaml

components:
  responses: {}
  schemas:
    Response:
      properties:
        errors:
          items:
            oneOf:
              - type: string
              - additionalProperties: true
                type: object
            title: Error
          type: array
        success:
          type: boolean
      title: Response
      type: object
    PreviewTokenListResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                sandbox_id:
                  type: string
                tokens:
                  items:
                    $ref: '#/components/schemas/PreviewToken'
                  type: array
              required:
                - tokens
                - sandbox_id
              type: object
          type: object
      title: PreviewTokenListResponse
      type: object
    VMUpdateHibernationTimeoutRequest:
      properties:
        hibernation_timeout_seconds:
          description: |
            The new hibernation timeout in seconds.

            Must be greater than 0 and less than or equal to 86400 (24 hours).
          example: 300
          maximum: 86400
          minimum: 1
          type: integer
      required:
        - hibernation_timeout_seconds
      title: VMUpdateHibernationTimeoutRequest
      type: object
    VMAssignTagAliasResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                alias:
                  type: string
                namespace:
                  type: string
                tag_alias_id:
                  type: string
                tag_id:
                  type: string
                team_id:
                  type: string
              required:
                - tag_alias_id
                - team_id
                - tag_id
                - namespace
                - alias
              type: object
          type: object
      title: VMAssignTagAliasResponse
      type: object
    TemplateCreateRequest:
      properties:
        description:
          default: '[Template description]'
          description: Template description. Maximum 255 characters. Defaults to description of original sandbox.
          maxLength: 255
          type: string
        forkOf:
          description: Short ID of the sandbox to fork.
          example: pt_1234567890
          type: string
        tags:
          default: []
          description: Tags to set on the new sandbox, if any. Will not inherit tags from the source sandbox.
          items:
            type: string
          type: array
        title:
          default: '[Template title]'
          description: Template title. Maximum 255 characters. Defaults to title of original sandbox with (forked).
          maxLength: 255
          type: string
      required:
        - forkOf
      title: TemplateCreateRequest
      type: object
    PreviewToken:
      properties:
        expires_at:
          nullable: true
          type: string
        last_used_at:
          nullable: true
          type: string
        token_id:
          type: string
        token_prefix:
          type: string
      required:
        - expires_at
        - last_used_at
        - token_id
        - token_prefix
      title: PreviewToken
      type: object
    VMShutdownResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties: {}
              type: object
          type: object
      title: VMShutdownResponse
      type: object
    PreviewTokenRevokeAllResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties: {}
              type: object
          type: object
      title: PreviewTokenRevokeAllResponse
      type: object
    Sandbox:
      properties:
        created_at:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        id:
          type: string
        is_frozen:
          type: boolean
        privacy:
          type: integer
        tags:
          items:
            type: string
          type: array
        title:
          nullable: true
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - privacy
        - is_frozen
        - created_at
        - updated_at
        - tags
      title: Sandbox
      type: object
    Error:
      oneOf:
        - type: string
        - additionalProperties: true
          type: object
      title: Error
    VMHibernateRequest:
      properties: {}
      title: VMHibernateRequest
    PreviewTokenCreateRequest:
      properties:
        expires_at:
          description: UTC Timestamp until when this token is valid. Omitting this field will create a token without an expiry.
          format: date-time
          nullable: true
          type: string
      title: PreviewTokenCreateRequest
      type: object
    VMCreateTagResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                tag_id:
                  type: string
              required:
                - tag_id
              type: object
          type: object
      title: VMCreateTagResponse
      type: object
    VMListRunningVMsResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                concurrent_vm_count:
                  type: integer
                concurrent_vm_limit:
                  type: integer
                vms:
                  items:
                    properties:
                      credit_basis:
                        type: string
                      id:
                        type: string
                      last_active_at:
                        format: date-time
                        type: string
                      session_started_at:
                        format: date-time
                        type: string
                      specs:
                        properties:
                          cpu:
                            type: integer
                          memory:
                            type: integer
                          storage:
                            type: integer
                        type: object
                    type: object
                  required:
                    - id
                    - last_active_at
                    - session_started_at
                    - specs
                    - credit_basis
                  type: array
              required:
                - vms
                - concurrent_vm_count
                - concurrent_vm_limit
              type: object
          type: object
      title: VMListRunningVMsResponse
      type: object
    SandboxGetResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              $ref: '#/components/schemas/Sandbox'
          type: object
      title: SandboxGetResponse
      type: object
    SandboxForkRequest:
      properties:
        description:
          default: '[Original description]'
          description: Sandbox description. Maximum 255 characters. Defaults to description of original sandbox.
          maxLength: 255
          type: string
        is_frozen:
          default: false
          description: Sandbox frozen status. When true, edits to the sandbox are restricted. Defaults to frozen status of the original sandbox.
          type: boolean
        path:
          default: /
          description: Path to the collection where the new sandbox should be stored. Defaults to "/". If no collection exists at the given path, it will be created.
          type: string
        privacy:
          default: 0
          description: Sandbox privacy. 0 for public, 1 for unlisted, and 2 for private. Subject to the minimum privacy restrictions of the workspace. Defaults to the privacy of the original sandbox.
          type: integer
        private_preview:
          description: Determines whether the preview of a private sandbox is private or public. Has no effect on public or unlisted sandboxes; their previews are always publicly accessible
          type: boolean
        start_options:
          description: Optional VM start configuration. If provided, the sandbox VM will be started immediately after creation.
          properties:
            automatic_wakeup_config:
              description: Configuration for when the VM should automatically wake up from hibernation
              properties:
                http:
                  default: true
                  description: Whether the VM should automatically wake up on HTTP requests (excludes WebSocket requests)
                  type: boolean
                websocket:
                  default: false
                  description: Whether the VM should automatically wake up on WebSocket connections
                  type: boolean
              type: object
            hibernation_timeout_seconds:
              description: |
                The time in seconds after which the VM will hibernate due to inactivity.
                Must be a positive integer between 1 and 86400 (24 hours).
                Defaults to 300 seconds (5 minutes) if not specified.
              example: 300
              maximum: 86400
              minimum: 1
              type: integer
            ipcountry:
              description: This determines in which cluster, closest to the given country the VM will be started in. The format is ISO-3166-1 alpha-2. If not set, the VM will be started closest to the caller of this API. This will only be applied when a VM is run for the first time, and will only serve as a hint (e.g. if the template of this sandbox runs in EU cluster, this sandbox will also run in the EU cluster).
              example: NL
              pattern: ^[A-Z]{2}$
              type: string
            tier:
              description: |
                Determines which specs to start the VM with. If not specified, the VM will start with the default specs for the workspace.

                You can only specify a VM tier when starting a VM that is inside your workspace. Specifying a VM tier for someone else's sandbox will return an error.

                Not all tiers will be available depending on the workspace subscription status, and higher tiers incur higher costs. Please see codesandbox.io/pricing for details on specs and costs.
              enum:
                - Pico
                - Nano
                - Micro
                - Small
                - Medium
                - Large
                - XLarge
              example: Micro
          type: object
        tags:
          default: []
          description: Tags to set on the new sandbox, if any. Will not inherit tags from the source sandbox.
          items:
            type: string
          type: array
        title:
          default: '[Original title]'
          description: Sandbox title. Maximum 255 characters. Defaults to title of original sandbox with (forked).
          maxLength: 255
          type: string
      title: SandboxForkRequest
      type: object
    SandboxListResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                pagination:
                  properties:
                    current_page:
                      type: integer
                    next_page:
                      description: The number of the next page, if any. If `null`, the current page is the last page of records.
                      nullable: true
                      type: integer
                    total_records:
                      type: integer
                  required:
                    - total_records
                    - current_page
                    - next_page
                  type: object
                sandboxes:
                  items:
                    $ref: '#/components/schemas/Sandbox'
                  type: array
              required:
                - sandboxes
                - pagination
              type: object
          type: object
      title: SandboxListResponse
      type: object
    MetaInformation:
      properties:
        api:
          description: Meta information about the CodeSandbox API
          properties:
            latest_version:
              type: string
            name:
              type: string
          required:
            - name
            - latest_version
          type: object
        auth:
          description: Meta information about the current authentication context
          properties:
            scopes:
              items:
                type: string
              type: array
            team:
              format: uuid
              nullable: true
              type: string
            version:
              type: string
          required:
            - scopes
            - team
            - version
          type: object
        rate_limits:
          description: Current workspace rate limits
          properties:
            concurrent_vms:
              properties:
                limit:
                  type: integer
                remaining:
                  type: integer
              type: object
            requests_hourly:
              properties:
                limit:
                  type: integer
                remaining:
                  type: integer
                reset:
                  type: integer
              type: object
            sandboxes_hourly:
              properties:
                limit:
                  type: integer
                remaining:
                  type: integer
                reset:
                  type: integer
              type: object
          required:
            - concurrent_vms
            - sandboxes_hourly
            - requests_hourly
          type: object
      required:
        - api
      title: MetaInformation
      type: object
    TokenUpdateRequest:
      description: Updateable fields for API Tokens. Omitting a field will not update it; explicitly passing null or an empty list will clear the value.
      properties:
        default_version:
          description: API Version to use, formatted as YYYY-MM-DD
          format: date
          nullable: true
          type: string
        description:
          description: Description of this token, for instance where it will be used.
          maxLength: 255
          nullable: true
          type: string
        expires_at:
          description: Expiry time of this token. Cannot be set in the past, and cannot be changed for tokens that have already expired. Pass null to make this token never expire.
          format: date-time
          nullable: true
          type: string
        scopes:
          description: Which scopes to grant this token. The given scopes will replace the current scopes, revoking any that are no longer present in the list.
          items:
            enum:
              - sandbox_create
              - sandbox_edit_code
              - sandbox_read
              - vm_manage
          type: array
      title: TokenUpdateRequest
      type: object
    VMAssignTagAliasRequest:
      description: Assign a tag alias to a VM
      properties:
        tag_id:
          type: string
      required:
        - tag_id
      title: VMAssignTagAliasRequest
      type: object
    VMHibernateResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties: {}
              type: object
          type: object
      title: VMHibernateResponse
      type: object
    PreviewTokenUpdateResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                sandbox_id:
                  type: string
                token:
                  $ref: '#/components/schemas/PreviewToken'
              required:
                - sandbox_id
                - token
              type: object
          type: object
      title: PreviewTokenUpdateResponse
      type: object
    SandboxCreateResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                alias:
                  type: string
                id:
                  type: string
                title:
                  nullable: true
                  type: string
              required:
                - alias
                - id
                - title
              type: object
          type: object
      title: SandboxCreateResponse
      type: object
    VMStartRequest:
      properties:
        automatic_wakeup_config:
          description: Configuration for when the VM should automatically wake up from hibernation
          properties:
            http:
              default: true
              description: Whether the VM should automatically wake up on HTTP requests (excludes WebSocket requests)
              type: boolean
            websocket:
              default: false
              description: Whether the VM should automatically wake up on WebSocket connections
              type: boolean
          type: object
        hibernation_timeout_seconds:
          description: |
            The time in seconds after which the VM will hibernate due to inactivity.
            Must be a positive integer between 1 and 86400 (24 hours).
            Defaults to 300 seconds (5 minutes) if not specified.
          example: 300
          maximum: 86400
          minimum: 1
          type: integer
        ipcountry:
          description: This determines in which cluster, closest to the given country the VM will be started in. The format is ISO-3166-1 alpha-2. If not set, the VM will be started closest to the caller of this API. This will only be applied when a VM is run for the first time, and will only serve as a hint (e.g. if the template of this sandbox runs in EU cluster, this sandbox will also run in the EU cluster).
          example: NL
          pattern: ^[A-Z]{2}$
          type: string
        tier:
          description: |
            Determines which specs to start the VM with. If not specified, the VM will start with the default specs for the workspace.

            You can only specify a VM tier when starting a VM that is inside your workspace. Specifying a VM tier for someone else's sandbox will return an error.

            Not all tiers will be available depending on the workspace subscription status, and higher tiers incur higher costs. Please see codesandbox.io/pricing for details on specs and costs.
          enum:
            - Pico
            - Nano
            - Micro
            - Small
            - Medium
            - Large
            - XLarge
          example: Micro
      title: VMStartRequest
      type: object
    PreviewTokenUpdateRequest:
      properties:
        expires_at:
          description: UTC Timestamp until when this token is valid. Omitting this field will create a token without an expiry.
          format: date-time
          nullable: true
          type: string
      title: PreviewTokenUpdateRequest
      type: object
    PreviewHostListResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                preview_hosts:
                  items:
                    properties:
                      host:
                        type: string
                      inserted_at:
                        format: date_time
                        type: string
                    required:
                      - host
                      - inserted_at
                    type: object
                  type: array
              required:
                - preview_hosts
              type: object
          type: object
      title: PreviewHostListResponse
      type: object
    VMShutdownRequest:
      properties: {}
      title: VMShutdownRequest
    VMUpdateSpecsRequest:
      properties:
        tier:
          description: |
            Determines which specs to update the VM with.

            Not all tiers will be available depending on the workspace subscription status, and higher tiers incur higher costs. Please see codesandbox.io/pricing for details on specs and costs.
          enum:
            - Pico
            - Nano
            - Micro
            - Small
            - Medium
            - Large
            - XLarge
          example: Micro
      required:
        - tier
      title: VMUpdateSpecsRequest
      type: object
    WorkspaceCreateRequest:
      properties:
        name:
          description: Name for the new workspace. Maximum length 64 characters.
          maxLength: 64
          type: string
      required:
        - name
      title: WorkspaceCreateRequest
      type: object
    VMCreateTagRequest:
      description: Create a tag for a list of VM IDs
      properties:
        vm_ids:
          items:
            type: string
          type: array
      required:
        - vm_ids
      title: VMCreateTagRequest
      type: object
    PreviewHostRequest:
      properties:
        hosts:
          items:
            description: Trusted domains that are allowed to access sandbox previews.
            example: https://example.com
            type: string
          type: array
      required:
        - hosts
      title: PreviewHostRequest
      type: object
    VMStartResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                bootup_type:
                  type: string
                cluster:
                  type: string
                id:
                  type: string
                latest_pitcher_version:
                  type: string
                pitcher_manager_version:
                  type: string
                pitcher_token:
                  type: string
                pitcher_url:
                  type: string
                pitcher_version:
                  type: string
                reconnect_token:
                  type: string
                user_workspace_path:
                  type: string
                workspace_path:
                  type: string
              required:
                - bootup_type
                - cluster
                - id
                - latest_pitcher_version
                - pitcher_manager_version
                - pitcher_token
                - pitcher_url
                - pitcher_version
                - reconnect_token
                - user_workspace_path
                - workspace_path
              type: object
          type: object
      title: VMStartResponse
      type: object
    VMUpdateSpecsResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                id:
                  type: string
                tier:
                  type: string
              required:
                - id
                - tier
              type: object
          type: object
      title: VMUpdateSpecsResponse
      type: object
    SandboxCreateRequest:
      properties:
        description:
          description: Optional text description of the sandbox. Defaults to no description.
          type: string
        entry:
          description: Filename of the entrypoint of the sandbox.
          type: string
        external_resources:
          description: Array of strings with external resources to load.
          items:
            type: string
          type: array
        files:
          additionalProperties:
            properties:
              binary_content:
                description: If the file has binary (non plain-text) contents, place the base-64 encoded contents in this key. Should be empty or missing if `is_binary` is `false`.
                type: string
              code:
                description: If the file is non-binary in nature, place the (escaped) plain text contents in this key. Should be empty or missing if `is_binary` is `true`.
                type: string
              is_binary:
                default: false
                description: Whether the file contains binary contents.
                type: boolean
            type: object
          description: Map of `path => file` where each file is a map.
          type: object
        is_frozen:
          default: false
          description: Whether changes to the sandbox are disallowed. Defaults to `false`.
          type: boolean
        npm_dependencies:
          additionalProperties:
            type: string
          description: Map of dependencies and their version specifications.
          type: object
        path:
          default: /
          description: Path to the collection where the new sandbox should be stored. Defaults to "/". If no collection exists at the given path, it will be created.
          type: string
        privacy:
          default: 0
          description: 0 for public, 1 for unlisted, and 2 for private. Privacy is subject to certain restrictions (team minimum setting, drafts must be private, etc.). Defaults to public.
          maximum: 2
          minimum: 0
          type: integer
        private_preview:
          description: Determines whether the preview of a private sandbox is private or public. Has no effect on public or unlisted sandboxes; their previews are always publicly accessible
          type: boolean
        runtime:
          default: browser
          description: Runtime to use for the sandbox. Defaults to `"browser"`.
          enum:
            - browser
            - vm
          type: string
        settings:
          description: Sandbox settings.
          properties:
            use_pint:
              description: Whether to use Pint for the sandbox.
              type: boolean
          type: object
        tags:
          default: []
          description: List of string tags to apply to the sandbox. Only the first ten will be used. Defaults to no tags.
          items:
            type: string
          type: array
        template:
          description: Name of the template from which the sandbox is derived (for example, `"static"`).
          type: string
        title:
          default: ''
          description: Sandbox title. Maximum 255 characters. Defaults to no title.
          maxLength: 255
          type: string
      required:
        - files
      title: SandboxCreateRequest
    VMListClustersResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                clusters:
                  items:
                    properties:
                      host:
                        type: string
                      slug:
                        type: string
                    required:
                      - host
                      - slug
                    type: object
                  type: array
              required:
                - clusters
              type: object
          type: object
      title: VMListClustersResponse
      type: object
    TokenUpdateResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                description:
                  nullable: true
                  type: string
                expires_at:
                  format: date-time
                  nullable: true
                  type: string
                scopes:
                  items:
                    type: string
                  type: array
                team_id:
                  type: string
                token_id:
                  type: string
              required:
                - description
                - scopes
                - team_id
                - token_id
              type: object
          type: object
      title: TokenUpdateResponse
      type: object
    TokenCreateResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                description:
                  nullable: true
                  type: string
                expires_at:
                  nullable: true
                  type: string
                scopes:
                  items:
                    type: string
                  type: array
                team_id:
                  type: string
                token:
                  type: string
                token_id:
                  type: string
              required:
                - description
                - expires_at
                - scopes
                - team_id
                - token
                - token_id
              type: object
          type: object
      title: TokenCreateResponse
      type: object
    VMDeleteResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties: {}
              type: object
          type: object
      title: VMDeleteResponse
      type: object
    TemplateCreateResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                sandboxes:
                  items:
                    properties:
                      cluster:
                        type: string
                      id:
                        type: string
                    required:
                      - id
                      - cluster
                    type: object
                  type: array
                tag:
                  type: string
              required:
                - tag
                - sandboxes
              type: object
          type: object
      title: TemplateCreateResponse
      type: object
    TokenCreateRequest:
      properties:
        default_version:
          description: API Version to use, formatted as YYYY-MM-DD. Defaults to the latest version at time of creation.
          format: date
          nullable: true
          type: string
        description:
          description: Description of this token, for instance where it will be used.
          maxLength: 255
          type: string
        expires_at:
          description: UTC Timestamp until when this token is valid. Omitting this field will create a token without an expiry.
          format: date-time
          nullable: true
          type: string
        scopes:
          description: Which scopes to grant this token. The given scopes will replace the current scopes, revoking any that are no longer present in the list.
          items:
            enum:
              - sandbox_create
              - sandbox_edit_code
              - sandbox_read
              - vm_manage
          type: array
      title: TokenCreateRequest
      type: object
    VMCreateSessionRequest:
      properties:
        git_access_token:
          description: GitHub token for the session
          type: string
        git_user_email:
          description: Git user email to configure for this session
          type: string
        git_user_name:
          description: Git user name to configure for this session
          type: string
        permission:
          description: Permission level for the session
          enum:
            - read
            - write
          example: write
          type: string
        session_id:
          description: Unique identifier for the session
          example: my-session-1
          pattern: ^[a-zA-Z0-9_-]+$
          type: string
      required:
        - session_id
        - permission
      title: VMCreateSessionRequest
      type: object
    VMCreateSessionResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                capabilities:
                  description: List of capabilities that Pitcher has
                  items:
                    type: string
                  type: array
                permissions:
                  description: The permissions of the current session
                  type: object
                pitcher_token:
                  description: Token to authenticate with Pitcher (the agent running inside the VM)
                  type: string
                pitcher_url:
                  description: WebSocket URL to connect to Pitcher
                  type: string
                user_workspace_path:
                  description: Path to the user's workspace in the VM
                  type: string
                username:
                  description: The Linux username created for this session
                  type: string
              required:
                - username
                - pitcher_token
                - user_workspace_path
                - capabilities
                - permissions
                - pitcher_url
              type: object
          type: object
      title: VMCreateSessionResponse
      type: object
    WorkspaceCreateResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                id:
                  type: string
                name:
                  type: string
              required:
                - id
                - name
              type: object
          type: object
      title: WorkspaceCreateResponse
      type: object
    VMUpdateHibernationTimeoutResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                hibernation_timeout_seconds:
                  type: integer
                id:
                  type: string
              required:
                - id
                - hibernation_timeout_seconds
              type: object
          type: object
      title: VMUpdateHibernationTimeoutResponse
      type: object
    SandboxForkResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                alias:
                  type: string
                id:
                  type: string
                start_response:
                  description: VM start response. Only present when start_options were provided in the request.
                  nullable: true
                  properties:
                    bootup_type:
                      type: string
                    cluster:
                      type: string
                    id:
                      type: string
                    latest_pitcher_version:
                      type: string
                    pitcher_manager_version:
                      type: string
                    pitcher_token:
                      type: string
                    pitcher_url:
                      type: string
                    pitcher_version:
                      type: string
                    reconnect_token:
                      type: string
                    user_workspace_path:
                      type: string
                    workspace_path:
                      type: string
                  required:
                    - bootup_type
                    - cluster
                    - id
                    - latest_pitcher_version
                    - pitcher_manager_version
                    - pitcher_token
                    - pitcher_url
                    - pitcher_version
                    - reconnect_token
                    - user_workspace_path
                    - workspace_path
                  type: object
                title:
                  nullable: true
                  type: string
              required:
                - alias
                - id
                - title
              type: object
          type: object
      title: SandboxForkResponse
      type: object
    PreviewTokenCreateResponse:
      allOf:
        - properties:
            errors:
              items:
                oneOf:
                  - type: string
                  - additionalProperties: true
                    type: object
                title: Error
              type: array
            success:
              type: boolean
          title: Response
          type: object
        - properties:
            data:
              properties:
                sandbox_id:
                  type: string
                token:
                  allOf:
                    - properties:
                        expires_at:
                          nullable: true
                          type: string
                        last_used_at:
                          nullable: true
                          type: string
                        token_id:
                          type: string
                        token_prefix:
                          type: string
                      required:
                        - expires_at
                        - last_used_at
                        - token_id
                        - token_prefix
                      title: PreviewToken
                      type: object
                    - properties:
                        token:
                          type: string
                      required:
                        - token
                      type: object
                  type: object
              required:
                - sandbox_id
                - token
              type: object
          type: object
      title: PreviewTokenCreateResponse
      type: object
  securitySchemes:
    authorization:
      scheme: bearer
      type: http
info:
  title: CodeSandbox API
  version: '2023-07-01'
openapi: 3.0.0
paths:
  /meta/info:
    get:
      callbacks: {}
      operationId: meta/info
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaInformation'
          description: Meta Info Response
      security:
        - {}
      summary: Metadata about the API
      tags:
        - meta
  /org/workspace:
    post:
      callbacks: {}
      description: |
        Create a new, empty, workspace in the current organization
      operationId: workspace/create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceCreateRequest'
        description: Workspace Create Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceCreateResponse'
          description: Workspace Create Response
      security:
        - authorization:
            - workspace:create
      summary: Create a Workspace
      tags: []
  /org/workspace/{team_id}/tokens:
    post:
      callbacks: {}
      description: |
        Create a new API token for a workspace that is part of the current organization.
      operationId: token/create
      parameters:
        - description: ID of the workspace to create the token in
          example: ws_123abcdef
          in: path
          name: team_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCreateRequest'
        description: Token Create Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCreateResponse'
          description: Token Create Response
      security:
        - authorization:
            - token:manage
      summary: Create an API Token
      tags: []
  /org/workspace/{team_id}/tokens/{token_id}:
    patch:
      callbacks: {}
      description: |
        Update an API token for a workspace that is part of the current organization.
      operationId: token/update
      parameters:
        - description: ID of the workspace the token belongs to
          example: ws_123abcdef
          in: path
          name: team_id
          required: true
          schema:
            type: string
        - description: ID of token to update
          example: tok_123abcdef
          in: path
          name: token_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenUpdateRequest'
        description: Token Update Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenUpdateResponse'
          description: Token Update Response
      security:
        - authorization:
            - token:manage
      summary: Update an API Token
      tags: []
  /sandbox:
    get:
      callbacks: {}
      description: |
        List sandboxes from the current workspace with optional filters.
        Results are limited to a maximum of 50 sandboxes per request.
      operationId: sandbox/list
      parameters:
        - description: Comma-separated list of tags to filter by
          example: sha-123,feature-x
          in: query
          name: tags
          required: false
          schema:
            type: string
        - description: Field to order results by
          example: updated_at
          in: query
          name: order_by
          required: false
          schema:
            default: updated_at
            enum:
              - inserted_at
              - updated_at
        - description: Order direction
          example: desc
          in: query
          name: direction
          required: false
          schema:
            default: desc
            enum:
              - asc
              - desc
        - description: Maximum number of sandboxes to return in a single response
          in: query
          name: page_size
          required: false
          schema:
            default: 20
            maximum: 50
            minimum: 1
            type: integer
        - description: Page number to return
          in: query
          name: page
          required: false
          schema:
            default: 1
            minimum: 1
            type: integer
        - description: If true, only returns VMs for which a heartbeat was received in the last 30 seconds.
          in: query
          name: status
          required: false
          schema:
            enum:
              - running
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxListResponse'
          description: Sandbox List Response
      security:
        - authorization:
            - sandbox:read
      summary: List Sandboxes
      tags:
        - sandbox
    post:
      callbacks: {}
      description: |
        Create a new sandbox in the current workspace with file contents
      operationId: sandbox/create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxCreateRequest'
        description: Sandbox Create Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxCreateResponse'
          description: Sandbox Create Response
      security:
        - authorization:
            - sandbox:create
      summary: Create a Sandbox
      tags:
        - sandbox
  /sandbox/{id}:
    get:
      callbacks: {}
      description: |
        Retrieve a sandbox by its ID
      operationId: sandbox/get
      parameters:
        - description: Short ID of the sandbox to retrieve
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxGetResponse'
          description: Sandbox Get Response
      security:
        - authorization:
            - sandbox:read
      summary: Get a Sandbox
      tags:
        - sandbox
  /sandbox/{id}/fork:
    post:
      callbacks: {}
      description: |
        Fork an existing sandbox to the current workspace
      operationId: sandbox/fork
      parameters:
        - description: Short ID of the sandbox to fork
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxForkRequest'
        description: Sandbox Fork Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxForkResponse'
          description: Sandbox Fork Response
      security:
        - authorization:
            - sandbox:create
      summary: Fork a Sandbox
      tags:
        - sandbox
  /sandbox/{id}/tokens:
    delete:
      callbacks: {}
      description: |
        Immediately expires all active preview tokens associated with this sandbox
      operationId: preview_token/revoke_all
      parameters:
        - description: Shortid of the sandbox to revoke tokens for
          example: 1ab3c
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewTokenRevokeAllResponse'
          description: RevokeAllPreviewTokensResponse
      security:
        - authorization:
            - preview_token:manage
      summary: Revoke preview tokens
      tags: []
    get:
      callbacks: {}
      description: |
        List information about the preview tokens associated with the current sandbox
      operationId: preview_token/list
      parameters:
        - description: Shortid of the sandbox to list the tokens for
          example: 1ab3c
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewTokenListResponse'
          description: Token List Response
      security:
        - authorization:
            - preview_token:manage
      summary: List Preview Tokens
      tags: []
    post:
      callbacks: {}
      description: |
        Create a new Preview token that allow access to a private sandbox
      operationId: preview_token/create
      parameters:
        - description: Shortid of the sandbox to create the token for
          example: 1ab3c
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewTokenCreateRequest'
        description: Token Create Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewTokenCreateResponse'
          description: Token Create Response
      security:
        - authorization:
            - preview_token:manage
      summary: Create a Preview Token
      tags: []
  /sandbox/{id}/tokens/{token_id}:
    patch:
      callbacks: {}
      description: |
        Update a Preview token that allow access to a private sandbox
      operationId: preview_token/update
      parameters:
        - description: Shortid of the sandbox to create the token for
          example: 1ab3c
          in: path
          name: id
          required: true
          schema:
            type: string
        - description: ID of the token to update. Does not accept the token itself.
          example: prv_abcd12345
          in: path
          name: token_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewTokenUpdateRequest'
        description: Token Update Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewTokenUpdateResponse'
          description: Token Update Response
      security:
        - authorization:
            - preview_token:manage
      summary: Update a Preview Token
      tags: []
  /templates:
    post:
      callbacks: {}
      description: |
        Create a new template in the current workspace (creates 3 sandboxes and tags them)
      operationId: templates/create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateCreateRequest'
        description: Template Create Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateCreateResponse'
          description: Template Create Response
      security:
        - authorization:
            - template:create
      summary: Create a template
      tags:
        - templates
  /vm/alias/{namespace}/{alias}:
    put:
      callbacks: {}
      description: |
        Assign a tag alias to a VM tag.
      operationId: vm/assign_tag_alias
      parameters:
        - description: Tag alias namespace
          example: my-project
          in: path
          name: namespace
          required: true
          schema:
            type: string
        - description: Tag alias
          example: latest
          in: path
          name: alias
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VMAssignTagAliasRequest'
        description: VM Assign Tag Alias Request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMAssignTagAliasResponse'
          description: VM Assign Tag Alias Response
      security:
        - authorization:
            - vm:manage
      summary: Assign a tag alias to a VM tag
      tags:
        - vm
  /vm/clusters:
    get:
      callbacks: {}
      description: |
        List all available clusters.
      operationId: vm/list_clusters
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMListClustersResponse'
          description: VM List Clusters Response
      security:
        - authorization:
            - vm:manage
      summary: List all available clusters
      tags:
        - vm
  /vm/running:
    get:
      callbacks: {}
      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.
      operationId: vm/list_running_vms
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMListRunningVMsResponse'
          description: VM List Running VMs Response
      security:
        - authorization:
            - vm:manage
      summary: List information about currently running VMs
      tags:
        - vm
  /vm/tag:
    post:
      callbacks: {}
      description: |
        Creates a new tag for a VM.
      operationId: vm/create_tag
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VMCreateTagRequest'
        description: VM Create Tag Request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMCreateTagResponse'
          description: VM Create Tag Response
      security:
        - authorization:
            - vm:manage
      summary: Create a new tag for a VM
      tags:
        - vm
  /vm/{id}:
    delete:
      callbacks: {}
      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.
      operationId: vm/delete
      parameters:
        - description: Sandbox ID
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMDeleteResponse'
          description: VM Delete Response
      security:
        - authorization:
            - vm:manage
      summary: Delete a VM
      tags:
        - vm
  /vm/{id}/hibernate:
    post:
      callbacks: {}
      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.
      operationId: vm/hibernate
      parameters:
        - description: Sandbox ID
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VMHibernateRequest'
        description: VM Hibernate Request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMHibernateResponse'
          description: VM Hibernate Response
      security:
        - authorization:
            - vm:manage
      summary: Hibernate a VM
      tags:
        - vm
  /vm/{id}/hibernation_timeout:
    put:
      callbacks: {}
      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).
      operationId: vm/update_hibernation_timeout
      parameters:
        - description: Sandbox ID
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VMUpdateHibernationTimeoutRequest'
        description: VM Update Hibernation Timeout Request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMUpdateHibernationTimeoutResponse'
          description: VM Update Hibernation Timeout Response
      security:
        - authorization:
            - vm:manage
      summary: Update VM Hibernation Timeout
      tags:
        - vm
  /vm/{id}/sessions:
    post:
      callbacks: {}
      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.
      operationId: vm/create_session
      parameters:
        - description: Sandbox ID
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VMCreateSessionRequest'
        description: VM Create Session Request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMCreateSessionResponse'
          description: VM Create Session Response
      security:
        - authorization:
            - vm:manage
      summary: Create a new session on a VM
      tags:
        - vm
  /vm/{id}/shutdown:
    post:
      callbacks: {}
      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.
      operationId: vm/shutdown
      parameters:
        - description: Sandbox ID
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VMShutdownRequest'
        description: VM Shutdown Request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMShutdownResponse'
          description: VM Shutdown Response
      security:
        - authorization:
            - vm:manage
      summary: Shutdown a VM
      tags:
        - vm
  /vm/{id}/specs:
    put:
      callbacks: {}
      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.
      operationId: vm/update_specs
      parameters:
        - description: Sandbox ID
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VMUpdateSpecsRequest'
        description: VM Update Specs Request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMUpdateSpecsResponse'
          description: VM Update Specs Response
      security:
        - authorization:
            - vm:manage
      summary: Update VM Specs
      tags:
        - vm
  /vm/{id}/start:
    post:
      callbacks: {}
      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.
      operationId: vm/start
      parameters:
        - description: Sandbox ID
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VMStartRequest'
        description: VM Start Request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMStartResponse'
          description: VM Start Response
      security:
        - authorization:
            - sandbox:read
            - vm:manage
      summary: Start a VM
      tags:
        - vm
  /vm/{id}/update_specs:
    post:
      callbacks: {}
      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.
      operationId: vm/update_specs (2)
      parameters:
        - description: Sandbox ID
          example: new
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VMUpdateSpecsRequest'
        description: VM Update Specs Request
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VMUpdateSpecsResponse'
          description: VM Update Specs Response
      security:
        - authorization:
            - vm:manage
      summary: Update VM Specs
      tags:
        - vm
  /workspace/preview_hosts:
    get:
      callbacks: {}
      description: |
        List all trusted preview hosts for the current team
      operationId: preview_host/list
      parameters: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewHostListResponse'
          description: Preview Host List Response
      security:
        - authorization:
            - vm:manage
      summary: List Preview Hosts
      tags: []
    post:
      callbacks: {}
      description: |
        Add one or more trusted domains that are allowed to access sandbox previews for this workspace.
      operationId: preview_host/create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewHostRequest'
        description: Preview Host Create Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewHostListResponse'
          description: Preview Host List Response
      security:
        - authorization:
            - vm:manage
      summary: Create Preview Hosts
      tags: []
    put:
      callbacks: {}
      description: |
        Replace the list of trusted domains that are allowed to access sandbox previews for this workspace.
      operationId: preview_host/update
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewHostRequest'
        description: Preview Host Update Request
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewHostListResponse'
          description: Preview Host List Response
      security:
        - authorization:
            - vm:manage
      summary: Update Preview Hosts
      tags: []
security: []
servers:
  - url: https://api.codesandbox.stream
    variables: {}
tags: []