openapi.yaml

openapi: 3.1.0
info:
  title: Sideplane REST API
  version: 0.1.0
  summary: Control-plane API for self-hosted Sideplane agent fleets.
  description: >
    Sideplane exposes a compact REST API for operator workflows and sidecar
    polling. Sidecars initiate outbound enrollment, heartbeat, job claim, and
    job-result requests. Operator mutating endpoints require an operator bearer
    token when configured. Node endpoints require node bearer credentials.
servers:
  - url: http://localhost:8080
    description: Local development server
tags:
  - name: Health
  - name: Metrics
  - name: Events
  - name: Operator
  - name: Sidecar
security: []
paths:
  /healthz:
    get:
      tags: [Health]
      summary: Health check.
      operationId: getHealth
      responses:
        "200":
          description: Server is reachable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
  /readyz:
    get:
      tags: [Health]
      summary: Readiness check.
      operationId: getReady
      responses:
        "200":
          description: Server is ready to serve requests.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
  /metrics:
    get:
      tags: [Metrics]
      summary: Prometheus-compatible metrics.
      operationId: getMetrics
      responses:
        "200":
          description: Prometheus text exposition format.
          content:
            text/plain:
              schema:
                type: string
  /api/events:
    get:
      tags: [Events]
      summary: Stream server-sent fleet events.
      operationId: streamEvents
      description: >
        Streams `node`, `job`, and `rollout` events as `text/event-stream`.
        Clients may authenticate with an operator bearer token or with a
        one-use ticket from `POST /api/events/tickets`.
      security:
        - operatorBearer: []
        - eventTicket: []
      parameters:
        - name: ticket
          in: query
          required: false
          schema:
            type: string
          description: One-use event stream ticket for browser EventSource clients.
      responses:
        "200":
          description: Server-sent event stream.
          content:
            text/event-stream:
              schema:
                type: string
              examples:
                node:
                  value: "event: node\ndata: {\"nodeId\":\"node-a\",\"state\":\"fresh\"}\n\n"
                job:
                  value: "event: job\ndata: {\"jobId\":\"job-a\",\"nodeId\":\"node-a\",\"status\":\"completed\"}\n\n"
                rollout:
                  value: "event: rollout\ndata: {\"rolloutId\":\"rollout-a\",\"state\":\"running\"}\n\n"
        "401":
          $ref: "#/components/responses/APIError"
  /api/events/tickets:
    post:
      tags: [Events]
      summary: Create a one-use SSE ticket.
      operationId: createEventTicket
      security:
        - operatorBearer: []
      responses:
        "201":
          description: Short-lived one-use event stream ticket.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventTicketResponse"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/enrollment-tokens:
    post:
      tags: [Operator]
      summary: Create a one-time enrollment token.
      operationId: createEnrollmentToken
      security:
        - operatorBearer: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEnrollmentTokenRequest"
            example:
              expiresAt: "2026-06-19T12:00:00Z"
      responses:
        "201":
          description: Plaintext enrollment token returned once.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateEnrollmentTokenResponse"
              example:
                token: "enroll_example_token"
                expiresAt: "2026-06-19T12:00:00Z"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/whoami:
    get:
      tags: [Operator]
      summary: Describe the authenticated operator identity.
      description: Returns the acting token scope and name. Never returns a secret.
      operationId: whoami
      security:
        - operatorBearer: []
      responses:
        "200":
          description: Authenticated identity.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WhoamiResponse"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/status:
    get:
      tags: [Operator]
      summary: Cheap control-plane status summary.
      operationId: serverStatus
      security:
        - operatorBearer: []
      responses:
        "200":
          description: Server status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerStatusResponse"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/operator-tokens:
    get:
      tags: [Operator]
      summary: List named operator token metadata.
      operationId: listOperatorTokens
      security:
        - operatorBearer: []
      responses:
        "200":
          description: Operator token metadata. Plaintext tokens are never listed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListOperatorTokensResponse"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
    post:
      tags: [Operator]
      summary: Create a named revocable operator token.
      operationId: createOperatorToken
      security:
        - operatorBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOperatorTokenRequest"
            example:
              name: workstation
      responses:
        "201":
          description: Plaintext operator token returned once.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateOperatorTokenResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/operator-tokens/{tokenId}:
    delete:
      tags: [Operator]
      summary: Revoke a named operator token.
      operationId: revokeOperatorToken
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/TokenId"
      responses:
        "200":
          description: Revoked token metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RevokeOperatorTokenResponse"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/enroll:
    post:
      tags: [Sidecar]
      summary: Exchange an enrollment token for node credentials.
      operationId: enrollNode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnrollNodeRequest"
            example:
              token: "enroll_example_token"
              nodeId: "node-example"
              hostname: "example-host"
              sidecarVersion: "dev"
      responses:
        "200":
          description: Node credential returned once.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnrollNodeResponse"
              example:
                nodeId: "node-example"
                nodeCredential: "node_example_credential"
        "401":
          $ref: "#/components/responses/APIError"
        "409":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/heartbeat:
    post:
      tags: [Sidecar]
      summary: Record sidecar heartbeat and lightweight runtime status.
      operationId: recordHeartbeat
      security:
        - nodeBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HeartbeatRequest"
      responses:
        "200":
          description: Heartbeat accepted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HeartbeatResponse"
        "401":
          $ref: "#/components/responses/APIError"
  /api/nodes:
    get:
      tags: [Operator]
      summary: List freshness-adjusted fleet nodes.
      operationId: listNodes
      security:
        - operatorBearer: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
          description: Maximum number of nodes to return.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of nodes to skip from the stable node ID order.
        - name: selector
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated exact label matches, for example `role=canary,zone=lab`.
      responses:
        "200":
          description: Paginated fleet nodes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListNodesResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
  /api/nodes/{nodeId}:
    delete:
      tags: [Operator]
      summary: Remove a decommissioned node from inventory.
      operationId: deleteNode
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
      responses:
        "204":
          description: Node removed.
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/nodes/{nodeId}/labels:
    get:
      tags: [Operator]
      summary: Get operator-managed node labels.
      operationId: getNodeLabels
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
      responses:
        "200":
          description: Node labels.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NodeLabelsResponse"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
    put:
      tags: [Operator]
      summary: Replace operator-managed node labels.
      operationId: putNodeLabels
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NodeLabelsRequest"
            example:
              labels:
                role: canary
                zone: lab
      responses:
        "200":
          description: Updated node labels.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NodeLabelsResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/nodes/{nodeId}/maintenance:
    put:
      tags: [Operator]
      summary: Set node maintenance mode.
      description: Maintenance nodes are excluded from rollouts and bulk operations by default and have node-offline/drift alerts suppressed.
      operationId: setNodeMaintenance
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NodeMaintenanceRequest"
            example:
              maintenance: true
      responses:
        "200":
          description: Updated maintenance state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NodeMaintenanceResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "403":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/nodes/{nodeId}/backups:
    get:
      tags: [Operator]
      summary: List rollback backup inventory for a node.
      operationId: listNodeBackups
      description: >
        Lists server-known backup references derived from prior config_apply
        job results. Sidecar-local paths are intentionally omitted.
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
      responses:
        "200":
          description: Backup references, newest first.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListRollbackBackupsResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/rollouts:
    get:
      tags: [Operator]
      summary: List staged fleet rollouts.
      operationId: listRollouts
      security:
        - operatorBearer: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: Paginated rollout list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListRolloutsResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
    post:
      tags: [Operator]
      summary: Create a staged fleet rollout.
      operationId: createRollout
      description: >
        Resolves a label selector or explicit node IDs and creates sequential
        config-apply batches. Dry-run rollout jobs are the default. By default,
        creation returns 409 when any resolved node is already part of a
        non-terminal rollout; set spec.allowOverlap to intentionally override.
      security:
        - operatorBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRolloutRequest"
      responses:
        "201":
          description: Rollout created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateRolloutResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "409":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/rollouts/{rolloutId}:
    get:
      tags: [Operator]
      summary: Get one staged fleet rollout.
      operationId: getRollout
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/RolloutId"
      responses:
        "200":
          description: Rollout.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetRolloutResponse"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/rollouts/{rolloutId}/actions:
    post:
      tags: [Operator]
      summary: Pause, resume, or abort a rollout.
      operationId: actOnRollout
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/RolloutId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RolloutActionRequest"
      responses:
        "200":
          description: Updated rollout.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RolloutActionResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/nodes/{nodeId}/jobs:
    get:
      tags: [Operator]
      summary: List jobs for a node.
      operationId: listNodeJobs
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 50
          description: Bounded maximum number of newest-first jobs.
        - name: status
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/JobStatus"
      responses:
        "200":
          description: Node jobs, newest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Job"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
    post:
      tags: [Operator]
      summary: Create an operator job for a node.
      operationId: createNodeJob
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateJobRequest"
            example:
              type: deep_probe
      responses:
        "201":
          description: Job created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "409":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/nodes/{nodeId}/config-apply:
    post:
      tags: [Operator]
      summary: Create a signed config apply job.
      operationId: createConfigApplyJob
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfigApplyRequest"
            example:
              runtimeType: hermes
              profile: default
              dryRun: true
      responses:
        "201":
          description: Config apply job created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "409":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/nodes/{nodeId}/restart:
    post:
      tags: [Operator]
      summary: Create a standalone restart job.
      operationId: createRestartJob
      description: >
        Enqueues a restart job only; the server does not restart local services.
        Requests default to dry-run unless live is true.
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RestartRequest"
            example:
              runtimeType: hermes
              profile: default
              live: false
      responses:
        "201":
          description: Restart job created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "409":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/nodes/{nodeId}/rollback:
    post:
      tags: [Operator]
      summary: Create an explicit rollback job.
      operationId: createRollbackJob
      description: >
        Enqueues a rollback job for a server-known backup reference. The
        operator supplies backupRef only; sidecar-local paths are derived from
        previously reported config_apply results.
      security:
        - operatorBearer: []
      parameters:
        - $ref: "#/components/parameters/NodeId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RollbackRequest"
            example:
              runtimeType: hermes
              backupRef: config_apply:job_example:plan_example
              live: false
      responses:
        "201":
          description: Rollback job created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "409":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/sidecar/config-apply/secrets:
    post:
      tags: [Sidecar]
      summary: Fetch managed provider secrets for a signed config apply plan.
      operationId: fetchConfigApplySecrets
      description: >
        Authenticated sidecars call this just before live config apply. The signed
        plan carries only provider env names; plaintext values are returned only
        over the node-credential channel and are never stored in job payloads.
      security:
        - nodeBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignedConfigPlan"
      responses:
        "200":
          description: Managed provider secret values keyed by environment variable name.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigApplySecretsResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "409":
          $ref: "#/components/responses/APIError"
  /api/sidecar/jobs/next:
    get:
      tags: [Sidecar]
      summary: Claim the next pending job for a node.
      operationId: claimNextJob
      security:
        - nodeBearer: []
      parameters:
        - name: nodeId
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Claimed job.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "204":
          description: No pending jobs.
        "401":
          $ref: "#/components/responses/APIError"
  /api/sidecar/jobs/{jobId}/result:
    post:
      tags: [Sidecar]
      summary: Submit a sidecar job result.
      operationId: submitJobResult
      security:
        - nodeBearer: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobResultRequest"
      responses:
        "200":
          description: Job result accepted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptedResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
  /api/config/desired/history:
    get:
      tags: [Operator]
      summary: List desired config history.
      operationId: listDesiredConfigHistory
      security:
        - operatorBearer: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: Paginated desired config history.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListDesiredConfigHistoryResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/config/desired/revert:
    post:
      tags: [Operator]
      summary: Revert desired config to a history entry.
      operationId: revertDesiredConfig
      security:
        - operatorBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RevertDesiredConfigRequest"
      responses:
        "200":
          description: Reverted desired config and appended history entry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RevertDesiredConfigResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/config/desired:
    get:
      tags: [Operator]
      summary: Get desired layered provider/model configuration.
      operationId: getDesiredConfig
      security:
        - operatorBearer: []
      responses:
        "200":
          description: Desired config.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DesiredConfig"
        "401":
          $ref: "#/components/responses/APIError"
    put:
      tags: [Operator]
      summary: Replace desired layered provider/model configuration.
      operationId: putDesiredConfig
      security:
        - operatorBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DesiredConfig"
      responses:
        "200":
          description: Updated desired config.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DesiredConfig"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/config/providers:
    get:
      tags: [Operator]
      summary: Get desired and actual provider catalog entries.
      operationId: getProviderCatalog
      security:
        - operatorBearer: []
      parameters:
        - name: nodeId
          in: query
          required: false
          schema:
            type: string
        - name: runtimeType
          in: query
          required: false
          schema:
            type: string
        - name: profile
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Desired provider catalog layers, effective catalog for the scope, and latest actual catalog when available.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderCatalogResponse"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
    put:
      tags: [Operator]
      summary: Add or replace one provider definition.
      operationId: upsertProviderDefinition
      security:
        - operatorBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpsertProviderRequest"
      responses:
        "200":
          description: Updated provider catalog.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderCatalogResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "403":
          $ref: "#/components/responses/APIError"
        "409":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
    delete:
      tags: [Operator]
      summary: Delete one provider definition.
      description: >
        Deletes a provider from one desired catalog layer. Known v1 limitation:
        deleting the last provider for a target leaves a stale custom_providers
        block in the runtime config until a later apply path can explicitly
        clear the block; deleting one provider while others remain works.
        Encrypted provider API key storage is keyed by apiKeyEnv and is retained
        when a provider definition is deleted because it may be shared.
      operationId: deleteProviderDefinition
      security:
        - operatorBearer: []
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
        - name: nodeId
          in: query
          required: false
          schema:
            type: string
        - name: runtimeType
          in: query
          required: false
          schema:
            type: string
        - name: profile
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Updated provider catalog.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderCatalogResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "403":
          $ref: "#/components/responses/APIError"
        "404":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/config/effective:
    get:
      tags: [Operator]
      summary: Preview effective config for the persisted desired state.
      operationId: getEffectiveConfig
      security:
        - operatorBearer: []
      parameters:
        - name: nodeId
          in: query
          required: true
          schema:
            type: string
        - name: runtimeType
          in: query
          required: false
          schema:
            type: string
        - name: profile
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Effective config and diff.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EffectiveConfigResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
  /api/config/effective/preview:
    post:
      tags: [Operator]
      summary: Preview effective config with a proposed target override.
      operationId: previewEffectiveConfig
      security:
        - operatorBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EffectiveConfigPreviewRequest"
      responses:
        "200":
          description: Effective config and diff.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EffectiveConfigResponse"
        "400":
          $ref: "#/components/responses/APIError"
        "401":
          $ref: "#/components/responses/APIError"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/audit:
    get:
      tags: [Operator]
      summary: List audit events.
      operationId: listAuditEvents
      security:
        - operatorBearer: []
      parameters:
        - name: nodeId
          in: query
          required: false
          schema:
            type: string
        - name: action
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 100
      responses:
        "200":
          description: Audit events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListAuditEventsResponse"
        "401":
          $ref: "#/components/responses/APIError"
  /api/audit/export:
    get:
      tags: [Operator]
      summary: Export the audit log as ndjson or csv.
      operationId: exportAuditEvents
      parameters:
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [ndjson, csv]
            default: ndjson
        - name: nodeId
          in: query
          required: false
          schema:
            type: string
        - name: action
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Streamed audit log.
          content:
            application/x-ndjson:
              schema:
                type: string
            text/csv:
              schema:
                type: string
  /api/jobs/bulk:
    post:
      tags: [Operator]
      summary: Create one job per matched node.
      operationId: createBulkJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkJobRequest"
      responses:
        "201":
          description: Bulk job creation result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkJobResponse"
        "400":
          $ref: "#/components/responses/APIError"
  /api/nodes/labels:
    put:
      tags: [Operator]
      summary: Apply labels to a node selection.
      operationId: bulkNodeLabels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkNodeLabelsRequest"
      responses:
        "200":
          description: Bulk label assignment result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkNodeLabelsResponse"
        "400":
          $ref: "#/components/responses/APIError"
  /api/webhooks:
    get:
      tags: [Operator]
      summary: List alert webhooks.
      operationId: listAlertWebhooks
      responses:
        "200":
          description: Alert webhooks.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListAlertWebhooksResponse"
    post:
      tags: [Operator]
      summary: Create an alert webhook.
      operationId: createAlertWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAlertWebhookRequest"
      responses:
        "201":
          description: Created alert webhook; signing secret returned once.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateAlertWebhookResponse"
        "400":
          $ref: "#/components/responses/APIError"
  /api/webhooks/{webhookId}:
    delete:
      tags: [Operator]
      summary: Delete an alert webhook.
      operationId: deleteAlertWebhook
      parameters:
        - name: webhookId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted.
        "404":
          $ref: "#/components/responses/APIError"
  /api/settings:
    get:
      tags: [Operator]
      summary: Get operator-tunable server settings.
      operationId: getServerSettings
      responses:
        "200":
          description: Server settings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerSettings"
    put:
      tags: [Operator]
      summary: Update operator-tunable server settings.
      operationId: updateServerSettings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateServerSettingsRequest"
      responses:
        "200":
          description: Updated server settings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerSettings"
        "400":
          $ref: "#/components/responses/APIError"
  /api/rollout-templates:
    get:
      tags: [Operator]
      summary: List rollout templates.
      operationId: listRolloutTemplates
      responses:
        "200":
          description: Rollout templates.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListRolloutTemplatesResponse"
    post:
      tags: [Operator]
      summary: Create a rollout template.
      operationId: createRolloutTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRolloutTemplateRequest"
      responses:
        "201":
          description: Created rollout template.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateRolloutTemplateResponse"
        "400":
          $ref: "#/components/responses/APIError"
  /api/rollout-templates/{templateId}:
    delete:
      tags: [Operator]
      summary: Delete a rollout template.
      operationId: deleteRolloutTemplate
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted.
        "404":
          $ref: "#/components/responses/APIError"
  /api/signing-key:
    get:
      tags: [Sidecar]
      summary: Get the server public signing key.
      operationId: getPublicSigningKey
      responses:
        "200":
          description: Public signing key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicSigningKeyResponse"
        "503":
          $ref: "#/components/responses/APIError"
