Nuon runners API

openapi: 3.2.0
info:
  contact:
    email: support@nuon.co
    name: Nuon Support
  description: API for managing nuon apps, components, installs, and actions.
  title: Nuon accounts Runners API
  version: 0.19.1074
servers:
- url: https://api.nuon.co/
tags:
- description: runners
  name: runners
paths:
  /v1/log-streams/{log_stream_id}:
    get:
      description: 'Return a log stream.

        '
      operationId: GetLogStream
      parameters:
      - description: log stream ID
        in: path
        name: log_stream_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app.LogStream'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get a log stream
      tags:
      - runners
  /v1/log-streams/{log_stream_id}/logs:
    get:
      description: 'Read OTEL formatted logs for a log stream.

        '
      operationId: LogStreamReadLogs
      parameters:
      - description: log stream ID
        in: path
        name: log_stream_id
        required: true
        schema:
          type: string
      - description: log stream offset
        in: header
        name: X-Nuon-API-Offset
        schema:
          type: string
      - description: sort direction
        in: query
        name: order
        schema:
          type: string
          default: asc
      - description: filter by service_name (repeatable)
        in: query
        name: service_name
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: filter by scope_name (repeatable)
        in: query
        name: scope_name
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: filter by severity_text (repeatable)
        in: query
        name: severity_text
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - description: filter by log_attributes['nuon.tool']
        in: query
        name: tool
        schema:
          type: string
      - description: filter by log_attributes['helm.release_name']
        in: query
        name: helm_release_name
        schema:
          type: string
      - description: filter by log_attributes['helm.operation']
        in: query
        name: helm_operation
        schema:
          type: string
      - description: filter by log_attributes['tf.workspace_id']
        in: query
        name: tf_workspace_id
        schema:
          type: string
      - description: filter by log_attributes['tf.operation']
        in: query
        name: tf_operation
        schema:
          type: string
      - description: filter by log_attributes['k8s.kind']
        in: query
        name: k8s_kind
        schema:
          type: string
      - description: filter by log_attributes['k8s.namespace']
        in: query
        name: k8s_namespace
        schema:
          type: string
      - description: filter by log_attributes['k8s.name']
        in: query
        name: k8s_name
        schema:
          type: string
      - description: filter by exact trace_id (dedicated CH column)
        in: query
        name: trace_id
        schema:
          type: string
      - description: filter by exact span_id (dedicated CH column)
        in: query
        name: span_id
        schema:
          type: string
      - description: case-insensitive substring filter on log body
        in: query
        name: q
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/app.OtelLogRecord'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: read a log stream's logs
      tags:
      - runners
  /v1/log-streams/{log_stream_id}/logs/tail:
    get:
      description: Returns rows after the supplied composite cursor, long-polling up to ~30s for new rows on an idle stream. Behind the `log-tail-long-poll` org feature flag.
      operationId: LogStreamTailLogs
      parameters:
      - description: log stream ID
        in: path
        name: log_stream_id
        required: true
        schema:
          type: string
      - description: composite cursor in the form `<unix_nano>:<id>`; empty starts from the oldest row
        in: query
        name: since
        schema:
          type: string
      - description: max wait for new rows (Go duration, capped server-side at 30s)
        in: query
        name: wait
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service.LogStreamTailLogsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: long-poll tail a log stream
      tags:
      - runners
  /v1/log-streams/{log_stream_id}/spans:
    get:
      description: 'Read OTEL trace spans for a log stream.


        Returns the flat list of spans recorded by the runner for the job execution

        (or executions) associated with this log stream, ordered by start timestamp

        ASC. The frontend assembles the tree from `parent_span_id`.

        '
      operationId: LogStreamReadSpans
      parameters:
      - description: log stream ID
        in: path
        name: log_stream_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/service.LogStreamSpan'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: read a log stream's trace spans
      tags:
      - runners
  /v1/runner-jobs:
    get:
      description: list runner jobs for the current org that ran on the control plane. Used by orgs that build on the control plane and therefore have no org runner.
      operationId: ListRunnerJobs
      parameters:
      - description: job group
        in: query
        name: group
        schema:
          type: string
      - description: job groups
        in: query
        name: groups
        schema:
          type: string
      - description: job status
        in: query
        name: status
        schema:
          type: string
      - description: job statuses
        in: query
        name: statuses
        schema:
          type: string
      - description: job executor (must be control-plane)
        in: query
        name: executor
        required: true
        schema:
          type: string
      - description: offset of jobs to return
        in: query
        name: offset
        schema:
          type: integer
          default: 0
      - description: limit of jobs to return
        in: query
        name: limit
        schema:
          type: integer
          default: 10
      - description: page number of results to return
        in: query
        name: page
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/app.RunnerJob'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: list org runner jobs
      tags:
      - runners
  /v1/runner-jobs/{runner_job_id}:
    get:
      deprecated: true
      description: 'Return a runner job.

        '
      operationId: GetRunnerJob
      parameters:
      - description: runner job ID
        in: path
        name: runner_job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app.RunnerJob'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get runner job
      tags:
      - runners
  /v1/runner-jobs/{runner_job_id}/cancel:
    post:
      description: 'Cancel a runner job.

        '
      operationId: CancelRunnerJob
      parameters:
      - description: runner job ID
        in: path
        name: runner_job_id
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app.RunnerJob'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: cancel runner job
      tags:
      - runners
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/service.CancelRunnerJobRequest'
        description: Input
        required: true
  /v1/runner-jobs/{runner_job_id}/composite-plan:
    get:
      description: 'Return a plan for a runner job.

        '
      operationId: GetRunnerJobCompositePlan
      parameters:
      - description: runner job ID
        in: path
        name: runner_job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plantypes.CompositePlan'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get runner job composite plan
      tags:
      - runners
  /v1/runner-jobs/{runner_job_id}/plan:
    get:
      deprecated: true
      description: 'Return a plan for a runner job.

        '
      operationId: GetRunnerJobPlan
      parameters:
      - description: runner job ID
        in: path
        name: runner_job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get runner job plan
      tags:
      - runners
  /v1/runners/terraform-workspace/{workspace_id}/state-json:
    get:
      deprecated: true
      description: 'Returns terraform states in JSON format.

        '
      operationId: GetTerraformWorkspaceStatesJSON
      parameters:
      - description: workspace ID
        in: path
        name: workspace_id
        required: true
        schema:
          type: string
      - description: offset of results to return
        in: query
        name: offset
        schema:
          type: integer
          default: 0
      - description: limit of results to return
        in: query
        name: limit
        schema:
          type: integer
          default: 10
      - description: page number of results to return
        in: query
        name: page
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/app.TerraformWorkspaceStateJSON'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get terraform states json
      tags:
      - runners
  /v1/runners/terraform-workspace/{workspace_id}/state-json/{state_id}:
    get:
      deprecated: true
      description: 'Return a terraform state in JSON format by id.

        '
      operationId: GetTerraformWorkspaceStatesJSONByID
      parameters:
      - description: workspace ID
        in: path
        name: workspace_id
        required: true
        schema:
          type: string
      - description: terraform state ID
        in: path
        name: state_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get terraform state json by id. This output is same as "terraform show --json"
      tags:
      - runners
  /v1/runners/terraform-workspace/{workspace_id}/state-json/{state_id}/resources:
    get:
      deprecated: true
      description: 'Returns terraform state resources in JSON format.

        '
      operationId: GetTerraformWorkspaceStateJSONResources
      parameters:
      - description: workspace ID
        in: path
        name: workspace_id
        required: true
        schema:
          type: string
      - description: state ID
        in: path
        name: state_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get terraform state resources. This output is similar to "terraform state list"
      tags:
      - runners
  /v1/runners/terraform-workspace/{workspace_id}/states:
    get:
      deprecated: true
      description: 'Returns terraform states for an install.

        '
      operationId: GetTerraformStates
      parameters:
      - description: workspace ID
        in: path
        name: workspace_id
        required: true
        schema:
          type: string
      - description: offset of results to return
        in: query
        name: offset
        schema:
          type: integer
          default: 0
      - description: limit of results to return
        in: query
        name: limit
        schema:
          type: integer
          default: 10
      - description: page number of results to return
        in: query
        name: page
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/app.TerraformWorkspaceState'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get terraform states
      tags:
      - runners
  /v1/runners/terraform-workspace/{workspace_id}/states/{state_id}:
    get:
      deprecated: true
      description: 'Return a terraform state by id.

        '
      operationId: GetTerraformWorkspaceStateByID
      parameters:
      - description: workspace ID
        in: path
        name: workspace_id
        required: true
        schema:
          type: string
      - description: state ID
        in: path
        name: state_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app.TerraformWorkspaceState'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get terraform state by ID
      tags:
      - runners
  /v1/runners/terraform-workspace/{workspace_id}/states/{state_id}/resources:
    get:
      description: 'Returns resources within a terraform state.

        '
      operationId: GetTerraformWorkspaceStateResources
      parameters:
      - description: workspace ID
        in: path
        name: workspace_id
        required: true
        schema:
          type: string
      - description: state ID
        in: path
        name: state_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/app.TerraformStateResource'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get terraform state resources
      tags:
      - runners
  /v1/runners/{runner_id}/card-details:
    get:
      description: 'Returns runner card details for monitoring and status.

        '
      operationId: GetRunnerCardDetails
      parameters:
      - description: runner ID
        in: path
        name: runner_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service.RunnerCardDetailsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: get runner card details
      tags:
      - runners
  /v1/runners/{runner_id}/connected:
    get:
      description: '# get runner connect status


        The connected status is based on runner heartbeat:


        if no heart beat found — false

        if heart beat > 15 seconds ago — false, hb timestamp

        if the heart beat < 15 seconds ago — true'
      operationId: GetRunnerConnectStatus
      parameters:
      - description: runner ID
        in: path
        name: runner_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service.RunnerConnectionStatus'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'


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