Nuon queues 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 Queues API
  version: 0.19.1074
servers:
- url: https://api.nuon.co/
tags:
- description: queues
  name: queues
paths:
  /v1/queues:
    get:
      description: List queues with optional filtering by owner
      operationId: ListQueues
      parameters:
      - description: Filter by owner ID
        in: query
        name: owner_id
        schema:
          type: string
      - description: Filter by owner type (e.g., 'app_branches')
        in: query
        name: owner_type
        schema:
          type: string
      - description: Limit results
        in: query
        name: limit
        schema:
          type: integer
          default: 50
      - description: Offset results
        in: query
        name: offset
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/app.Queue'
                type: array
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: List queues
      tags:
      - queues
  /v1/queues/{queue_id}:
    get:
      description: Retrieve a single queue by its ID
      operationId: GetQueue
      parameters:
      - description: Queue ID
        in: path
        name: queue_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app.Queue'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: Get queue by ID
      tags:
      - queues
  /v1/queues/{queue_id}/signals:
    get:
      description: Get a list of signals for a specific queue with optional filtering
      operationId: GetQueueSignals
      parameters:
      - description: Queue ID
        in: path
        name: queue_id
        required: true
        schema:
          type: string
      - description: Filter by owner ID
        in: query
        name: owner_id
        schema:
          type: string
      - description: Filter by owner type (e.g., app_branches)
        in: query
        name: owner_type
        schema:
          type: string
      - description: Filter by status
        in: query
        name: status
        schema:
          type: string
      - description: Filter by signal type
        in: query
        name: type
        schema:
          type: string
      - description: 'Limit results (default: 50)'
        in: query
        name: limit
        schema:
          type: integer
      - description: 'Offset for pagination (default: 0)'
        in: query
        name: offset
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/app.QueueSignal'
                type: array
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: List queue signals
      tags:
      - queues
  /v1/queues/{queue_id}/signals/{signal_id}:
    get:
      description: Get detailed information about a specific queue signal
      operationId: GetQueueSignal
      parameters:
      - description: Queue ID
        in: path
        name: queue_id
        required: true
        schema:
          type: string
      - description: Signal ID
        in: path
        name: signal_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app.QueueSignal'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: Get queue signal details
      tags:
      - queues
  /v1/queues/{queue_id}/signals/{signal_id}/await:
    get:
      description: Blocks until the queue signal finishes or the timeout is reached
      operationId: AwaitQueueSignal
      parameters:
      - description: Queue ID
        in: path
        name: queue_id
        required: true
        schema:
          type: string
      - description: Signal ID
        in: path
        name: signal_id
        required: true
        schema:
          type: string
      - description: Timeout in seconds (default 30, max 120)
        in: query
        name: timeout
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app.QueueSignal'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
        '408':
          description: Request Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: Long-poll for queue signal completion
      tags:
      - queues
  /v1/queues/{queue_id}/signals/{signal_id}/graph:
    get:
      description: Returns a recursive tree of a signal and all its awaited/enqueued child signals.
      operationId: GetQueueSignalGraph
      parameters:
      - description: Queue ID
        in: path
        name: queue_id
        required: true
        schema:
          type: string
      - description: Signal ID
        in: path
        name: signal_id
        required: true
        schema:
          type: string
      - description: Max recursion depth (default 1, max 10)
        in: query
        name: depth
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: Get signal execution graph
      tags:
      - queues
  /v1/queues/{queue_id}/status:
    get:
      description: Get real-time status of a queue including depth and in-flight signals
      operationId: GetQueueStatus
      parameters:
      - description: Queue ID
        in: path
        name: queue_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/queue.StatusResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stderr.ErrResponse'
      security:
      - APIKey: []
      - OrgID: []
      summary: Get live queue status
      tags:
      - queues
