openapi: 3.0.0
info:
  version: 0.1.0
  title: E2B API

servers:
  - url: https://api.e2b.app

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    AccessTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: access_token
    # Generated code uses security schemas in the alphabetical order.
    # In order to check first the token, and then the team (so we can already use the user),
    # there is a 1 and 2 present in the names of the security schemas.
    Supabase1TokenAuth:
      type: apiKey
      in: header
      name: X-Supabase-Token
    Supabase2TeamAuth:
      type: apiKey
      in: header
      name: X-Supabase-Team
    AdminTokenAuth:
      type: apiKey
      in: header
      name: X-Admin-Token

  parameters:
    templateID:
      name: templateID
      in: path
      required: true
      schema:
        type: string
    buildID:
      name: buildID
      in: path
      required: true
      schema:
        type: string
    sandboxID:
      name: sandboxID
      in: path
      required: true
      schema:
        type: string
    teamID:
      name: teamID
      in: path
      required: true
      schema:
        type: string
    nodeID:
      name: nodeID
      in: path
      required: true
      schema:
        type: string
    apiKeyID:
      name: apiKeyID
      in: path
      required: true
      schema:
        type: string
    accessTokenID:
      name: accessTokenID
      in: path
      required: true
      schema:
        type: string
    snapshotID:
      name: snapshotID
      in: path
      required: true
      schema:
        type: string
        description: Identifier of the snapshot (template ID)
    tag:
      name: tag
      in: path
      required: true
      schema:
        type: string
        description: Tag name
    paginationLimit:
      name: limit
      in: query
      description: Maximum number of items to return per page
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 100
        maximum: 100
    paginationNextToken:
      name: nextToken
      in: query
      description: Cursor to start the list from
      required: false
      schema:
        type: string
    volumeID:
      name: volumeID
      in: path
      required: true
      schema:
        type: string

  responses:
    '400':
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Authentication error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '409':
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Team:
      required:
        - teamID
        - name
        - apiKey
        - isDefault
      properties:
        teamID:
          type: string
          description: Identifier of the team
        name:
          type: string
          description: Name of the team
        apiKey:
          type: string
          description: API key for the team
        isDefault:
          type: boolean
          description: Whether the team is the default team

    TeamUser:
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the user
        email:
          type: string
          description: Email of the user

    TemplateUpdateRequest:
      properties:
        public:
          type: boolean
          description: Whether the template is public or only accessible by the team

    TemplateUpdateResponse:
      required:
        - names
      properties:
        names:
          type: array
          description: Names of the template (namespace/alias format when namespaced)
          items:
            type: string

    CPUCount:
      type: integer
      format: int32
      minimum: 1
      description: CPU cores for the sandbox

    MemoryMB:
      type: integer
      format: int32
      minimum: 128
      description: Memory for the sandbox in MiB

    DiskSizeMB:
      type: integer
      format: int32
      minimum: 0
      description: Disk size for the sandbox in MiB

    EnvdVersion:
      type: string
      description: Version of the envd running in the sandbox

    SandboxMetadata:
      additionalProperties:
        type: string
        description: Metadata of the sandbox

    SandboxState:
      type: string
      description: State of the sandbox
      enum:
        - running
        - paused

    SnapshotInfo:
      type: object
      required:
        - snapshotID
        - names
      properties:
        snapshotID:
          type: string
          description: Identifier of the snapshot template including the tag. Uses namespace/alias when a name was provided (e.g. team-slug/my-snapshot:default), otherwise falls back to the raw template ID (e.g. abc123:default).
        names:
          type: array
          items:
            type: string
          description: Full names of the snapshot template including team namespace and tag (e.g. team-slug/my-snapshot:v2)

    EnvVars:
      additionalProperties:
        type: string
        description: Environment variables for the sandbox

    Mcp:
      type: object
      description: MCP configuration for the sandbox
      additionalProperties: {}
      nullable: true

    SandboxNetworkConfig:
      type: object
      properties:
        allowPublicTraffic:
          type: boolean
          default: true
          description: Specify if the sandbox URLs should be accessible only with authentication.
        allowOut:
          type: array
          description: List of allowed CIDR blocks or IP addresses for egress traffic. Allowed addresses always take precedence over blocked addresses.
          items:
            type: string
        denyOut:
          type: array
          description: List of denied CIDR blocks or IP addresses for egress traffic
          items:
            type: string
        maskRequestHost:
          type: string
          description: Specify host mask which will be used for all sandbox requests

    SandboxAutoResumeEnabled:
      type: boolean
      description: Auto-resume enabled flag for paused sandboxes. Default false.
      default: false

    SandboxAutoResumeConfig:
      type: object
      description: Auto-resume configuration for paused sandboxes.
      required:
        - enabled
      properties:
        enabled:
          $ref: "#/components/schemas/SandboxAutoResumeEnabled"

    SandboxOnTimeout:
      type: string
      description: Action taken when the sandbox times out.
      enum:
        - kill
        - pause

    SandboxLifecycle:
      type: object
      description: Sandbox lifecycle policy returned by sandbox info.
      required:
        - autoResume
        - onTimeout
      properties:
        autoResume:
          type: boolean
          description: Whether the sandbox can auto-resume.
        onTimeout:
          $ref: "#/components/schemas/SandboxOnTimeout"

    SandboxLog:
      description: Log entry with timestamp and line
      required:
        - timestamp
        - line
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the log entry
        line:
          type: string
          description: Log line content

    SandboxLogEntry:
      required:
        - timestamp
        - level
        - message
        - fields
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the log entry
        message:
          type: string
          description: Log message content
        level:
          $ref: '#/components/schemas/LogLevel'
        fields:
          type: object
          additionalProperties:
            type: string

    SandboxLogs:
      required:
        - logs
        - logEntries
      properties:
        logs:
          description: Logs of the sandbox
          type: array
          items:
            $ref: '#/components/schemas/SandboxLog'
        logEntries:
          description: Structured logs of the sandbox
          type: array
          items:
            $ref: '#/components/schemas/SandboxLogEntry'

    SandboxLogsV2Response:
      required:
        - logs
      properties:
        logs:
          default: []
          description: Sandbox logs structured
          type: array
          items:
            $ref: '#/components/schemas/SandboxLogEntry'

    SandboxMetric:
      description: Metric entry with timestamp and line
      required:
        - timestamp
        - timestampUnix
        - cpuCount
        - cpuUsedPct
        - memUsed
        - memTotal
        - diskUsed
        - diskTotal
      properties:
        timestamp:
          type: string
          format: date-time
          deprecated: true
          description: Timestamp of the metric entry
        timestampUnix:
          type: integer
          format: int64
          description: Timestamp of the metric entry in Unix time (seconds since epoch)
        cpuCount:
          type: integer
          format: int32
          description: Number of CPU cores
        cpuUsedPct:
          type: number
          format: float
          description: CPU usage percentage
        memUsed:
          type: integer
          format: int64
          description: Memory used in bytes
        memTotal:
          type: integer
          format: int64
          description: Total memory in bytes
        diskUsed:
          type: integer
          format: int64
          description: Disk used in bytes
        diskTotal:
          type: integer
          format: int64
          description: Total disk space in bytes

    SandboxVolumeMount:
      type: object
      properties:
        name:
          type: string
          description: Name of the volume
        path:
          type: string
          description: Path of the volume
      required:
        - name
        - path

    Sandbox:
      required:
        - templateID
        - sandboxID
        - clientID
        - envdVersion
      properties:
        templateID:
          type: string
          description: Identifier of the template from which is the sandbox created
        sandboxID:
          type: string
          description: Identifier of the sandbox
        alias:
          type: string
          description: Alias of the template
        clientID:
          type: string
          deprecated: true
          description: Identifier of the client
        envdVersion:
          $ref: '#/components/schemas/EnvdVersion'
        envdAccessToken:
          type: string
          description: Access token used for envd communication
        trafficAccessToken:
          type: string
          nullable: true
          description: Token required for accessing sandbox via proxy.
        domain:
          type: string
          nullable: true
          description: Base domain where the sandbox traffic is accessible

    SandboxDetail:
      required:
        - templateID
        - sandboxID
        - clientID
        - startedAt
        - cpuCount
        - memoryMB
        - diskSizeMB
        - endAt
        - state
        - envdVersion
      properties:
        templateID:
          type: string
          description: Identifier of the template from which is the sandbox created
        alias:
          type: string
          description: Alias of the template
        sandboxID:
          type: string
          description: Identifier of the sandbox
        clientID:
          type: string
          deprecated: true
          description: Identifier of the client
        startedAt:
          type: string
          format: date-time
          description: Time when the sandbox was started
        endAt:
          type: string
          format: date-time
          description: Time when the sandbox will expire
        envdVersion:
          $ref: '#/components/schemas/EnvdVersion'
        envdAccessToken:
          type: string
          description: Access token used for envd communication
        allowInternetAccess:
          type: boolean
          nullable: true
          description: Whether internet access was explicitly enabled or disabled for the sandbox. Null means it was not explicitly set.
        domain:
          type: string
          nullable: true
          description: Base domain where the sandbox traffic is accessible
        cpuCount:
          $ref: '#/components/schemas/CPUCount'
        memoryMB:
          $ref: '#/components/schemas/MemoryMB'
        diskSizeMB:
          $ref: '#/components/schemas/DiskSizeMB'
        metadata:
          $ref: '#/components/schemas/SandboxMetadata'
        state:
          $ref: '#/components/schemas/SandboxState'
        network:
          $ref: '#/components/schemas/SandboxNetworkConfig'
        lifecycle:
          $ref: '#/components/schemas/SandboxLifecycle'
        volumeMounts:
          type: array
          items:
            $ref: '#/components/schemas/SandboxVolumeMount'

    ListedSandbox:
      required:
        - templateID
        - sandboxID
        - clientID
        - startedAt
        - cpuCount
        - memoryMB
        - diskSizeMB
        - endAt
        - state
        - envdVersion
      properties:
        templateID:
          type: string
          description: Identifier of the template from which is the sandbox created
        alias:
          type: string
          description: Alias of the template
        sandboxID:
          type: string
          description: Identifier of the sandbox
        clientID:
          type: string
          deprecated: true
          description: Identifier of the client
        startedAt:
          type: string
          format: date-time
          description: Time when the sandbox was started
        endAt:
          type: string
          format: date-time
          description: Time when the sandbox will expire
        cpuCount:
          $ref: '#/components/schemas/CPUCount'
        memoryMB:
          $ref: '#/components/schemas/MemoryMB'
        diskSizeMB:
          $ref: '#/components/schemas/DiskSizeMB'
        metadata:
          $ref: '#/components/schemas/SandboxMetadata'
        state:
          $ref: '#/components/schemas/SandboxState'
        envdVersion:
          $ref: '#/components/schemas/EnvdVersion'
        volumeMounts:
          type: array
          items:
            $ref: '#/components/schemas/SandboxVolumeMount'

    SandboxesWithMetrics:
      required:
        - sandboxes
      properties:
        sandboxes:
          additionalProperties:
            $ref: '#/components/schemas/SandboxMetric'

    NewSandbox:
      required:
        - templateID
      properties:
        templateID:
          type: string
          description: Identifier of the required template
        timeout:
          type: integer
          format: int32
          minimum: 0
          default: 15
          description: Time to live for the sandbox in seconds.
        autoPause:
          type: boolean
          default: false
          description: Automatically pauses the sandbox after the timeout
        autoResume:
          $ref: '#/components/schemas/SandboxAutoResumeConfig'
        secure:
          type: boolean
          description: Secure all system communication with sandbox
        allow_internet_access:
          type: boolean
          description:
            Allow sandbox to access the internet. When set to false, it behaves the same as specifying denyOut
            to 0.0.0.0/0 in the network config.
        network:
          $ref: '#/components/schemas/SandboxNetworkConfig'
        metadata:
          $ref: '#/components/schemas/SandboxMetadata'
        envVars:
          $ref: '#/components/schemas/EnvVars'
        mcp:
          $ref: '#/components/schemas/Mcp'
        volumeMounts:
          type: array
          items:
            $ref: '#/components/schemas/SandboxVolumeMount'

    ResumedSandbox:
      properties:
        timeout:
          type: integer
          format: int32
          minimum: 0
          default: 15
          description: Time to live for the sandbox in seconds.
        autoPause:
          type: boolean
          deprecated: true
          description: Automatically pauses the sandbox after the timeout

    ConnectSandbox:
      type: object
      required:
        - timeout
      properties:
        timeout:
          description: Timeout in seconds from the current time after which the sandbox should expire
          type: integer
          format: int32
          minimum: 0

    TeamMetric:
      description: Team metric with timestamp
      required:
        - timestamp
        - timestampUnix
        - concurrentSandboxes
        - sandboxStartRate
      properties:
        timestamp:
          type: string
          format: date-time
          deprecated: true
          description: Timestamp of the metric entry
        timestampUnix:
          type: integer
          format: int64
          description: Timestamp of the metric entry in Unix time (seconds since epoch)
        concurrentSandboxes:
          type: integer
          format: int32
          description: The number of concurrent sandboxes for the team
        sandboxStartRate:
          type: number
          format: float
          description: Number of sandboxes started per second

    MaxTeamMetric:
      description: Team metric with timestamp
      required:
        - timestamp
        - timestampUnix
        - value
      properties:
        timestamp:
          type: string
          format: date-time
          deprecated: true
          description: Timestamp of the metric entry
        timestampUnix:
          type: integer
          format: int64
          description: Timestamp of the metric entry in Unix time (seconds since epoch)
        value:
          type: number
          description: The maximum value of the requested metric in the given interval

    AdminSandboxKillResult:
      required:
        - killedCount
        - failedCount
      properties:
        killedCount:
          type: integer
          description: Number of sandboxes successfully killed
        failedCount:
          type: integer
          description: Number of sandboxes that failed to kill

    AdminBuildCancelResult:
      required:
        - cancelledCount
        - failedCount
      properties:
        cancelledCount:
          type: integer
          description: Number of builds successfully cancelled
        failedCount:
          type: integer
          description: Number of builds that failed to cancel

    VolumeToken:
      type: object
      properties:
        token:
          type: string
      required:
        - token

    Template:
      required:
        - templateID
        - buildID
        - cpuCount
        - memoryMB
        - diskSizeMB
        - public
        - createdAt
        - updatedAt
        - createdBy
        - lastSpawnedAt
        - spawnCount
        - buildCount
        - envdVersion
        - aliases
        - names
        - buildStatus
      properties:
        templateID:
          type: string
          description: Identifier of the template
        buildID:
          type: string
          description: Identifier of the last successful build for given template
        cpuCount:
          $ref: '#/components/schemas/CPUCount'
        memoryMB:
          $ref: '#/components/schemas/MemoryMB'
        diskSizeMB:
          $ref: '#/components/schemas/DiskSizeMB'
        public:
          type: boolean
          description: Whether the template is public or only accessible by the team
        aliases:
          type: array
          description: Aliases of the template
          deprecated: true
          items:
            type: string
        names:
          type: array
          description: Names of the template (namespace/alias format when namespaced)
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          description: Time when the template was created
        updatedAt:
          type: string
          format: date-time
          description: Time when the template was last updated
        createdBy:
          allOf:
            - $ref: '#/components/schemas/TeamUser'
          nullable: true
        lastSpawnedAt:
          type: string
          nullable: true
          format: date-time
          description: Time when the template was last used
        spawnCount:
          type: integer
          format: int64
          description: Number of times the template was used
        buildCount:
          type: integer
          format: int32
          description: Number of times the template was built
        envdVersion:
          $ref: '#/components/schemas/EnvdVersion'
        buildStatus:
          $ref: '#/components/schemas/TemplateBuildStatus'

    TemplateRequestResponseV3:
      required:
        - templateID
        - buildID
        - public
        - aliases
        - names
        - tags
      properties:
        templateID:
          type: string
          description: Identifier of the template
        buildID:
          type: string
          description: Identifier of the last successful build for given template
        public:
          type: boolean
          description: Whether the template is public or only accessible by the team
        names:
          type: array
          description: Names of the template
          items:
            type: string
        tags:
          type: array
          description: Tags assigned to the template build
          items:
            type: string
        aliases:
          type: array
          description: Aliases of the template
          deprecated: true
          items:
            type: string

    TemplateLegacy:
      required:
        - templateID
        - buildID
        - cpuCount
        - memoryMB
        - diskSizeMB
        - public
        - createdAt
        - updatedAt
        - createdBy
        - lastSpawnedAt
        - spawnCount
        - buildCount
        - envdVersion
        - aliases
      properties:
        templateID:
          type: string
          description: Identifier of the template
        buildID:
          type: string
          description: Identifier of the last successful build for given template
        cpuCount:
          $ref: '#/components/schemas/CPUCount'
        memoryMB:
          $ref: '#/components/schemas/MemoryMB'
        diskSizeMB:
          $ref: '#/components/schemas/DiskSizeMB'
        public:
          type: boolean
          description: Whether the template is public or only accessible by the team
        aliases:
          type: array
          description: Aliases of the template
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          description: Time when the template was created
        updatedAt:
          type: string
          format: date-time
          description: Time when the template was last updated
        createdBy:
          allOf:
            - $ref: '#/components/schemas/TeamUser'
          nullable: true
        lastSpawnedAt:
          type: string
          nullable: true
          format: date-time
          description: Time when the template was last used
        spawnCount:
          type: integer
          format: int64
          description: Number of times the template was used
        buildCount:
          type: integer
          format: int32
          description: Number of times the template was built
        envdVersion:
          $ref: '#/components/schemas/EnvdVersion'

    TemplateBuild:
      required:
        - buildID
        - status
        - createdAt
        - updatedAt
        - cpuCount
        - memoryMB
      properties:
        buildID:
          type: string
          format: uuid
          description: Identifier of the build
        status:
          $ref: '#/components/schemas/TemplateBuildStatus'
        createdAt:
          type: string
          format: date-time
          description: Time when the build was created
        updatedAt:
          type: string
          format: date-time
          description: Time when the build was last updated
        finishedAt:
          type: string
          format: date-time
          description: Time when the build was finished
        cpuCount:
          $ref: '#/components/schemas/CPUCount'
        memoryMB:
          $ref: '#/components/schemas/MemoryMB'
        diskSizeMB:
          $ref: '#/components/schemas/DiskSizeMB'
        envdVersion:
          $ref: '#/components/schemas/EnvdVersion'

    TemplateWithBuilds:
      required:
        - templateID
        - public
        - aliases
        - names
        - createdAt
        - updatedAt
        - lastSpawnedAt
        - spawnCount
        - builds
      properties:
        templateID:
          type: string
          description: Identifier of the template
        public:
          type: boolean
          description: Whether the template is public or only accessible by the team
        aliases:
          type: array
          description: Aliases of the template
          deprecated: true
          items:
            type: string
        names:
          type: array
          description: Names of the template (namespace/alias format when namespaced)
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          description: Time when the template was created
        updatedAt:
          type: string
          format: date-time
          description: Time when the template was last updated
        lastSpawnedAt:
          type: string
          nullable: true
          format: date-time
          description: Time when the template was last used
        spawnCount:
          type: integer
          format: int64
          description: Number of times the template was used
        builds:
          type: array
          description: List of builds for the template
          items:
            $ref: '#/components/schemas/TemplateBuild'

    TemplateAliasResponse:
      required:
        - templateID
        - public
      properties:
        templateID:
          type: string
          description: Identifier of the template
        public:
          type: boolean
          description: Whether the template is public or only accessible by the team

    TemplateBuildRequest:
      required:
        - dockerfile
      properties:
        alias:
          description: Alias of the template
          type: string
        dockerfile:
          description: Dockerfile for the template
          type: string
        teamID:
          type: string
          description: Identifier of the team
        startCmd:
          description: Start command to execute in the template after the build
          type: string
        readyCmd:
          description: Ready check command to execute in the template after the build
          type: string
        cpuCount:
          $ref: '#/components/schemas/CPUCount'
        memoryMB:
          $ref: '#/components/schemas/MemoryMB'

    TemplateStep:
      description: Step in the template build process
      required:
        - type
      properties:
        type:
          type: string
          description: Type of the step
        args:
          default: []
          type: array
          description: Arguments for the step
          items:
            type: string
        filesHash:
          type: string
          description: Hash of the files used in the step
        force:
          default: false
          type: boolean
          description: Whether the step should be forced to run regardless of the cache

    TemplateBuildRequestV3:
      properties:
        name:
          description: Name of the template. Can include a tag with colon separator (e.g. "my-template" or "my-template:v1"). If tag is included, it will be treated as if the tag was provided in the tags array.
          type: string
        tags:
          type: array
          description: Tags to assign to the template build
          items:
            type: string
        alias:
          description: Alias of the template. Deprecated, use name instead.
          type: string
          deprecated: true
        teamID:
          deprecated: true
          type: string
          description: Identifier of the team
        cpuCount:
          $ref: '#/components/schemas/CPUCount'
        memoryMB:
          $ref: '#/components/schemas/MemoryMB'

    TemplateBuildRequestV2:
      required:
        - alias
      properties:
        alias:
          description: Alias of the template
          type: string
        teamID:
          deprecated: true
          type: string
          description: Identifier of the team
        cpuCount:
          $ref: '#/components/schemas/CPUCount'
        memoryMB:
          $ref: '#/components/schemas/MemoryMB'

    FromImageRegistry:
      oneOf:
        - $ref: '#/components/schemas/AWSRegistry'
        - $ref: '#/components/schemas/GCPRegistry'
        - $ref: '#/components/schemas/GeneralRegistry'
      discriminator:
        propertyName: type
        mapping:
          aws: '#/components/schemas/AWSRegistry'
          gcp: '#/components/schemas/GCPRegistry'
          registry: '#/components/schemas/GeneralRegistry'

    AWSRegistry:
      type: object
      required:
        - type
        - awsAccessKeyId
        - awsSecretAccessKey
        - awsRegion
      properties:
        type:
          type: string
          enum: [aws]
          description: Type of registry authentication
        awsAccessKeyId:
          type: string
          description: AWS Access Key ID for ECR authentication
        awsSecretAccessKey:
          type: string
          description: AWS Secret Access Key for ECR authentication
        awsRegion:
          type: string
          description: AWS Region where the ECR registry is located

    GCPRegistry:
      type: object
      required:
        - type
        - serviceAccountJson
      properties:
        type:
          type: string
          enum: [gcp]
          description: Type of registry authentication
        serviceAccountJson:
          type: string
          description: Service Account JSON for GCP authentication

    GeneralRegistry:
      type: object
      required:
        - type
        - username
        - password
      properties:
        type:
          type: string
          enum: [registry]
          description: Type of registry authentication
        username:
          type: string
          description: Username to use for the registry
        password:
          type: string
          description: Password to use for the registry

    TemplateBuildStartV2:
      type: object
      properties:
        fromImage:
          type: string
          description: Image to use as a base for the template build
        fromTemplate:
          type: string
          description: Template to use as a base for the template build
        fromImageRegistry:
          $ref: '#/components/schemas/FromImageRegistry'
        force:
          default: false
          type: boolean
          description: Whether the whole build should be forced to run regardless of the cache
        steps:
          default: []
          description: List of steps to execute in the template build
          type: array
          items:
            $ref: '#/components/schemas/TemplateStep'
        startCmd:
          description: Start command to execute in the template after the build
          type: string
        readyCmd:
          description: Ready check command to execute in the template after the build
          type: string

    TemplateBuildFileUpload:
      required:
        - present
      properties:
        present:
          type: boolean
          description: Whether the file is already present in the cache
        url:
          description: Url where the file should be uploaded to
          type: string

    LogLevel:
      type: string
      description: State of the sandbox
      enum:
        - debug
        - info
        - warn
        - error

    BuildLogEntry:
      required:
        - timestamp
        - message
        - level
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the log entry
        message:
          type: string
          description: Log message content
        level:
          $ref: '#/components/schemas/LogLevel'
        step:
          type: string
          description: Step in the build process related to the log entry

    BuildStatusReason:
      required:
        - message
      properties:
        message:
          type: string
          description: Message with the status reason, currently reporting only for error status
        step:
          type: string
          description: Step that failed
        logEntries:
          default: []
          description: Log entries related to the status reason
          type: array
          items:
            $ref: '#/components/schemas/BuildLogEntry'

    TemplateBuildStatus:
      type: string
      description: Status of the template build
      enum:
        - building
        - waiting
        - ready
        - error

    TemplateBuildInfo:
      required:
        - templateID
        - buildID
        - status
        - logs
        - logEntries
      properties:
        logs:
          default: []
          description: Build logs
          type: array
          items:
            type: string
        logEntries:
          default: []
          description: Build logs structured
          type: array
          items:
            $ref: '#/components/schemas/BuildLogEntry'
        templateID:
          type: string
          description: Identifier of the template
        buildID:
          type: string
          description: Identifier of the build
        status:
          $ref: '#/components/schemas/TemplateBuildStatus'
        reason:
          $ref: '#/components/schemas/BuildStatusReason'

    TemplateBuildLogsResponse:
      required:
        - logs
      properties:
        logs:
          default: []
          description: Build logs structured
          type: array
          items:
            $ref: '#/components/schemas/BuildLogEntry'

    LogsDirection:
      type: string
      description: Direction of the logs that should be returned
      enum:
        - forward
        - backward
      x-enum-varnames:
        - LogsDirectionForward
        - LogsDirectionBackward

    LogsSource:
      type: string
      description: Source of the logs that should be returned
      enum:
        - temporary
        - persistent
      x-enum-varnames:
        - LogsSourceTemporary
        - LogsSourcePersistent

    NodeStatus:
      type: string
      description: Status of the node
      enum:
        - ready
        - draining
        - connecting
        - unhealthy
      x-enum-varnames:
        - NodeStatusReady
        - NodeStatusDraining
        - NodeStatusConnecting
        - NodeStatusUnhealthy

    NodeStatusChange:
      required:
        - status
      properties:
        clusterID:
          type: string
          format: uuid
          description: Identifier of the cluster
        status:
          $ref: '#/components/schemas/NodeStatus'

    DiskMetrics:
      required:
        - mountPoint
        - device
        - filesystemType
        - usedBytes
        - totalBytes
      properties:
        mountPoint:
          type: string
          description: Mount point of the disk
        device:
          type: string
          description: Device name
        filesystemType:
          type: string
          description: Filesystem type (e.g., ext4, xfs)
        usedBytes:
          type: integer
          format: uint64
          description: Used space in bytes
        totalBytes:
          type: integer
          format: uint64
          description: Total space in bytes

    NodeMetrics:
      description: Node metrics
      required:
        - allocatedCPU
        - allocatedMemoryBytes
        - cpuPercent
        - memoryUsedBytes
        - cpuCount
        - memoryTotalBytes
        - disks
      properties:
        allocatedCPU:
          type: integer
          format: uint32
          description: Number of allocated CPU cores
        cpuPercent:
          type: integer
          format: uint32
          description: Node CPU usage percentage
        cpuCount:
          type: integer
          format: uint32
          description: Total number of CPU cores on the node
        allocatedMemoryBytes:
          type: integer
          format: uint64
          description: Amount of allocated memory in bytes
        memoryUsedBytes:
          type: integer
          format: uint64
          description: Node memory used in bytes
        memoryTotalBytes:
          type: integer
          format: uint64
          description: Total node memory in bytes
        disks:
          type: array
          description: Detailed metrics for each disk/mount point
          items:
            $ref: '#/components/schemas/DiskMetrics'
    MachineInfo:
      required:
        - cpuFamily
        - cpuModel
        - cpuModelName
        - cpuArchitecture
      properties:
        cpuFamily:
          type: string
          description: CPU family of the node
        cpuModel:
          type: string
          description: CPU model of the node
        cpuModelName:
          type: string
          description: CPU model name of the node
        cpuArchitecture:
          type: string
          description: CPU architecture of the node

    Node:
      required:
        - id
        - serviceInstanceID
        - clusterID
        - status
        - sandboxCount
        - metrics
        - createSuccesses
        - createFails
        - sandboxStartingCount
        - version
        - commit
        - machineInfo
      properties:
        version:
          type: string
          description: Version of the orchestrator
        commit:
          type: string
          description: Commit of the orchestrator
        id:
          type: string
          description: Identifier of the node
        serviceInstanceID:
          type: string
          description: Service instance identifier of the node
        clusterID:
          type: string
          description: Identifier of the cluster
        machineInfo:
          $ref: '#/components/schemas/MachineInfo'
        status:
          $ref: '#/components/schemas/NodeStatus'
        sandboxCount:
          type: integer
          format: uint32
          description: Number of sandboxes running on the node
        metrics:
          $ref: '#/components/schemas/NodeMetrics'
        createSuccesses:
          type: integer
          format: uint64
          description: Number of sandbox create successes
        createFails:
          type: integer
          format: uint64
          description: Number of sandbox create fails
        sandboxStartingCount:
          type: integer
          format: int
          description: Number of starting Sandboxes

    NodeDetail:
      required:
        - id
        - serviceInstanceID
        - clusterID
        - status
        - sandboxCount
        - cachedBuilds
        - createSuccesses
        - createFails
        - version
        - commit
        - metrics
        - machineInfo
      properties:
        clusterID:
          type: string
          description: Identifier of the cluster
        version:
          type: string
          description: Version of the orchestrator
        commit:
          type: string
          description: Commit of the orchestrator
        id:
          type: string
          description: Identifier of the node
        serviceInstanceID:
          type: string
          description: Service instance identifier of the node
        machineInfo:
          $ref: '#/components/schemas/MachineInfo'
        status:
          $ref: '#/components/schemas/NodeStatus'
        sandboxCount:
          type: integer
          format: uint32
          description: Number of sandboxes running on the node
        metrics:
          $ref: '#/components/schemas/NodeMetrics'
        cachedBuilds:
          type: array
          description: List of cached builds id on the node
          items:
            type: string
        createSuccesses:
          type: integer
          format: uint64
          description: Number of sandbox create successes
        createFails:
          type: integer
          format: uint64
          description: Number of sandbox create fails

    CreatedAccessToken:
      required:
        - id
        - name
        - token
        - mask
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the access token
        name:
          type: string
          description: Name of the access token
        token:
          type: string
          description: The fully created access token
        mask:
          $ref: '#/components/schemas/IdentifierMaskingDetails'
        createdAt:
          type: string
          format: date-time
          description: Timestamp of access token creation

    NewAccessToken:
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the access token

    TeamAPIKey:
      required:
        - id
        - name
        - mask
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the API key
        name:
          type: string
          description: Name of the API key
        mask:
          $ref: '#/components/schemas/IdentifierMaskingDetails'
        createdAt:
          type: string
          format: date-time
          description: Timestamp of API key creation
        createdBy:
          allOf:
            - $ref: '#/components/schemas/TeamUser'
          nullable: true
        lastUsed:
          type: string
          format: date-time
          description: Last time this API key was used
          nullable: true

    CreatedTeamAPIKey:
      required:
        - id
        - key
        - mask
        - name
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the API key
        key:
          type: string
          description: Raw value of the API key
        mask:
          $ref: '#/components/schemas/IdentifierMaskingDetails'
        name:
          type: string
          description: Name of the API key
        createdAt:
          type: string
          format: date-time
          description: Timestamp of API key creation
        createdBy:
          allOf:
            - $ref: '#/components/schemas/TeamUser'
          nullable: true
        lastUsed:
          type: string
          format: date-time
          description: Last time this API key was used
          nullable: true

    NewTeamAPIKey:
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the API key

    UpdateTeamAPIKey:
      required:
        - name
      properties:
        name:
          type: string
          description: New name for the API key

    AssignedTemplateTags:
      required:
        - tags
        - buildID
      properties:
        tags:
          type: array
          items:
            type: string
          description: Assigned tags of the template
        buildID:
          type: string
          format: uuid
          description: Identifier of the build associated with these tags

    TemplateTag:
      required:
        - tag
        - buildID
        - createdAt
      properties:
        tag:
          type: string
          description: The tag name
        buildID:
          type: string
          format: uuid
          description: Identifier of the build associated with this tag
        createdAt:
          type: string
          format: date-time
          description: Time when the tag was assigned

    AssignTemplateTagsRequest:
      required:
        - target
        - tags
      properties:
        target:
          type: string
          description: Target template in "name:tag" format
        tags:
          description: Tags to assign to the template
          type: array
          items:
            type: string

    DeleteTemplateTagsRequest:
      required:
        - name
        - tags
      properties:
        name:
          type: string
          description: Name of the template
        tags:
          description: Tags to delete
          type: array
          items:
            type: string

    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error

    IdentifierMaskingDetails:
      required:
        - prefix
        - valueLength
        - maskedValuePrefix
        - maskedValueSuffix
      properties:
        prefix:
          type: string
          description: Prefix that identifies the token or key type
        valueLength:
          type: integer
          description: Length of the token or key
        maskedValuePrefix:
          type: string
          description: Prefix used in masked version of the token or key
        maskedValueSuffix:
          type: string
          description: Suffix used in masked version of the token or key

    Volume:
      type: object
      properties:
        volumeID:
          type: string
          description: ID of the volume
        name:
          type: string
          description: Name of the volume
      required:
        - volumeID
        - name

    VolumeAndToken:
      type: object
      properties:
        volumeID:
          type: string
          description: ID of the volume
        name:
          type: string
          description: Name of the volume
        token:
          type: string
          description: Auth token to use for interacting with volume content
      required:
        - volumeID
        - name
        - token

    NewVolume:
      type: object
      properties:
        name:
          type: string
          description: Name of the volume
          pattern: '^[a-zA-Z0-9_-]+$'
      required:
        - name

