Daytona Runners API

openapi: 3.2.0
info:
  contact:
    email: support@daytona.com
    name: Daytona Platforms Inc.
    url: https://www.daytona.io
  description: Daytona AI platform API Docs
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  title: Daytona Runners API
  version: '1.0'
servers:
- url: http://localhost:3000
tags:
- name: Runners
paths:
  /runners:
    get:
      operationId: listRunners
      parameters:
      - description: Filter runners by region ID
        explode: true
        in: query
        name: regionId
        required: false
        schema:
          type: string
        style: form
      - description: Use with JWT to specify the organization ID
        explode: false
        in: header
        name: X-Daytona-Organization-ID
        required: false
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Runner'
                type: array
          description: ''
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: List all runners
      tags:
      - Runners
    post:
      operationId: createRunner
      parameters:
      - description: Use with JWT to specify the organization ID
        explode: false
        in: header
        name: X-Daytona-Organization-ID
        required: false
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunner'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRunnerResponse'
          description: ''
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Create runner
      tags:
      - Runners
  /runners/me:
    get:
      operationId: getInfoForAuthenticatedRunner
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnerFull'
          description: Runner info
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Get info for authenticated runner
      tags:
      - Runners
  /runners/me/snapshots:
    get:
      operationId: getSnapshotRefsForAuthenticatedRunner
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
          description: Snapshot refs the runner is expected to have
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Get snapshot refs for authenticated runner
      tags:
      - Runners
  /runners/by-sandbox/{sandboxId}:
    get:
      operationId: getRunnerBySandboxId
      parameters:
      - explode: false
        in: path
        name: sandboxId
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnerFull'
          description: ''
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Get runner by sandbox ID
      tags:
      - Runners
  /runners/by-snapshot-ref:
    get:
      operationId: getRunnersBySnapshotRef
      parameters:
      - description: Snapshot ref
        explode: true
        in: query
        name: ref
        required: true
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RunnerSnapshotDto'
                type: array
          description: ''
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Get runners by snapshot ref
      tags:
      - Runners
  /runners/{id}:
    delete:
      operationId: deleteRunner
      parameters:
      - description: Runner ID
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      - description: Delete the runner without waiting for sandboxes already marked for destruction. Requires the runner to have stopped reporting as ready.
        explode: true
        in: query
        name: force
        required: false
        schema:
          type: boolean
        style: form
      - description: Use with JWT to specify the organization ID
        explode: false
        in: header
        name: X-Daytona-Organization-ID
        required: false
        schema:
          type: string
        style: simple
      responses:
        '204':
          description: ''
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Delete runner
      tags:
      - Runners
    get:
      operationId: getRunnerById
      parameters:
      - description: Runner ID
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      - description: Use with JWT to specify the organization ID
        explode: false
        in: header
        name: X-Daytona-Organization-ID
        required: false
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Runner'
          description: ''
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Get runner by ID
      tags:
      - Runners
  /runners/{id}/full:
    get:
      operationId: getRunnerFullById
      parameters:
      - description: Runner ID
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnerFull'
          description: ''
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Get runner by ID
      tags:
      - Runners
  /runners/{id}/scheduling:
    patch:
      operationId: updateRunnerScheduling
      parameters:
      - description: Runner ID
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      - description: Use with JWT to specify the organization ID
        explode: false
        in: header
        name: X-Daytona-Organization-ID
        required: false
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Runner'
          description: ''
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Update runner scheduling status
      tags:
      - Runners
  /runners/{id}/draining:
    patch:
      operationId: updateRunnerDraining
      parameters:
      - description: Runner ID
        explode: false
        in: path
        name: id
        required: true
        schema:
          type: string
        style: simple
      - description: Use with JWT to specify the organization ID
        explode: false
        in: header
        name: X-Daytona-Organization-ID
        required: false
        schema:
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Runner'
          description: ''
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Update runner draining status
      tags:
      - Runners
  /runners/healthcheck:
    post:
      description: Endpoint for version 2 runners to send healthcheck and metrics. Updates lastChecked timestamp and runner metrics.
      operationId: runnerHealthcheck
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunnerHealthcheck'
        required: true
      responses:
        '200':
          description: Healthcheck received
      security:
      - bearer: []
      - oauth2:
        - openid
        - profile
        - email
      summary: Runner healthcheck
      tags:
      - Runners