components:
  securitySchemes:
    operatorBearer:
      type: http
      scheme: bearer
      description: Operator bearer token from `SIDEPLANE_OPERATOR_TOKEN`.
    eventTicket:
      type: apiKey
      in: query
      name: ticket
      description: One-use SSE ticket returned by `POST /api/events/tickets`.
    nodeBearer:
      type: http
      scheme: bearer
      description: Node credential returned by enrollment.
  parameters:
    NodeId:
      name: nodeId
      in: path
      required: true
      schema:
        type: string
    RolloutId:
      name: rolloutId
      in: path
      required: true
      schema:
        type: string
    TokenId:
      name: tokenId
      in: path
      required: true
      schema:
        type: string
  responses:
    APIError:
      description: Structured JSON error response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds until the caller should retry.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
  schemas:
    APIError:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string
    StatusResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
    AcceptedResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [accepted, accepted_late]
    EventTicketResponse:
      type: object
      required: [ticket, expiresAt]
      properties:
        ticket:
          type: string
        expiresAt:
          type: string
          format: date-time
    CreateEnrollmentTokenRequest:
      type: object
      properties:
        expiresAt:
          type: string
          format: date-time
    CreateEnrollmentTokenResponse:
      type: object
      required: [token, expiresAt]
      properties:
        token:
          type: string
        expiresAt:
          type: string
          format: date-time
    OperatorTokenScope:
      type: string
      enum: [admin, readonly]
      description: admin grants full access; readonly allows GET/list endpoints only.
    OperatorToken:
      type: object
      required: [id, name, scope, createdAt]
      properties:
        id:
          type: string
        name:
          type: string
        scope:
          $ref: "#/components/schemas/OperatorTokenScope"
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
        revokedAt:
          type: string
          format: date-time
    CreateOperatorTokenRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        scope:
          $ref: "#/components/schemas/OperatorTokenScope"
    CreateOperatorTokenResponse:
      type: object
      required: [operatorToken, token]
      properties:
        operatorToken:
          $ref: "#/components/schemas/OperatorToken"
        token:
          type: string
          description: Plaintext token returned once.
    ListOperatorTokensResponse:
      type: object
      required: [tokens]
      properties:
        tokens:
          type: array
          items:
            $ref: "#/components/schemas/OperatorToken"
    RevokeOperatorTokenResponse:
      type: object
      required: [operatorToken]
      properties:
        operatorToken:
          $ref: "#/components/schemas/OperatorToken"
    EnrollNodeRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string
        nodeId:
          type: string
        hostname:
          type: string
        sidecarVersion:
          type: string
    EnrollNodeResponse:
      type: object
      required: [nodeId, nodeCredential]
      properties:
        nodeId:
          type: string
        nodeCredential:
          type: string
    NodeState:
      type: string
      enum: [fresh, stale, offline]
    RuntimeStatus:
      type: object
      required: [name]
      properties:
        name:
          type: string
        type:
          type: string
        version:
          type: string
        deploymentMode:
          type: string
          enum: [container, systemd, local]
          description: How the adapter manages the runtime, derived from existing configuration. Empty when the deployment mode is unknown.
        state:
          type: string
        provider:
          type: string
        model:
          type: string
        configHash:
          type: string
        lastError:
          type: string
        warnings:
          type: array
          items:
            type: string
        outdated:
          type: boolean
          description: True only when this runtime reports an actual version and an expected version is configured for its runtime type, and the two differ.
        health:
          $ref: "#/components/schemas/RuntimeHealth"
    RuntimeHealth:
      type: object
      required: [state]
      description: Read-only local liveness result for a runtime. Never contacts external networks or restarts anything.
      properties:
        state:
          type: string
          enum: [healthy, degraded, unknown]
        reason:
          type: string
    NodeStatus:
      type: object
      required: [nodeId, state, lastHeartbeatAt]
      properties:
        nodeId:
          type: string
        hostname:
          type: string
        state:
          $ref: "#/components/schemas/NodeState"
        sidecarVersion:
          type: string
        lastHeartbeatAt:
          type: string
          format: date-time
        runtimes:
          type: array
          items:
            $ref: "#/components/schemas/RuntimeStatus"
        configHash:
          type: string
        labels:
          $ref: "#/components/schemas/Labels"
        maintenance:
          type: boolean
          description: True when the node is in operator-set maintenance mode (excluded from rollouts and bulk ops by default; node-offline/drift alerts suppressed).
        lastError:
          type: string
    NodeStatusWithDrift:
      allOf:
        - $ref: "#/components/schemas/NodeStatus"
        - type: object
          required: [drift]
          properties:
            drift:
              type: boolean
            sidecarOutdated:
              type: boolean
              description: True when an expected sidecar version is set and this node's version differs.
    ListNodesResponse:
      type: object
      required: [nodes, total, limit, offset]
      properties:
        nodes:
          type: array
          items:
            $ref: "#/components/schemas/NodeStatusWithDrift"
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    Labels:
      type: object
      additionalProperties:
        type: string
    NodeLabelsRequest:
      type: object
      required: [labels]
      properties:
        labels:
          $ref: "#/components/schemas/Labels"
    NodeLabelsResponse:
      type: object
      required: [nodeId, labels]
      properties:
        nodeId:
          type: string
        labels:
          $ref: "#/components/schemas/Labels"
    NodeMaintenanceRequest:
      type: object
      required: [maintenance]
      properties:
        maintenance:
          type: boolean
    NodeMaintenanceResponse:
      type: object
      required: [nodeId, maintenance]
      properties:
        nodeId:
          type: string
        maintenance:
          type: boolean
    WhoamiResponse:
      type: object
      required: [scope, tokenName]
      properties:
        scope:
          $ref: "#/components/schemas/OperatorTokenScope"
        tokenName:
          type: string
          description: Acting token name, or "bootstrap" for the env/flag token.
    ServerStatusResponse:
      type: object
      required: [version, uptimeSeconds, schemaVersion, nodeCount, rolloutCount]
      properties:
        version:
          type: string
        commit:
          type: string
        buildDate:
          type: string
        uptimeSeconds:
          type: integer
          format: int64
        schemaVersion:
          type: integer
        nodeCount:
          type: integer
        rolloutCount:
          type: integer
    HeartbeatRequest:
      type: object
      required: [nodeId, sentAt]
      properties:
        nodeId:
          type: string
        hostname:
          type: string
        sidecarVersion:
          type: string
        sentAt:
          type: string
          format: date-time
        runtimes:
          type: array
          items:
            $ref: "#/components/schemas/RuntimeStatus"
        configHash:
          type: string
        lastError:
          type: string
    HeartbeatResponse:
      type: object
      required: [accepted, serverTime, node]
      properties:
        accepted:
          type: boolean
        serverTime:
          type: string
          format: date-time
        node:
          $ref: "#/components/schemas/NodeStatus"
    JobType:
      type: string
      enum: [deep_probe, config_apply, restart, rollback]
    JobStatus:
      type: string
      enum: [pending, claimed, completed, failed]
    Job:
      type: object
      required: [id, nodeId, type, status, createdAt]
      properties:
        id:
          type: string
        nodeId:
          type: string
        type:
          $ref: "#/components/schemas/JobType"
        status:
          $ref: "#/components/schemas/JobStatus"
        payloadJson:
          type: string
          description: Serialized job payload. May be omitted or summarized for unauthenticated list calls.
        resultJson:
          type: string
          description: Serialized job result. Hidden from unauthenticated list calls when operator auth is configured.
        error:
          type: string
        createdAt:
          type: string
          format: date-time
        claimedAt:
          type: string
          format: date-time
        claimExpiresAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
    CreateJobRequest:
      type: object
      required: [type]
      properties:
        type:
          $ref: "#/components/schemas/JobType"
        payloadJson:
          type: string
    JobResultRequest:
      type: object
      required: [status]
      properties:
        status:
          $ref: "#/components/schemas/JobStatus"
        resultJson:
          type: string
        error:
          type: string
    DeepProbeResult:
      type: object
      required: [runtimes, configSnapshots]
      properties:
        runtimes:
          type: array
          items:
            $ref: "#/components/schemas/RuntimeStatus"
        configSnapshots:
          type: array
          items:
            $ref: "#/components/schemas/RuntimeConfigSnapshot"
    ConfigApplyStep:
      type: object
      required: [name, status]
      properties:
        name:
          type: string
        status:
          type: string
        detail:
          type: string
    ConfigApplyResult:
      type: object
      required: [planId, dryRun, steps]
      properties:
        planId:
          type: string
        dryRun:
          type: boolean
        backupPath:
          type: string
          description: Sidecar-local backup reference or path.
        backup:
          $ref: "#/components/schemas/RollbackBackup"
        tempPath:
          type: string
          description: Sidecar-local temporary validation path.
        steps:
          type: array
          items:
            $ref: "#/components/schemas/ConfigApplyStep"
    RestartRequest:
      type: object
      properties:
        runtimeType:
          type: string
          enum: [hermes, openclaw]
        runtimeName:
          type: string
        profile:
          type: string
        reason:
          type: string
        live:
          type: boolean
          default: false
    RestartJobPayload:
      type: object
      required: [dryRun]
      properties:
        runtimeType:
          type: string
        runtimeName:
          type: string
        profile:
          type: string
        reason:
          type: string
        dryRun:
          type: boolean
    RestartJobResult:
      type: object
      required: [steps]
      properties:
        controller:
          type: string
        steps:
          type: array
          items:
            $ref: "#/components/schemas/ConfigApplyStep"
        healthStatus:
          type: string
    RollbackBackup:
      type: object
      required: [ref, sourceJobId]
      properties:
        ref:
          type: string
        sourceJobId:
          type: string
        planId:
          type: string
        runtimeType:
          type: string
        profile:
          type: string
        configPath:
          type: string
          description: Sidecar-local config path from a prior signed plan.
        backupPath:
          type: string
          description: Sidecar-local backup path reported by the sidecar.
        createdAt:
          type: string
          format: date-time
    RollbackBackupInventoryItem:
      type: object
      required: [ref, sourceJobId]
      properties:
        ref:
          type: string
        sourceJobId:
          type: string
        runtimeType:
          type: string
        profile:
          type: string
        configHash:
          type: string
        createdAt:
          type: string
          format: date-time
    ListRollbackBackupsResponse:
      type: object
      required: [backups, total, limit]
      properties:
        backups:
          type: array
          items:
            $ref: "#/components/schemas/RollbackBackupInventoryItem"
        total:
          type: integer
        limit:
          type: integer
    RollbackRequest:
      type: object
      required: [backupRef]
      properties:
        runtimeType:
          type: string
          enum: [hermes, openclaw]
        runtimeName:
          type: string
        profile:
          type: string
        backupRef:
          type: string
        live:
          type: boolean
          default: false
    RollbackJobPayload:
      type: object
      required: [backupRef, configPath, backupPath, dryRun]
      properties:
        runtimeType:
          type: string
        runtimeName:
          type: string
        profile:
          type: string
        backupRef:
          type: string
        configPath:
          type: string
        backupPath:
          type: string
        dryRun:
          type: boolean
    RollbackJobResult:
      type: object
      required: [backupRef, steps]
      properties:
        backupRef:
          type: string
        steps:
          type: array
          items:
            $ref: "#/components/schemas/ConfigApplyStep"
        healthStatus:
          type: string
    RolloutState:
      type: string
      enum: [pending, scheduled, running, paused, completed, aborted, failed]
    RolloutBatchState:
      type: string
      enum: [pending, running, completed, paused, failed]
    RolloutNodeState:
      type: string
      enum: [pending, dispatched, succeeded, failed, timed_out, offline]
    RolloutAction:
      type: string
      enum: [pause, resume, abort]
    RolloutSpec:
      type: object
      required: [runtimeType, target, live]
      properties:
        selector:
          $ref: "#/components/schemas/Labels"
        nodeIds:
          type: array
          items:
            type: string
        runtimeType:
          type: string
          enum: [hermes, openclaw]
        profile:
          type: string
        target:
          $ref: "#/components/schemas/ProviderModelConfig"
        batchSize:
          type: integer
          minimum: 1
          default: 1
        live:
          type: boolean
          default: false
        autoRollbackOnFailure:
          type: boolean
          default: false
          description: When true, a failed live batch rolls back already-applied nodes before pausing.
        healthTimeout:
          type: integer
          format: int64
          minimum: 0
          description: Nanoseconds. Omit or send 0 to use the server default.
        startAt:
          type: string
          format: date-time
          description: Optional scheduled start time (RFC3339). A future value keeps the rollout scheduled until then; empty or past runs immediately.
        includeMaintenance:
          type: boolean
          default: false
          description: When true, explicitly include nodes in maintenance mode; default false excludes them from new rollouts.
        allowOverlap:
          type: boolean
          default: false
          description: When true, allow creating a rollout whose resolved nodes overlap non-terminal rollouts; default false returns a 409 conflict.
    RolloutNodeProgress:
      type: object
      required: [nodeId, state]
      properties:
        nodeId:
          type: string
        jobId:
          type: string
        state:
          $ref: "#/components/schemas/RolloutNodeState"
        lastError:
          type: string
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
        rollbackJobId:
          type: string
          description: Rollback job dispatched by auto-rollback for this node, if any.
        rolledBack:
          type: boolean
    RolloutBatch:
      type: object
      required: [index, nodeIds, state, nodes]
      properties:
        index:
          type: integer
        nodeIds:
          type: array
          items:
            type: string
        state:
          $ref: "#/components/schemas/RolloutBatchState"
        nodes:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/RolloutNodeProgress"
    Rollout:
      type: object
      required: [id, spec, state, batches, createdAt, updatedAt]
      properties:
        id:
          type: string
        spec:
          $ref: "#/components/schemas/RolloutSpec"
        state:
          $ref: "#/components/schemas/RolloutState"
        batches:
          type: array
          items:
            $ref: "#/components/schemas/RolloutBatch"
        pauseReason:
          type: string
        failingNodeIds:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
    CreateRolloutRequest:
      type: object
      required: [spec]
      properties:
        spec:
          $ref: "#/components/schemas/RolloutSpec"
        templateId:
          type: string
          description: When set, the referenced template's spec prefills the rollout.
    RolloutTemplate:
      type: object
      required: [id, name, spec, createdAt]
      properties:
        id:
          type: string
        name:
          type: string
        spec:
          $ref: "#/components/schemas/RolloutSpec"
        createdAt:
          type: string
          format: date-time
    CreateRolloutTemplateRequest:
      type: object
      required: [name, spec]
      properties:
        name:
          type: string
        spec:
          $ref: "#/components/schemas/RolloutSpec"
    CreateRolloutTemplateResponse:
      type: object
      required: [template]
      properties:
        template:
          $ref: "#/components/schemas/RolloutTemplate"
    ListRolloutTemplatesResponse:
      type: object
      required: [templates]
      properties:
        templates:
          type: array
          items:
            $ref: "#/components/schemas/RolloutTemplate"
    BulkJobRequest:
      type: object
      required: [type]
      properties:
        selector:
          $ref: "#/components/schemas/Labels"
        nodeIds:
          type: array
          items:
            type: string
        type:
          type: string
          enum: [deep_probe]
    BulkJobResult:
      type: object
      required: [nodeId]
      properties:
        nodeId:
          type: string
        jobId:
          type: string
        error:
          type: string
    BulkJobResponse:
      type: object
      required: [jobs, created]
      properties:
        jobs:
          type: array
          items:
            $ref: "#/components/schemas/BulkJobResult"
        created:
          type: integer
    BulkNodeLabelsRequest:
      type: object
      required: [labels]
      properties:
        selector:
          $ref: "#/components/schemas/Labels"
        nodeIds:
          type: array
          items:
            type: string
        labels:
          $ref: "#/components/schemas/Labels"
    BulkNodeLabelsResponse:
      type: object
      required: [nodeIds, updated]
      properties:
        nodeIds:
          type: array
          items:
            type: string
        updated:
          type: integer
    AlertEventType:
      type: string
      enum: [node.offline, node.drift, rollout.paused, rollout.failed]
    AlertWebhookKind:
      type: string
      enum: [generic, slack]
    AlertWebhook:
      type: object
      required: [id, kind, url, events, hasSecret, disabled, createdAt]
      properties:
        id:
          type: string
        kind:
          $ref: "#/components/schemas/AlertWebhookKind"
        url:
          type: string
        events:
          type: array
          items:
            $ref: "#/components/schemas/AlertEventType"
        hasSecret:
          type: boolean
        disabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
    CreateAlertWebhookRequest:
      type: object
      required: [url, events]
      properties:
        url:
          type: string
        kind:
          $ref: "#/components/schemas/AlertWebhookKind"
          description: Defaults to generic. Slack sends an incoming-webhook-compatible body and cannot use Sideplane HMAC signing.
        events:
          type: array
          items:
            $ref: "#/components/schemas/AlertEventType"
        sign:
          type: boolean
          description: Generic webhooks only. When true and no secret is provided, the server generates one and returns it once.
        secret:
          type: string
          description: Generic webhooks only. If provided, deliveries carry an HMAC signature header.
    CreateAlertWebhookResponse:
      type: object
      required: [webhook]
      properties:
        webhook:
          $ref: "#/components/schemas/AlertWebhook"
        secret:
          type: string
          description: Signing secret, returned only once at creation time.
    ListAlertWebhooksResponse:
      type: object
      required: [webhooks]
      properties:
        webhooks:
          type: array
          items:
            $ref: "#/components/schemas/AlertWebhook"
    AlertWebhookPayload:
      type: object
      description: >-
        Outbound JSON body delivered to a registered alert webhook. Sideplane
        POSTs this to the configured URL when a subscribed event fires; it never
        contains secrets. Documented for receiver implementations.
      required: [event, occurredAt]
      properties:
        event:
          $ref: "#/components/schemas/AlertEventType"
        nodeId:
          type: string
        rolloutId:
          type: string
        actor:
          type: string
        detail:
          type: string
        occurredAt:
          type: string
          format: date-time
    ExpectedRuntimeVersions:
      type: object
      additionalProperties: false
      properties:
        hermes:
          type: string
          description: Operator-configured expected Hermes Agent version. Empty or absent disables the Hermes runtime version check.
        openclaw:
          type: string
          description: Operator-configured expected OpenClaw version. Empty or absent disables the OpenClaw runtime version check.
    ServerSettings:
      type: object
      required: [expectedSidecarVersion, expectedRuntimeVersions]
      properties:
        expectedSidecarVersion:
          type: string
        expectedRuntimeVersions:
          $ref: "#/components/schemas/ExpectedRuntimeVersions"
    UpdateServerSettingsRequest:
      type: object
      required: [expectedSidecarVersion]
      properties:
        expectedSidecarVersion:
          type: string
        expectedRuntimeVersions:
          $ref: "#/components/schemas/ExpectedRuntimeVersions"
    CreateRolloutResponse:
      type: object
      required: [rollout]
      properties:
        rollout:
          $ref: "#/components/schemas/Rollout"
    ListRolloutsResponse:
      type: object
      required: [rollouts, total, limit, offset]
      properties:
        rollouts:
          type: array
          items:
            $ref: "#/components/schemas/Rollout"
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    GetRolloutResponse:
      type: object
      required: [rollout]
      properties:
        rollout:
          $ref: "#/components/schemas/Rollout"
    RolloutActionRequest:
      type: object
      required: [action]
      properties:
        action:
          $ref: "#/components/schemas/RolloutAction"
    RolloutActionResponse:
      type: object
      required: [rollout]
      properties:
        rollout:
          $ref: "#/components/schemas/Rollout"
    RuntimeConfigSnapshot:
      type: object
      required: [runtimeName, runtimeType]
      properties:
        runtimeName:
          type: string
        runtimeType:
          type: string
        configPath:
          type: string
          description: Operator-configured or sidecar-local path, never file contents.
        source:
          type: string
        profile:
          type: string
        provider:
          type: string
        model:
          type: string
        providers:
          type: array
          items:
            $ref: "#/components/schemas/ProviderCatalogEntry"
        configHash:
          type: string
        warnings:
          type: array
          items:
            type: string
        health:
          $ref: "#/components/schemas/RuntimeHealth"
    ProviderModelConfig:
      type: object
      properties:
        provider:
          type: string
        model:
          type: string
    ProviderDefinition:
      type: object
      required: [name]
      properties:
        name:
          type: string
        baseURL:
          type: string
        models:
          type: array
          items:
            type: string
        apiKeyEnv:
          type: string
          description: Environment variable name only; never plaintext secret material.
        apiKeyManaged:
          type: boolean
          readOnly: true
          description: True when Sideplane has an encrypted stored API key for apiKeyEnv.
    ProviderScope:
      type: object
      properties:
        nodeId:
          type: string
        runtimeType:
          type: string
        profile:
          type: string
    UpsertProviderRequest:
      type: object
      required: [provider]
      properties:
        scope:
          $ref: "#/components/schemas/ProviderScope"
        provider:
          $ref: "#/components/schemas/ProviderDefinition"
        apiKey:
          type: string
          writeOnly: true
          description: Stored encrypted at rest and never returned.
    ProviderCatalogEntry:
      type: object
      required: [name]
      properties:
        name:
          type: string
        baseURL:
          type: string
        models:
          type: array
          items:
            type: string
        apiKeyEnv:
          type: string
          description: Environment variable name reported from an ${ENV} reference; never plaintext secret material.
        active:
          type: boolean
    ProviderCatalogResponse:
      type: object
      properties:
        global:
          type: array
          items:
            $ref: "#/components/schemas/ProviderDefinition"
        nodeProviders:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ProviderDefinition"
        runtimeProfileProviders:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ProviderDefinition"
        nodeRuntimeProfileProviders:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ProviderDefinition"
        effective:
          type: array
          items:
            $ref: "#/components/schemas/ProviderDefinition"
        actual:
          type: array
          items:
            $ref: "#/components/schemas/ProviderCatalogEntry"
    DesiredConfig:
      type: object
      properties:
        global:
          $ref: "#/components/schemas/ProviderModelConfig"
        nodeOverrides:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/ProviderModelConfig"
        runtimeProfileOverrides:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/ProviderModelConfig"
        nodeRuntimeProfileOverrides:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/ProviderModelConfig"
        globalProviders:
          type: array
          items:
            $ref: "#/components/schemas/ProviderDefinition"
        nodeProviders:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ProviderDefinition"
        runtimeProfileProviders:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ProviderDefinition"
        nodeRuntimeProfileProviders:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/ProviderDefinition"
    DesiredConfigHistoryEntry:
      type: object
      required: [id, config, updatedAt, actor]
      properties:
        id:
          type: string
        config:
          $ref: "#/components/schemas/DesiredConfig"
        desiredHash:
          type: string
        updatedAt:
          type: string
          format: date-time
        actor:
          type: string
    ListDesiredConfigHistoryResponse:
      type: object
      required: [history, total, limit, offset]
      properties:
        history:
          type: array
          items:
            $ref: "#/components/schemas/DesiredConfigHistoryEntry"
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    RevertDesiredConfigRequest:
      type: object
      required: [historyId]
      properties:
        historyId:
          type: string
    RevertDesiredConfigResponse:
      type: object
      required: [desired, history]
      properties:
        desired:
          $ref: "#/components/schemas/DesiredConfig"
        history:
          $ref: "#/components/schemas/DesiredConfigHistoryEntry"
    ConfigDiffEntry:
      type: object
      required: [field, change]
      properties:
        field:
          type: string
        actual:
          type: string
        desired:
          type: string
        change:
          type: string
          enum: [update, missingActual]
    EffectiveConfigResponse:
      type: object
      required: [nodeId, effective, diff]
      properties:
        nodeId:
          type: string
        runtimeType:
          type: string
        profile:
          type: string
        effective:
          $ref: "#/components/schemas/ProviderModelConfig"
        desiredHash:
          type: string
        actual:
          $ref: "#/components/schemas/RuntimeConfigSnapshot"
        diff:
          type: array
          items:
            $ref: "#/components/schemas/ConfigDiffEntry"
    EffectiveConfigPreviewRequest:
      type: object
      required: [nodeId, desired]
      properties:
        nodeId:
          type: string
        runtimeType:
          type: string
        profile:
          type: string
        desired:
          $ref: "#/components/schemas/ProviderModelConfig"
    ConfigApplyRequest:
      type: object
      properties:
        runtimeType:
          type: string
        profile:
          type: string
        dryRun:
          type: boolean
          default: true
    ConfigPlanBody:
      type: object
      required: [runtimeType, desired, dryRun]
      properties:
        runtimeType:
          type: string
        profile:
          type: string
        desired:
          $ref: "#/components/schemas/ProviderModelConfig"
        providers:
          type: array
          items:
            $ref: "#/components/schemas/ProviderDefinition"
        dryRun:
          type: boolean
    ConfigPlan:
      type: object
      required: [id, schema, version, createdAt, targetNodeId, mode, body]
      properties:
        id:
          type: string
        schema:
          type: string
          const: sideplane.config-plan.v1
        version:
          type: integer
          const: 1
        createdAt:
          type: string
          format: date-time
        targetNodeId:
          type: string
        mode:
          type: string
          enum: [dry_run, live]
        body:
          $ref: "#/components/schemas/ConfigPlanBody"
    SignedConfigPlan:
      type: object
      required: [plan, signature]
      properties:
        plan:
          $ref: "#/components/schemas/ConfigPlan"
        signature:
          type: string
    ConfigApplySecretsResponse:
      type: object
      required: [secrets]
      properties:
        secrets:
          type: object
          additionalProperties:
            type: string
          description: Plaintext values keyed by env var name; returned only to authenticated sidecars.
    PublicSigningKeyResponse:
      type: object
      required: [algorithm, publicKey]
      properties:
        algorithm:
          type: string
          const: ed25519
        publicKey:
          type: string
    AuditEvent:
      type: object
      required: [id, actor, action, createdAt]
      properties:
        id:
          type: string
        actor:
          type: string
        actorName:
          type: string
          description: Acting operator token name when known ("bootstrap" for the env/flag token). Never a secret.
        action:
          type: string
        targetNode:
          type: string
        detail:
          type: string
        createdAt:
          type: string
          format: date-time
    ListAuditEventsResponse:
      type: object
      required: [events]
      properties:
        events:
          type: array
          items:
            $ref: "#/components/schemas/AuditEvent"