tags:
  - name: templates
  - name: sandboxes
  - name: auth
  - name: access-tokens
  - name: api-keys
  - name: tags
  - name: volumes

paths:
  /health:
    get:
      description: Health check
      responses:
        '200':
          description: Request was successful
        '401':
          $ref: '#/components/responses/401'

  /teams:
    get:
      description: List all teams
      tags: [auth]
      security:
        - AccessTokenAuth: []
        - Supabase1TokenAuth: []
      responses:
        '200':
          description: Successfully returned all teams
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /teams/{teamID}/metrics:
    get:
      description: Get metrics for the team
      tags: [auth]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/teamID'
        - in: query
          name: start
          schema:
            type: integer
            format: int64
            minimum: 0
          description: Unix timestamp for the start of the interval, in seconds, for which the metrics
        - in: query
          name: end
          schema:
            type: integer
            format: int64
            minimum: 0
            description: Unix timestamp for the end of the interval, in seconds, for which the metrics
      responses:
        '200':
          description: Successfully returned the team metrics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TeamMetric'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'

  /teams/{teamID}/metrics/max:
    get:
      description: Get the maximum metrics for the team in the given interval
      tags: [auth]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/teamID'
        - in: query
          name: start
          schema:
            type: integer
            format: int64
            minimum: 0
          description: Unix timestamp for the start of the interval, in seconds, for which the metrics
        - in: query
          name: end
          schema:
            type: integer
            format: int64
            minimum: 0
            description: Unix timestamp for the end of the interval, in seconds, for which the metrics
        - in: query
          name: metric
          required: true
          schema:
            type: string
            enum: [concurrent_sandboxes, sandbox_start_rate]
          description: Metric to retrieve the maximum value for
      responses:
        '200':
          description: Successfully returned the team metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaxTeamMetric'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'

  /sandboxes:
    get:
      description: List all running sandboxes
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - name: metadata
          in: query
          description: Metadata query used to filter the sandboxes (e.g. "user=abc&app=prod"). Each key and values must be URL encoded.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully returned all running sandboxes
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/ListedSandbox'
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
    post:
      description: Create a sandbox from the template
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewSandbox'
      responses:
        '201':
          description: The sandbox was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'

  /v2/sandboxes:
    get:
      description: List all sandboxes
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - name: metadata
          in: query
          description: Metadata query used to filter the sandboxes (e.g. "user=abc&app=prod"). Each key and values must be URL encoded.
          required: false
          schema:
            type: string
        - name: state
          in: query
          description: Filter sandboxes by one or more states
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SandboxState'
          style: form
          explode: false
        - $ref: '#/components/parameters/paginationNextToken'
        - $ref: '#/components/parameters/paginationLimit'
      responses:
        '200':
          description: Successfully returned all running sandboxes
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/ListedSandbox'
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'

  /sandboxes/metrics:
    get:
      description: List metrics for given sandboxes
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - name: sandbox_ids
          in: query
          required: true
          description: Comma-separated list of sandbox IDs to get metrics for
          explode: false
          schema:
            type: array
            items:
              type: string
            maxItems: 100
            uniqueItems: true
      responses:
        '200':
          description: Successfully returned all running sandboxes with metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxesWithMetrics'
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'

  /sandboxes/{sandboxID}/logs:
    get:
      description: Get sandbox logs. Use /v2/sandboxes/{sandboxID}/logs instead.
      deprecated: true
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/sandboxID'
        - in: query
          name: start
          schema:
            type: integer
            format: int64
            minimum: 0
          description: Starting timestamp of the logs that should be returned in milliseconds
        - in: query
          name: limit
          schema:
            default: 1000
            format: int32
            minimum: 0
            type: integer
          description: Maximum number of logs that should be returned
      responses:
        '200':
          description: Successfully returned the sandbox logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxLogs'
        '404':
          $ref: '#/components/responses/404'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /v2/sandboxes/{sandboxID}/logs:
    get:
      description: Get sandbox logs
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/sandboxID'
        - in: query
          name: cursor
          schema:
            type: integer
            format: int64
            minimum: 0
          description: Starting timestamp of the logs that should be returned in milliseconds
        - in: query
          name: limit
          schema:
            default: 1000
            type: integer
            format: int32
            minimum: 0
            maximum: 1000
          description: Maximum number of logs that should be returned
        - in: query
          name: direction
          schema:
            $ref: '#/components/schemas/LogsDirection'
          description: Direction of the logs that should be returned
        - in: query
          name: level
          schema:
            $ref: '#/components/schemas/LogLevel'
          description: Minimum log level to return. Logs below this level are excluded
        - in: query
          name: search
          schema:
            type: string
            maxLength: 256
          description: Case-sensitive substring match on log message content
      responses:
        '200':
          description: Successfully returned the sandbox logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxLogsV2Response'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /sandboxes/{sandboxID}:
    get:
      description: Get a sandbox by id
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/sandboxID'
      responses:
        '200':
          description: Successfully returned the sandbox
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxDetail'
        '404':
          $ref: '#/components/responses/404'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

    delete:
      description: Kill a sandbox
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/sandboxID'
      responses:
        '204':
          description: The sandbox was killed successfully
        '404':
          $ref: '#/components/responses/404'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /sandboxes/{sandboxID}/metrics:
    get:
      description: Get sandbox metrics
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/sandboxID'
        - in: query
          name: start
          schema:
            type: integer
            format: int64
            minimum: 0
          description: Unix timestamp for the start of the interval, in seconds, for which the metrics
        - in: query
          name: end
          schema:
            type: integer
            format: int64
            minimum: 0
            description: Unix timestamp for the end of the interval, in seconds, for which the metrics

      responses:
        '200':
          description: Successfully returned the sandbox metrics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SandboxMetric'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  # TODO: Pause and resume might be exposed as POST /sandboxes/{sandboxID}/snapshot and then POST /sandboxes with specified snapshotting setup
  /sandboxes/{sandboxID}/pause:
    post:
      description: Pause the sandbox
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/sandboxID'
      responses:
        '204':
          description: The sandbox was paused successfully and can be resumed
        '409':
          $ref: '#/components/responses/409'
        '404':
          $ref: '#/components/responses/404'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /sandboxes/{sandboxID}/resume:
    post:
      deprecated: true
      description: Resume the sandbox
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/sandboxID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumedSandbox'
      responses:
        '201':
          description: The sandbox was resumed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '409':
          $ref: '#/components/responses/409'
        '404':
          $ref: '#/components/responses/404'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /sandboxes/{sandboxID}/connect:
    post:
      description: Returns sandbox details. If the sandbox is paused, it will be resumed. TTL is only extended.
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/sandboxID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectSandbox'
      responses:
        '200':
          description: The sandbox was already running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '201':
          description: The sandbox was resumed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /sandboxes/{sandboxID}/timeout:
    post:
      description: Set the timeout for the sandbox. The sandbox will expire x seconds from the time of the request. Calling this method multiple times overwrites the TTL, each time using the current timestamp as the starting point to measure the timeout duration.
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      tags: [sandboxes]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - timeout
              properties:
                timeout:
                  description: Timeout in seconds from the current time after which the sandbox should expire
                  type: integer
                  format: int32
                  minimum: 0
      parameters:
        - $ref: '#/components/parameters/sandboxID'
      responses:
        '204':
          description: Successfully set the sandbox timeout
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /sandboxes/{sandboxID}/refreshes:
    post:
      description: Refresh the sandbox extending its time to live
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      tags: [sandboxes]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                duration:
                  description: Duration for which the sandbox should be kept alive in seconds
                  type: integer
                  maximum: 3600 # 1 hour
                  minimum: 0
      parameters:
        - $ref: '#/components/parameters/sandboxID'
      responses:
        '204':
          description: Successfully refreshed the sandbox
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'

  /sandboxes/{sandboxID}/snapshots:
    post:
      description: Create a persistent snapshot from the sandbox's current state. Snapshots can be used to create new sandboxes and persist beyond the original sandbox's lifetime.
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/sandboxID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Optional name for the snapshot template. If a snapshot template with this name already exists, a new build will be assigned to the existing template instead of creating a new one.
      responses:
        '201':
          description: Snapshot created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotInfo'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /snapshots:
    get:
      description: List all snapshots for the team
      tags: [snapshots]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - name: sandboxID
          in: query
          required: false
          schema:
            type: string
            description: Filter snapshots by source sandbox ID
        - $ref: '#/components/parameters/paginationLimit'
        - $ref: '#/components/parameters/paginationNextToken'
      responses:
        '200':
          description: Successfully returned snapshots
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SnapshotInfo'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /v3/templates:
    post:
      description: Create a new template
      tags: [templates]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateBuildRequestV3'

      responses:
        '202':
          description: The build was requested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateRequestResponseV3'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /v2/templates:
    post:
      description: Create a new template
      deprecated: true
      tags: [templates]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateBuildRequestV2'

      responses:
        '202':
          description: The build was requested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateLegacy'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /templates/{templateID}/files/{hash}:
    get:
      description: Get an upload link for a tar file containing build layer files
      tags: [templates]
      security:
        - AccessTokenAuth: []
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
        - in: path
          name: hash
          required: true
          schema:
            type: string
            description: Hash of the files

      responses:
        '201':
          description: The upload link where to upload the tar file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateBuildFileUpload'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /templates:
    get:
      description: List all templates
      tags: [templates]
      security:
        - ApiKeyAuth: []
        - AccessTokenAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - in: query
          required: false
          name: teamID
          schema:
            type: string
            description: Identifier of the team
      responses:
        '200':
          description: Successfully returned all templates
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/Template'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
    post:
      description: Create a new template
      deprecated: true
      tags: [templates]
      security:
        - AccessTokenAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateBuildRequest'

      responses:
        '202':
          description: The build was accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateLegacy'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /templates/{templateID}:
    get:
      description: List all builds for a template
      tags: [templates]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
        - $ref: '#/components/parameters/paginationNextToken'
        - $ref: '#/components/parameters/paginationLimit'
      responses:
        '200':
          description: Successfully returned the template with its builds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateWithBuilds'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
    post:
      description: Rebuild an template
      deprecated: true
      tags: [templates]
      security:
        - AccessTokenAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateBuildRequest'

      responses:
        '202':
          description: The build was accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateLegacy'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
    delete:
      description: Delete a template
      tags: [templates]
      security:
        - ApiKeyAuth: []
        - AccessTokenAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
      responses:
        '204':
          description: The template was deleted successfully
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
    patch:
      description: Update template
      deprecated: true
      tags: [templates]
      security:
        - ApiKeyAuth: []
        - AccessTokenAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateUpdateRequest'
      responses:
        '200':
          description: The template was updated successfully
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /templates/{templateID}/builds/{buildID}:
    post:
      description: Start the build
      deprecated: true
      tags: [templates]
      security:
        - AccessTokenAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
        - $ref: '#/components/parameters/buildID'
      responses:
        '202':
          description: The build has started
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /v2/templates/{templateID}/builds/{buildID}:
    post:
      description: Start the build
      tags: [templates]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
        - $ref: '#/components/parameters/buildID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateBuildStartV2'
      responses:
        '202':
          description: The build has started
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /v2/templates/{templateID}:
    patch:
      description: Update template
      tags: [templates]
      security:
        - ApiKeyAuth: []
        - AccessTokenAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateUpdateRequest'
      responses:
        '200':
          description: The template was updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateUpdateResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /templates/{templateID}/builds/{buildID}/status:
    get:
      description: Get template build info
      tags: [templates]
      security:
        - AccessTokenAuth: []
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
        - $ref: '#/components/parameters/buildID'
        - in: query
          name: logsOffset
          schema:
            default: 0
            type: integer
            format: int32
            minimum: 0
          description: Index of the starting build log that should be returned with the template
        - in: query
          name: limit
          schema:
            default: 100
            type: integer
            format: int32
            minimum: 0
            maximum: 100
          description: Maximum number of logs that should be returned
        - in: query
          name: level
          schema:
            $ref: '#/components/schemas/LogLevel'
      responses:
        '200':
          description: Successfully returned the template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateBuildInfo'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /templates/{templateID}/builds/{buildID}/logs:
    get:
      description: Get template build logs
      tags: [templates]
      security:
        - AccessTokenAuth: []
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
        - $ref: '#/components/parameters/buildID'
        - in: query
          name: cursor
          schema:
            type: integer
            format: int64
            minimum: 0
          description: Starting timestamp of the logs that should be returned in milliseconds
        - in: query
          name: limit
          schema:
            default: 100
            type: integer
            format: int32
            minimum: 0
            maximum: 100
          description: Maximum number of logs that should be returned
        - in: query
          name: direction
          schema:
            $ref: '#/components/schemas/LogsDirection'
        - in: query
          name: level
          schema:
            $ref: '#/components/schemas/LogLevel'
        - in: query
          name: source
          schema:
            $ref: '#/components/schemas/LogsSource'
          description: Source of the logs that should be returned from
      responses:
        '200':
          description: Successfully returned the template build logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateBuildLogsResponse'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /templates/tags:
    post:
      description: Assign tag(s) to a template build
      tags: [tags]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignTemplateTagsRequest'
      responses:
        '201':
          description: Tag assigned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignedTemplateTags'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    delete:
      description: Delete multiple tags from templates
      tags: [tags]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteTemplateTagsRequest'
      responses:
        '204':
          description: Tags deleted successfully
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /templates/{templateID}/tags:
    get:
      description: List all tags for a template
      tags: [tags]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/templateID'
      responses:
        '200':
          description: Successfully returned the template tags
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TemplateTag'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /templates/aliases/{alias}:
    get:
      description: Check if template with given alias exists
      tags: [templates]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - name: alias
          in: path
          required: true
          schema:
            type: string
            description: Template alias
      responses:
        '200':
          description: Successfully queried template by alias
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateAliasResponse'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /nodes:
    get:
      description: List all nodes
      tags: [admin]
      security:
        - AdminTokenAuth: []
      responses:
        '200':
          description: Successfully returned all nodes
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/Node'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /nodes/{nodeID}:
    get:
      description: Get node info
      tags: [admin]
      security:
        - AdminTokenAuth: []
      parameters:
        - $ref: '#/components/parameters/nodeID'
        - in: query
          name: clusterID
          description: Identifier of the cluster
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully returned the node
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeDetail'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    post:
      description: Change status of a node
      tags: [admin]
      security:
        - AdminTokenAuth: []
      parameters:
        - $ref: '#/components/parameters/nodeID'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NodeStatusChange'
      responses:
        '204':
          description: The node status was changed successfully
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /admin/teams/{teamID}/sandboxes/kill:
    post:
      summary: Kill all sandboxes for a team
      description: Kills all sandboxes for the specified team
      tags: [admin]
      security:
        - AdminTokenAuth: []
      parameters:
        - name: teamID
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Team ID
      responses:
        '200':
          description: Successfully killed sandboxes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminSandboxKillResult'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /admin/teams/{teamID}/builds/cancel:
    post:
      summary: Cancel all builds for a team
      description: Cancels all in-progress and pending builds for the specified team
      tags: [admin]
      security:
        - AdminTokenAuth: []
      parameters:
        - name: teamID
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Team ID
      responses:
        '200':
          description: Successfully cancelled builds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminBuildCancelResult'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /access-tokens:
    post:
      description: Create a new access token
      tags: [access-tokens]
      security:
        - Supabase1TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewAccessToken'
      responses:
        '201':
          description: Access token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedAccessToken'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /access-tokens/{accessTokenID}:
    delete:
      description: Delete an access token
      tags: [access-tokens]
      security:
        - Supabase1TokenAuth: []
      parameters:
        - $ref: '#/components/parameters/accessTokenID'
      responses:
        '204':
          description: Access token deleted successfully
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /api-keys:
    get:
      description: List all team API keys
      tags: [api-keys]
      security:
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      responses:
        '200':
          description: Successfully returned all team API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TeamAPIKey'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
    post:
      description: Create a new team API key
      tags: [api-keys]
      security:
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTeamAPIKey'
      responses:
        '201':
          description: Team API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedTeamAPIKey'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /api-keys/{apiKeyID}:
    patch:
      description: Update a team API key
      tags: [api-keys]
      security:
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/apiKeyID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamAPIKey'
      responses:
        '200':
          description: Team API key updated successfully
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    delete:
      description: Delete a team API key
      tags: [api-keys]
      security:
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/apiKeyID'
      responses:
        '204':
          description: Team API key deleted successfully
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

  /volumes:
    get:
      description: List all team volumes
      tags: [volumes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      responses:
        '200':
          description: Successfully listed all team volumes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Volume'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

    post:
      description: Create a new team volume
      tags: [volumes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewVolume'
      responses:
        '201':
          description: Successfully created a new team volume
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeAndToken'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'

  /volumes/{volumeID}:
    get:
      description: Get team volume info
      tags: [volumes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/volumeID'
      responses:
        '200':
          description: Successfully retrieved a team volume
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeAndToken'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'

    delete:
      description: Delete a team volume
      tags: [volumes]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: '#/components/parameters/volumeID'
      responses:
        '204':
          description: Successfully deleted a team volume
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'