components:
  schemas:
    CreateRunnerSandboxClass:
      description: The sandbox class supported by the runner. Defaults to container when omitted or null.
      enum:
      - container
      - linux-vm
      - windows
      - null
      type:
      - string
      - 'null'
    RunnerClass:
      description: The class of the runner. Deprecated and always returns "container" for backward compatibility - use sandboxClass instead.
      enum:
      - container
      type: string
    CreateRunner:
      example:
        regionId: regionId
        name: name
        tags:
        - gpu
        - us-east
        sandboxClass: container
      properties:
        regionId:
          type: string
        name:
          type: string
        tags:
          description: Tags to associate with the runner
          example:
          - gpu
          - us-east
          items:
            type: string
          type: array
        sandboxClass:
          allOf:
          - $ref: '#/components/schemas/CreateRunnerSandboxClass'
          default: container
          description: The sandbox class supported by the runner. Defaults to container when omitted or null.
          example: container
      required:
      - name
      - regionId
      type: object
    CreateRunnerResponse:
      example:
        apiKey: dtn_1234567890
        id: runner123
      properties:
        id:
          description: The ID of the runner
          example: runner123
          type: string
        apiKey:
          description: The API key for the runner
          example: dtn_1234567890
          type: string
      required:
      - apiKey
      - id
      type: object
    RunnerFull:
      example:
        currentStartedSandboxes: 5
        appVersion: v0.0.0-dev
        memory: 16
        currentMemoryUsagePercentage: 68.2
        apiKey: dtn_1234567890
        availabilityScore: 85
        currentDiskUsagePercentage: 33.8
        currentCpuUsagePercentage: 45.6
        createdAt: '2023-10-01T12:00:00.000Z'
        apiVersion: '0'
        apiUrl: https://api.runner1.example.com
        regionType: shared
        id: runner123
        state: initializing
        unschedulable: false
        currentAllocatedDiskGiB: 50000
        class: small
        currentAllocatedMemoryGiB: 8000
        gpuType: gpuType
        sandboxClass: linux-vm
        currentAllocatedCpu: 4000
        updatedAt: '2023-10-01T12:00:00.000Z'
        proxyUrl: https://proxy.runner1.example.com
        cpu: 8
        gpu: 1
        currentSnapshotCount: 12
        version: '0'
        tags:
        - gpu
        - us-east
        disk: 100
        domain: runner1.example.com
        name: runner1
        runnerClass: container
        region: us
        lastChecked: '2024-10-01T12:00:00.000Z'
      properties:
        id:
          description: The ID of the runner
          example: runner123
          type: string
        domain:
          description: The domain of the runner
          example: runner1.example.com
          type: string
        apiUrl:
          description: The API URL of the runner
          example: https://api.runner1.example.com
          type: string
        proxyUrl:
          description: The proxy URL of the runner
          example: https://proxy.runner1.example.com
          type: string
        cpu:
          description: The CPU capacity of the runner
          example: 8
          type: number
        memory:
          description: The memory capacity of the runner in GiB
          example: 16
          type: number
        disk:
          description: The disk capacity of the runner in GiB
          example: 100
          type: number
        gpu:
          description: The GPU capacity of the runner
          example: 1
          type: number
        gpuType:
          description: The type of GPU
          type: string
        sandboxClass:
          allOf:
          - $ref: '#/components/schemas/SandboxClass'
          description: The sandbox class supported by this runner
          example: linux-vm
        currentCpuUsagePercentage:
          description: Current CPU usage percentage
          example: 45.6
          type: number
        currentMemoryUsagePercentage:
          description: Current RAM usage percentage
          example: 68.2
          type: number
        currentDiskUsagePercentage:
          description: Current disk usage percentage
          example: 33.8
          type: number
        currentAllocatedCpu:
          description: Current allocated CPU
          example: 4000
          type: number
        currentAllocatedMemoryGiB:
          description: Current allocated memory in GiB
          example: 8000
          type: number
        currentAllocatedDiskGiB:
          description: Current allocated disk in GiB
          example: 50000
          type: number
        currentSnapshotCount:
          description: Current snapshot count
          example: 12
          type: number
        currentStartedSandboxes:
          description: Current number of started sandboxes
          example: 5
          type: number
        availabilityScore:
          description: Runner availability score
          example: 85
          type: number
        region:
          description: The region of the runner
          example: us
          type: string
        name:
          description: The name of the runner
          example: runner1
          type: string
        state:
          allOf:
          - $ref: '#/components/schemas/RunnerState'
          description: The state of the runner
          example: initializing
        lastChecked:
          description: The last time the runner was checked
          example: '2024-10-01T12:00:00.000Z'
          type: string
        unschedulable:
          description: Whether the runner is unschedulable
          example: false
          type: boolean
        tags:
          description: Tags associated with the runner
          example:
          - gpu
          - us-east
          items:
            type: string
          type: array
        createdAt:
          description: The creation timestamp of the runner
          example: '2023-10-01T12:00:00.000Z'
          type: string
        updatedAt:
          description: The last update timestamp of the runner
          example: '2023-10-01T12:00:00.000Z'
          type: string
        version:
          deprecated: true
          description: The version of the runner (deprecated in favor of apiVersion)
          example: '0'
          type: string
        apiVersion:
          deprecated: true
          description: The api version of the runner
          example: '0'
          type: string
        runnerClass:
          allOf:
          - $ref: '#/components/schemas/RunnerClass'
          deprecated: true
          description: The class of the runner. Deprecated and always returns "container" for backward compatibility - use sandboxClass instead.
          example: container
        appVersion:
          deprecated: true
          description: The app version of the runner
          example: v0.0.0-dev
          type: string
        class:
          deprecated: true
          description: Deprecated runner class property
          example: small
          type: string
        apiKey:
          description: The API key for the runner
          example: dtn_1234567890
          type: string
        regionType:
          allOf:
          - $ref: '#/components/schemas/RegionType'
          description: The region type of the runner
          example: shared
      required:
      - apiKey
      - apiVersion
      - cpu
      - createdAt
      - disk
      - id
      - memory
      - name
      - region
      - runnerClass
      - state
      - tags
      - unschedulable
      - updatedAt
      - version
      type: object
    RunnerHealthcheck:
      example:
        appVersion: v0.0.0-dev
        apiUrl: http://api.daytona.example.com:8080
        proxyUrl: http://proxy.daytona.example.com:8080
        domain: runner-123.daytona.example.com
        serviceHealth:
        - healthy: false
          errorReason: Cannot connect to the runner
          serviceName: runner
        - healthy: false
          errorReason: Cannot connect to the runner
          serviceName: runner
        metrics: ''
      properties:
        metrics:
          allOf:
          - $ref: '#/components/schemas/RunnerHealthMetrics'
          description: Runner metrics
        serviceHealth:
          description: Health status of individual services on the runner
          items:
            $ref: '#/components/schemas/RunnerServiceHealth'
          type: array
        domain:
          description: Runner domain
          example: runner-123.daytona.example.com
          type: string
        proxyUrl:
          description: Runner proxy URL
          example: http://proxy.daytona.example.com:8080
          type: string
        apiUrl:
          description: Runner API URL
          example: http://api.daytona.example.com:8080
          type: string
        appVersion:
          description: Runner app version
          example: v0.0.0-dev
          type: string
      required:
      - appVersion
      type: object
    Runner:
      example:
        currentStartedSandboxes: 5
        appVersion: v0.0.0-dev
        memory: 16
        currentMemoryUsagePercentage: 68.2
        availabilityScore: 85
        currentDiskUsagePercentage: 33.8
        currentCpuUsagePercentage: 45.6
        createdAt: '2023-10-01T12:00:00.000Z'
        apiVersion: '0'
        apiUrl: https://api.runner1.example.com
        id: runner123
        state: initializing
        unschedulable: false
        currentAllocatedDiskGiB: 50000
        class: small
        currentAllocatedMemoryGiB: 8000
        gpuType: gpuType
        sandboxClass: linux-vm
        currentAllocatedCpu: 4000
        updatedAt: '2023-10-01T12:00:00.000Z'
        proxyUrl: https://proxy.runner1.example.com
        cpu: 8
        gpu: 1
        currentSnapshotCount: 12
        version: '0'
        tags:
        - gpu
        - us-east
        disk: 100
        domain: runner1.example.com
        name: runner1
        runnerClass: container
        region: us
        lastChecked: '2024-10-01T12:00:00.000Z'
      properties:
        id:
          description: The ID of the runner
          example: runner123
          type: string
        domain:
          description: The domain of the runner
          example: runner1.example.com
          type: string
        apiUrl:
          description: The API URL of the runner
          example: https://api.runner1.example.com
          type: string
        proxyUrl:
          description: The proxy URL of the runner
          example: https://proxy.runner1.example.com
          type: string
        cpu:
          description: The CPU capacity of the runner
          example: 8
          type: number
        memory:
          description: The memory capacity of the runner in GiB
          example: 16
          type: number
        disk:
          description: The disk capacity of the runner in GiB
          example: 100
          type: number
        gpu:
          description: The GPU capacity of the runner
          example: 1
          type: number
        gpuType:
          description: The type of GPU
          type: string
        sandboxClass:
          allOf:
          - $ref: '#/components/schemas/SandboxClass'
          description: The sandbox class supported by this runner
          example: linux-vm
        currentCpuUsagePercentage:
          description: Current CPU usage percentage
          example: 45.6
          type: number
        currentMemoryUsagePercentage:
          description: Current RAM usage percentage
          example: 68.2
          type: number
        currentDiskUsagePercentage:
          description: Current disk usage percentage
          example: 33.8
          type: number
        currentAllocatedCpu:
          description: Current allocated CPU
          example: 4000
          type: number
        currentAllocatedMemoryGiB:
          description: Current allocated memory in GiB
          example: 8000
          type: number
        currentAllocatedDiskGiB:
          description: Current allocated disk in GiB
          example: 50000
          type: number
        currentSnapshotCount:
          description: Current snapshot count
          example: 12
          type: number
        currentStartedSandboxes:
          description: Current number of started sandboxes
          example: 5
          type: number
        availabilityScore:
          description: Runner availability score
          example: 85
          type: number
        region:
          description: The region of the runner
          example: us
          type: string
        name:
          description: The name of the runner
          example: runner1
          type: string
        state:
          allOf:
          - $ref: '#/components/schemas/RunnerState'
          description: The state of the runner
          example: initializing
        lastChecked:
          description: The last time the runner was checked
          example: '2024-10-01T12:00:00.000Z'
          type: string
        unschedulable:
          description: Whether the runner is unschedulable
          example: false
          type: boolean
        tags:
          description: Tags associated with the runner
          example:
          - gpu
          - us-east
          items:
            type: string
          type: array
        createdAt:
          description: The creation timestamp of the runner
          example: '2023-10-01T12:00:00.000Z'
          type: string
        updatedAt:
          description: The last update timestamp of the runner
          example: '2023-10-01T12:00:00.000Z'
          type: string
        version:
          deprecated: true
          description: The version of the runner (deprecated in favor of apiVersion)
          example: '0'
          type: string
        apiVersion:
          deprecated: true
          description: The api version of the runner
          example: '0'
          type: string
        runnerClass:
          allOf:
          - $ref: '#/components/schemas/RunnerClass'
          deprecated: true
          description: The class of the runner. Deprecated and always returns "container" for backward compatibility - use sandboxClass instead.
          example: container
        appVersion:
          deprecated: true
          description: The app version of the runner
          example: v0.0.0-dev
          type: string
        class:
          deprecated: true
          description: Deprecated runner class property
          example: small
          type: string
      required:
      - apiVersion
      - cpu
      - createdAt
      - disk
      - id
      - memory
      - name
      - region
      - runnerClass
      - state
      - tags
      - unschedulable
      - updatedAt
      - version
      type: object
    RunnerServiceHealth:
      example:
        healthy: false
        errorReason: Cannot connect to the runner
        serviceName: runner
      properties:
        serviceName:
          description: Name of the service being checked
          example: runner
          type: string
        healthy:
          description: Whether the service is healthy
          example: false
          type: boolean
        errorReason:
          description: Error reason if the service is unhealthy
          example: Cannot connect to the runner
          type: string
      required:
      - healthy
      - serviceName
      type: object
    RunnerSnapshotDto:
      example:
        runnerDomain: runner.example.com
        runnerId: 123e4567-e89b-12d3-a456-426614174000
        runnerSnapshotId: 123e4567-e89b-12d3-a456-426614174000
      properties:
        runnerSnapshotId:
          description: Runner snapshot ID
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
        runnerId:
          description: Runner ID
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
        runnerDomain:
          description: Runner domain
          example: runner.example.com
          type: string
      required:
      - runnerId
      - runnerSnapshotId
      type: object
    RunnerHealthMetrics:
      properties:
        currentCpuLoadAverage:
          description: Current CPU load average
          example: 0.98
          type: number
        currentCpuUsagePercentage:
          description: Current CPU usage percentage
          example: 45.5
          type: number
        currentMemoryUsagePercentage:
          description: Current memory usage percentage
          example: 60.2
          type: number
        currentDiskUsagePercentage:
          description: Current disk usage percentage
          example: 35.8
          type: number
        currentAllocatedCpu:
          description: Currently allocated CPU cores
          example: 8
          type: number
        currentAllocatedMemoryGiB:
          description: Currently allocated memory in GiB
          example: 16
          type: number
        currentAllocatedDiskGiB:
          description: Currently allocated disk in GiB
          example: 100
          type: number
        currentSnapshotCount:
          description: Number of snapshots currently stored
          example: 5
          type: number
        currentStartedSandboxes:
          description: Number of started sandboxes
          example: 10
          type: number
        cpu:
          description: Total CPU cores on the runner
          example: 8
          type: number
        memoryGiB:
          description: Total RAM in GiB on the runner
          example: 16
          type: number
        diskGiB:
          description: Total disk space in GiB on the runner
          example: 100
          type: number
        gpu:
          description: Total number of GPUs on the runner
          example: 4
          type: number
        gpuType:
          description: GPU model name
          example: NVIDIA H100 80GB HBM3
          type: string
      required:
      - cpu
      - currentAllocatedCpu
      - currentAllocatedDiskGiB
      - currentAllocatedMemoryGiB
      - currentCpuLoadAverage
      - currentCpuUsagePercentage
      - currentDiskUsagePercentage
      - currentMemoryUsagePercentage
      - currentSnapshotCount
      - currentStartedSandboxes
      - diskGiB
      - memoryGiB
      type: object
    RunnerState:
      description: The state of the runner
      enum:
      - initializing
      - ready
      - disabled
      - decommissioned
      - unresponsive
      type: string
    RegionType:
      description: The type of the region
      enum:
      - shared
      - dedicated
      - custom
      type: string
    SandboxClass:
      enum:
      - linux-vm
      - container
      - windows
      type: string
      x-enum-varnames:
      - LINUX_VM
      - CONTAINER
      - WINDOWS
  securitySchemes:
    bearer:
      bearerFormat: JWT
      description: API Key access
      scheme: bearer
      type: http
    oauth2:
      openIdConnectUrl: http://localhost:3000/.well-known/openid-configuration
      type: openIdConnect
x-provenance:
  method: harvested
  publisher: Daytona
  source: https://www.daytona.io/docs/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)