OpenAPI Specification
swagger: '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
host: api.nuon.co
basePath: /
schemes:
- https
tags:
- description: runners
name: runners
paths:
/v1/log-streams/{log_stream_id}:
get:
consumes:
- application/json
description: 'Return a log stream.
'
operationId: GetLogStream
parameters:
- description: log stream ID
in: path
name: log_stream_id
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/app.LogStream'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get a log stream
tags:
- runners
/v1/log-streams/{log_stream_id}/logs:
get:
consumes:
- application/json
description: 'Read OTEL formatted logs for a log stream.
'
operationId: LogStreamReadLogs
parameters:
- description: log stream ID
in: path
name: log_stream_id
required: true
type: string
- description: log stream offset
in: header
name: X-Nuon-API-Offset
type: string
- default: asc
description: sort direction
in: query
name: order
type: string
- collectionFormat: csv
description: filter by service_name (repeatable)
in: query
items:
type: string
name: service_name
type: array
- collectionFormat: csv
description: filter by scope_name (repeatable)
in: query
items:
type: string
name: scope_name
type: array
- collectionFormat: csv
description: filter by severity_text (repeatable)
in: query
items:
type: string
name: severity_text
type: array
- description: filter by log_attributes['nuon.tool']
in: query
name: tool
type: string
- description: filter by log_attributes['helm.release_name']
in: query
name: helm_release_name
type: string
- description: filter by log_attributes['helm.operation']
in: query
name: helm_operation
type: string
- description: filter by log_attributes['tf.workspace_id']
in: query
name: tf_workspace_id
type: string
- description: filter by log_attributes['tf.operation']
in: query
name: tf_operation
type: string
- description: filter by log_attributes['k8s.kind']
in: query
name: k8s_kind
type: string
- description: filter by log_attributes['k8s.namespace']
in: query
name: k8s_namespace
type: string
- description: filter by log_attributes['k8s.name']
in: query
name: k8s_name
type: string
- description: filter by exact trace_id (dedicated CH column)
in: query
name: trace_id
type: string
- description: filter by exact span_id (dedicated CH column)
in: query
name: span_id
type: string
- description: case-insensitive substring filter on log body
in: query
name: q
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
items:
$ref: '#/definitions/app.OtelLogRecord'
type: array
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: read a log stream's logs
tags:
- runners
/v1/log-streams/{log_stream_id}/logs/tail:
get:
consumes:
- application/json
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
type: string
- description: composite cursor in the form `<unix_nano>:<id>`; empty starts from the oldest row
in: query
name: since
type: string
- description: max wait for new rows (Go duration, capped server-side at 30s)
in: query
name: wait
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/service.LogStreamTailLogsResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: long-poll tail a log stream
tags:
- runners
/v1/log-streams/{log_stream_id}/spans:
get:
consumes:
- application/json
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
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
items:
$ref: '#/definitions/service.LogStreamSpan'
type: array
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: read a log stream's trace spans
tags:
- runners
/v1/runner-jobs:
get:
consumes:
- application/json
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
type: string
- description: job groups
in: query
name: groups
type: string
- description: job status
in: query
name: status
type: string
- description: job statuses
in: query
name: statuses
type: string
- description: job executor (must be control-plane)
in: query
name: executor
required: true
type: string
- default: 0
description: offset of jobs to return
in: query
name: offset
type: integer
- default: 10
description: limit of jobs to return
in: query
name: limit
type: integer
- default: 0
description: page number of results to return
in: query
name: page
type: integer
produces:
- application/json
responses:
'200':
description: OK
schema:
items:
$ref: '#/definitions/app.RunnerJob'
type: array
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: list org runner jobs
tags:
- runners
/v1/runner-jobs/{runner_job_id}:
get:
consumes:
- application/json
deprecated: true
description: 'Return a runner job.
'
operationId: GetRunnerJob
parameters:
- description: runner job ID
in: path
name: runner_job_id
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/app.RunnerJob'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get runner job
tags:
- runners
/v1/runner-jobs/{runner_job_id}/cancel:
post:
consumes:
- application/json
description: 'Cancel a runner job.
'
operationId: CancelRunnerJob
parameters:
- description: Input
in: body
name: req
required: true
schema:
$ref: '#/definitions/service.CancelRunnerJobRequest'
- description: runner job ID
in: path
name: runner_job_id
required: true
type: string
produces:
- application/json
responses:
'202':
description: Accepted
schema:
$ref: '#/definitions/app.RunnerJob'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: cancel runner job
tags:
- runners
/v1/runner-jobs/{runner_job_id}/composite-plan:
get:
consumes:
- application/json
description: 'Return a plan for a runner job.
'
operationId: GetRunnerJobCompositePlan
parameters:
- description: runner job ID
in: path
name: runner_job_id
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/plantypes.CompositePlan'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get runner job composite plan
tags:
- runners
/v1/runner-jobs/{runner_job_id}/plan:
get:
consumes:
- application/json
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
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
type: string
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get runner job plan
tags:
- runners
/v1/runners/terraform-workspace/{workspace_id}/state-json:
get:
consumes:
- application/json
deprecated: true
description: 'Returns terraform states in JSON format.
'
operationId: GetTerraformWorkspaceStatesJSON
parameters:
- description: workspace ID
in: path
name: workspace_id
required: true
type: string
- default: 0
description: offset of results to return
in: query
name: offset
type: integer
- default: 10
description: limit of results to return
in: query
name: limit
type: integer
- default: 0
description: page number of results to return
in: query
name: page
type: integer
produces:
- application/json
responses:
'200':
description: OK
schema:
items:
$ref: '#/definitions/app.TerraformWorkspaceStateJSON'
type: array
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get terraform states json
tags:
- runners
/v1/runners/terraform-workspace/{workspace_id}/state-json/{state_id}:
get:
consumes:
- application/json
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
type: string
- description: terraform state ID
in: path
name: state_id
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
type: object
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/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:
consumes:
- application/json
deprecated: true
description: 'Returns terraform state resources in JSON format.
'
operationId: GetTerraformWorkspaceStateJSONResources
parameters:
- description: workspace ID
in: path
name: workspace_id
required: true
type: string
- description: state ID
in: path
name: state_id
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema: {}
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/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:
consumes:
- application/json
deprecated: true
description: 'Returns terraform states for an install.
'
operationId: GetTerraformStates
parameters:
- description: workspace ID
in: path
name: workspace_id
required: true
type: string
- default: 0
description: offset of results to return
in: query
name: offset
type: integer
- default: 10
description: limit of results to return
in: query
name: limit
type: integer
- default: 0
description: page number of results to return
in: query
name: page
type: integer
produces:
- application/json
responses:
'200':
description: OK
schema:
items:
$ref: '#/definitions/app.TerraformWorkspaceState'
type: array
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get terraform states
tags:
- runners
/v1/runners/terraform-workspace/{workspace_id}/states/{state_id}:
get:
consumes:
- application/json
deprecated: true
description: 'Return a terraform state by id.
'
operationId: GetTerraformWorkspaceStateByID
parameters:
- description: workspace ID
in: path
name: workspace_id
required: true
type: string
- description: state ID
in: path
name: state_id
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/app.TerraformWorkspaceState'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get terraform state by ID
tags:
- runners
/v1/runners/terraform-workspace/{workspace_id}/states/{state_id}/resources:
get:
consumes:
- application/json
description: 'Returns resources within a terraform state.
'
operationId: GetTerraformWorkspaceStateResources
parameters:
- description: workspace ID
in: path
name: workspace_id
required: true
type: string
- description: state ID
in: path
name: state_id
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
items:
$ref: '#/definitions/app.TerraformStateResource'
type: array
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get terraform state resources
tags:
- runners
/v1/runners/{runner_id}/card-details:
get:
consumes:
- application/json
description: 'Returns runner card details for monitoring and status.
'
operationId: GetRunnerCardDetails
parameters:
- description: runner ID
in: path
name: runner_id
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/service.RunnerCardDetailsResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get runner card details
tags:
- runners
/v1/runners/{runner_id}/connected:
get:
consumes:
- application/json
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
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/service.RunnerConnectionStatus'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get a runner connection satus based on heartbeat
tags:
- runners
/v1/runners/{runner_id}/force-shutdown:
post:
consumes:
- application/json
deprecated: true
description: 'Force shutdown a runner.
This will result in jobs being lost/cancelled if they are in-flight.
'
operationId: ForceShutDownRunner
parameters:
- description: runner ID
in: path
name: runner_id
required: true
type: string
- description: Input
in: body
name: req
required: true
schema:
$ref: '#/definitions/service.ForceShutdownRequest'
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/app.EmptyResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: force shut down a runner
tags:
- runners
/v1/runners/{runner_id}/graceful-shutdown:
post:
consumes:
- application/json
description: 'Gracefully shut down a runner.
_NOTE_ when a runner is unhealthy, the runner will not be able to pick up this job, so use force shut down instead.
'
operationId: GracefulShutDownRunner
parameters:
- description: runner ID
in: path
name: runner_id
required: true
type: string
- description: Input
in: body
name: req
required: true
schema:
$ref: '#/definitions/service.GracefulShutdownRequest'
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/app.EmptyResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: shut down a runner
tags:
- runners
/v1/runners/{runner_id}/heart-beats/latest:
get:
consumes:
- application/json
description: '
'
operationId: GetLatestRunnerHeartBeat
parameters:
- description: runner ID
in: path
name: runner_id
required: true
type: string
produces:
- application/json
responses:
'200':
description: OK
schema:
$ref: '#/definitions/service.LatestRunnerHeartBeats'
'400':
description: Bad Request
schema:
$ref: '#/definitions/stderr.ErrResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/stderr.ErrResponse'
'403':
description: Forbidden
schema:
$ref: '#/definitions/stderr.ErrResponse'
'404':
description: Not Found
schema:
$ref: '#/definitions/stderr.ErrResponse'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/stderr.ErrResponse'
security:
- APIKey: []
- OrgID: []
summary: get a runner
tags:
- runners
/v1/runners/{runner_id}/jobs:
get:
consumes:
- application/json
description: 'Return runner jobs.
'
operationId: GetRunnerJobs
parameters:
- description: job group
in: query
name: group
type: string
- description: job groups
in: query
name: groups
type: string
- description: job status
in: query
name: status
type: string
- description: job statuses
in: query
name: statuses
type: string
- description: job executor
in: query
name: executor
type: string
- description: runner ID
in: path
name: runner_id
required: true
type: string
- default: 0
description: offset of jobs to return
in: query
name: offset
type: integer
- default: 10
description: limit of jobs to return
in: query
name: limit
type: integer
- default: 0
description: page number of results to return
in: query
name: page
type: integer
produces:
- application/json
responses:
# --- truncated at 32 KB (208 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nuon/refs/heads/main/openapi/nuon-runners-api-openapi.yml