components:
  schemas:
    signaldb.WorkflowRef:
      properties:
        id:
          type: string
        namespace:
          type: string
        run_id:
          type: string
      type: object
    app.QueueSignal:
      properties:
        callback:
          $ref: '#/components/schemas/callback.Ref'
        callbacks:
          items:
            $ref: '#/components/schemas/callback.Ref'
          type: array
        created_at:
          type: string
        created_by_id:
          type: string
        emitter_id:
          description: 'Optional: if this signal was emitted by an emitter'
          type: string
        enqueued:
          type: boolean
        execution_count:
          type: integer
        expires_at:
          type: string
        id:
          type: string
        org_id:
          type: string
        owner_id:
          type: string
        owner_type:
          type: string
        queue:
          $ref: '#/components/schemas/app.Queue'
        queue_id:
          type: string
        signal:
          $ref: '#/components/schemas/signaldb.SignalData'
        signal_context:
          $ref: '#/components/schemas/cctx.SignalContext'
        status:
          $ref: '#/components/schemas/app.CompositeStatus'
        type:
          type: string
        updated_at:
          type: string
        workflow:
          $ref: '#/components/schemas/signaldb.WorkflowRef'
      type: object
    app.Queue:
      properties:
        created_at:
          type: string
        created_by_id:
          type: string
        emitters:
          items:
            $ref: '#/components/schemas/app.QueueEmitter'
          type: array
        id:
          type: string
        idle_timeout:
          type: integer
        max_depth:
          type: integer
        max_in_flight:
          type: integer
        metadata:
          additionalProperties:
            type: string
          type: object
        name:
          type: string
        org_id:
          type: string
        owner_id:
          type: string
        owner_type:
          type: string
        queue_signal:
          items:
            $ref: '#/components/schemas/app.QueueSignal'
          type: array
        status_v2:
          $ref: '#/components/schemas/app.CompositeStatus'
        updated_at:
          type: string
        workflow:
          $ref: '#/components/schemas/signaldb.WorkflowRef'
      type: object
    queue.StatusResponse:
      properties:
        inFlight:
          items:
            type: string
          type: array
        inFlightCount:
          type: integer
        paused:
          type: boolean
        queueDepthCount:
          type: integer
        ready:
          type: boolean
        stopped:
          type: boolean
      type: object
    stderr.ErrResponse:
      properties:
        description:
          type: string
        error:
          type: string
        user_error:
          type: boolean
      type: object
    app.QueueEmitter:
      properties:
        created_at:
          type: string
        created_by_id:
          type: string
        cron_schedule:
          description: 'Schedule configuration

            For cron mode: cron expression (e.g., "0 * * * *")'
          type: string
        description:
          type: string
        emit_count:
          type: integer
        fired:
          description: 'For scheduled mode: whether the signal has been fired'
          type: boolean
        id:
          type: string
        jitter_window:
          description: 'For cron mode: spread emitter ticks deterministically across this window

            to avoid thundering-herd when many emitters share a schedule. A hash of the

            emitter ID determines each emitter''s static offset within the window. Zero

            disables jitter (default).'
          type: integer
        last_emitted_at:
          type: string
        mode:
          allOf:
          - $ref: '#/components/schemas/app.QueueEmitterMode'
          description: 'Emitter mode: "cron" for recurring, "scheduled" for one-shot'
        name:
          description: Emitter identity
          type: string
        next_emit_at:
          type: string
        org_id:
          type: string
        queue_id:
          description: 'Many-to-one: each emitter belongs to exactly one queue'
          type: string
        scheduled_at:
          description: 'For scheduled mode: the time to fire the signal'
          type: string
        signal_expires_in:
          description: 'Optional TTL for emitted signals. When set, each emitted signal''s ExpiresAt

            is computed as time.Now().Add(SignalExpiresIn) at emission time.'
          type: integer
        signal_template:
          $ref: '#/components/schemas/signaldb.SignalData'
        signal_type:
          description: Signal template - the signal to emit on each tick
          type: string
        status:
          allOf:
          - $ref: '#/components/schemas/app.CompositeStatus'
          description: Runtime state using shared CompositeStatus
        updated_at:
          type: string
        workflow:
          allOf:
          - $ref: '#/components/schemas/signaldb.WorkflowRef'
          description: Workflow reference for the emitter's cron workflow
      type: object
    cctx.SignalContext:
      properties:
        account_id:
          type: string
        log_stream_id:
          type: string
        org_id:
          type: string
        trace_id:
          type: string
      type: object
    app.Status:
      enum:
      - error
      - pending
      - in-progress
      - checking-plan
      - success
      - not-attempted
      - cancelled
      - retrying
      - discarded
      - user-skipped
      - auto-skipped
      - planning
      - applying
      - queued
      - warning
      - failed-pending-retry
      - generating
      - awaiting-user-run
      - provisioning
      - active
      - outdated
      - expired
      - approved
      - drifted
      - no-drift
      - approval-expired
      - approval-denied
      - approval-retry
      - building
      - deleting
      - noop
      - approval-awaiting
      type: string
      x-enum-varnames:
      - StatusError
      - StatusPending
      - StatusInProgress
      - StatusCheckPlan
      - StatusSuccess
      - StatusNotAttempted
      - StatusCancelled
      - StatusRetrying
      - StatusDiscarded
      - StatusUserSkipped
      - StatusAutoSkipped
      - StatusPlanning
      - StatusApplying
      - StatusQueued
      - StatusWarning
      - StatusFailedPendingRetry
      - InstallStackVersionStatusGenerating
      - InstallStackVersionStatusPendingUser
      - InstallStackVersionStatusProvisioning
      - InstallStackVersionStatusActive
      - InstallStackVersionStatusOutdated
      - InstallStackVersionStatusExpired
      - WorkflowStepApprovalStatusApproved
      - WorkflowStepDrifted
      - WorkflowStepNoDrift
      - WorkflowStepApprovalStatusApprovalExpired
      - WorkflowStepApprovalStatusApprovalDenied
      - WorkflowStepApprovalStatusApprovalRetryPlan
      - StatusBuilding
      - StatusDeleting
      - InstallDeployStatusV2Noop
      - AwaitingApproval
    signaldb.SignalData:
      properties:
        signal: {}
      type: object
    app.QueueEmitterMode:
      enum:
      - cron
      - scheduled
      - fire_once
      type: string
      x-enum-varnames:
      - QueueEmitterModeCron
      - QueueEmitterModeScheduled
      - QueueEmitterModeFireOnce
    app.CompositeStatus:
      properties:
        created_at_ts:
          type: integer
        created_by_id:
          type: string
        history:
          items:
            $ref: '#/components/schemas/app.CompositeStatus'
          type: array
        metadata:
          additionalProperties: {}
          type: object
        status:
          $ref: '#/components/schemas/app.Status'
        status_human_description:
          type: string
      type: object
    callback.Ref:
      properties:
        namespace:
          type: string
        signal_name:
          type: string
        workflow_id:
          type: string
      type: object
  securitySchemes:
    APIKey:
      description: Type "Bearer" followed by a space and token.
      in: header
      name: Authorization
      type: apiKey
    OrgID:
      description: Nuon org ID
      in: header
      name: X-Nuon-Org-ID
      type: apiKey