SPB Git

Repository Public

openapi.yaml 246.2 KB 5,214 lines yaml

1openapi: 3.1.02info:3  title: MacLustr Command Center API4  version: 1.0.05  summary: Public REST + SSE API served by control-api under /api/v1.6  description: |7    Contract of the public API of **MacLustr Command Center** (`control-api`). This document is the source of truth8    for the Go server (`oapi-codegen`, strict server), the web client (`openapi-typescript` + `openapi-fetch`) and9    the Apple clients (`swift-openapi-generator`, package `MCCCore`).1011    ## Conventions1213    - **Base path**: every path below is relative to `/api/v1`.14    - **Authentication**: web clients use the session cookie `__Host-mcc_session` (scheme `cookieSession`);15      native clients use an opaque access token (`Authorization: Bearer`, scheme `bearer`, 10 min) plus a rotating16      refresh token (30 days, device-bound).17    - **CSRF**: every non-safe request (POST, PUT, PATCH, DELETE) authenticated by the session cookie MUST carry the18      header `X-MCC-CSRF` (token returned by `GET /me` and by the authentication result) and a matching `Origin`.19      The header is ignored for bearer sessions. Failure is `403 csrf_failed`.20    - **Permissions**: each operation states the permission it requires in `x-permission`21      (`authenticated` = any valid session, `none` = no session required). `x-step-up: true` means a passkey ceremony22      younger than 5 minutes is required on the session, otherwise `403 step_up_required`23      (run `POST /auth/stepup/begin` + `/finish`, then retry).24    - **Errors**: every non-2xx response is `application/json` with the `ErrorResponse` envelope.25    - **Correlation**: every response carries `X-Correlation-Id`; the same id is found in `error.correlation_id`26      and in the audit log.27    - **Pagination**: cursor based. Query `limit` (1-200, default 50) and `cursor` (opaque); list responses are28      objects `{ items: [...], next_cursor?: string }`. No `next_cursor` means the last page.29    - **Time**: timestamps are RFC 3339 UTC (`date-time`). Ids are UUID (v7). Byte counts are `int64`.30    - **Optional fields are omitted**, never sent as `null`.31    - **Telemetry honesty**: a value that cannot be measured is never invented nor zeroed. It is absent and its32      state is given by an `Availability` value. Every telemetry-derived resource carries `observed_at` and33      `freshness` (`fresh` < 30 s, `stale` 30-120 s, `offline` > 120 s or never seen), computed by the server.34    - **Idempotency**: mutations that create actions or jobs require the `Idempotency-Key` header. Same key and35      same body returns the original resource (`200`); same key with a different body is `409 idempotency_conflict`.3637    ## Error codes3839    | HTTP | `error.code` | Meaning |40    |---|---|---|41    | 400 | `validation_failed` | Malformed body, parameter or header; `details.fields` lists the offending fields |42    | 401 | `unauthenticated` | No valid session or token |43    | 401 | `session_expired` | Idle (30 min) or absolute (12 h) expiry reached, or access token expired |44    | 401 | `webauthn_failed` | Passkey ceremony rejected (challenge consumed or expired, bad signature, UV missing, counter regression) |45    | 401 | `refresh_reuse_detected` | A rotated refresh token was presented again; the session has been revoked |46    | 403 | `forbidden` | The session lacks the required permission (or a deny grant applies) |47    | 403 | `step_up_required` | A passkey ceremony younger than 5 minutes is required |48    | 403 | `csrf_failed` | Missing or invalid `X-MCC-CSRF`, or `Origin` mismatch |49    | 404 | `not_found` | Unknown resource, or resource hidden from the caller |50    | 409 | `conflict` | State conflict (duplicate alias, handle taken, invalid state transition...) |51    | 409 | `idempotency_conflict` | `Idempotency-Key` reused with a different request body |52    | 409 | `target_locked` | Another action holds the lock of the target; `details.action_id` is the holder |53    | 409 | `last_passkey` | Refusal to delete the last active passkey of an account |54    | 410 | `gone` | Invitation or setup transaction expired, consumed or revoked |55    | 422 | `precheck_failed` | Server pre-check of an action failed; `details.check` names it |56    | 422 | `confirmation_mismatch` | `confirm` does not equal the alias of the target |57    | 422 | `justification_required` | The action type requires a justification |58    | 422 | `agent_offline` | The agent of the target node is offline or revoked |59    | 422 | `capability_missing` | The agent does not declare the capability for this action type |60    | 422 | `node_in_maintenance` | The target node is in maintenance mode |61    | 422 | `action_unavailable` | The action type is in the catalog with `available=false` |62    | 422 | `unprocessable` | Semantically invalid request not covered by a more specific code |63    | 429 | `rate_limited` | Too many requests; see `Retry-After` |64    | 500 | `internal` | Unexpected server error (may be returned by any operation) |65    | 503 | `unavailable` | A dependency (database, ingest, orchestrator) is unavailable |66    | 503 | `orchestrator_frozen` | Emergency stop is engaged (`orchestrator.frozen=true`); no command is issued |67  contact:68    name: MacLustr Command Center69    url: https://clustr.spboucher.ai70  license:71    name: Proprietary72    identifier: LicenseRef-Proprietary73servers:74  - url: https://clustr.spboucher.ai/api/v175    description: Production76  - url: http://localhost:8730/api/v177    description: Local development78security:79  - cookieSession: []80  - bearer: []81tags:82  - {name: Auth, description: 'Passkey (WebAuthn) authentication, step-up, sessions, devices and the current account.'}83  - {name: Invitations, description: 'Single-use invitations and the short setup transaction that follows the token exchange.'}84  - {name: Admin, description: 'User, policy, agent and settings administration; backend status.'}85  - {name: Cluster, description: 'Cluster-wide overview and aggregated trends.'}86  - {name: Nodes, description: 'Node inventory, latest state, metric series, processes and health history.'}87  - {name: Services, description: 'Services observed by the agents (PM2, launchd, systemd, docker).'}88  - {name: Models, description: 'Inference servers observed on the nodes.'}89  - {name: Jobs, description: 'Job templates, jobs and recurring schedules.'}90  - {name: Alerts, description: 'Alerts, alert rules, silences and incidents.'}91  - {name: Maintenance, description: 'Maintenance calendar (windows, recurring occurrences) and maintenance notes.'}92  - {name: Network, description: 'Observed network topology and interfaces.'}93  - {name: Storage, description: 'Volumes, NAS targets and observed backups.'}94  - {name: Actions, description: 'Typed action catalog and action lifecycle. There is no free-form command.'}95  - {name: Audit, description: 'Append-only, hash-chained audit log.'}96  - {name: Events, description: 'Real-time event stream (Server-Sent Events).'}97  - {name: Dashboards, description: 'Per-user dashboard layouts.'}98  - {name: Activity, description: 'Redacted operator-visible activity feed.'}99  - {name: Search, description: 'Universal search.'}100  - {name: Meta, description: 'Liveness, readiness and version.'}101102paths:103  # ───────────────────────────── Auth ─────────────────────────────104  /auth/webauthn/authentication/begin:105    post:106      tags: [Auth]107      operationId: beginAuthentication108      summary: Begin a passkey authentication ceremony109      description: |110        Returns a single-use challenge (32 bytes, valid 5 minutes) for a discoverable-credential (usernameless)111        ceremony. `userVerification` is `required`. Rate limit: 10 requests per minute per IP.112      x-permission: none113      security: []114      responses:115        '200':116          description: Challenge created.117          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}118          content:119            application/json:120              schema: {$ref: '#/components/schemas/WebAuthnChallenge'}121              example:122                challenge_id: 019a9c1e-7b10-7c3a-9d54-2f6f1f0f3a11123                expires_at: '2026-11-18T21:05:00Z'124                public_key:125                  challenge: 3q2-7wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA126                  rpId: clustr.spboucher.ai127                  timeout: 300000128                  userVerification: required129        '429': {$ref: '#/components/responses/RateLimited'}130        '503': {$ref: '#/components/responses/Unavailable'}131  /auth/webauthn/authentication/finish:132    post:133      tags: [Auth]134      operationId: finishAuthentication135      summary: Finish a passkey authentication ceremony and open a session136      description: |137        Verifies the assertion (origin, RP ID, user verification, signature counter) and opens a session bound to a138        device. `client.kind=web`: sets the cookie `__Host-mcc_session` (Secure, HttpOnly, SameSite=Strict, Path=/)139        and returns `csrf_token`. `client.kind=macos|ios`: returns `access_token`, `access_expires_at` and140        `refresh_token` instead, and sets no cookie. Rate limit: 10 requests per minute per IP.141      x-permission: none142      security: []143      requestBody:144        required: true145        content:146          application/json:147            schema: {$ref: '#/components/schemas/AuthenticationFinishRequest'}148            example:149              challenge_id: 019a9c1e-7b10-7c3a-9d54-2f6f1f0f3a11150              credential:151                id: Xk3f0Jm2Qy8152                rawId: Xk3f0Jm2Qy8153                type: public-key154                response: {clientDataJSON: eyJ0eXBlIjoid2ViYXV0aG4uZ2V0In0, authenticatorData: SZYN5YgO, signature: MEUCIQ, userHandle: q83vEjRWeJA}155              client: {kind: web, label: Safari on MacBook Pro}156      responses:157        '200':158          description: Authenticated. For web clients the session cookie is set.159          headers:160            X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}161            Set-Cookie:162              description: '`__Host-mcc_session=<opaque>; Secure; HttpOnly; SameSite=Strict; Path=/` (web clients only).'163              schema: {type: string}164          content:165            application/json:166              schema: {$ref: '#/components/schemas/AuthResult'}167              example:168                user:169                  id: 019a9b00-1111-7aaa-8bbb-000000000001170                  handle: spb171                  display_name: Simon-Pierre172                  role: owner173                  locale: fr174                  disabled: false175                  created_at: '2026-11-18T20:40:00Z'176                session:177                  id: 019a9c1e-9000-7000-8000-00000000a001178                  kind: cookie179                  device_id: 019a9c1e-9000-7000-8000-00000000d001180                  current: true181                  created_at: '2026-11-18T21:00:12Z'182                  last_seen_at: '2026-11-18T21:00:12Z'183                  authenticated_at: '2026-11-18T21:00:12Z'184                  step_up_valid_until: '2026-11-18T21:05:12Z'185                  idle_expires_at: '2026-11-18T21:30:12Z'186                  absolute_expires_at: '2026-11-19T09:00:12Z'187                csrf_token: 6fJmC0n1x1c0u0S7wq5a8nq3mVbYb1pZ5nq2dX0v9Qk188        '400': {$ref: '#/components/responses/BadRequest'}189        '401': {$ref: '#/components/responses/Unauthenticated'}190        '403': {$ref: '#/components/responses/Forbidden'}191        '429': {$ref: '#/components/responses/RateLimited'}192        '503': {$ref: '#/components/responses/Unavailable'}193  /auth/webauthn/registration/begin:194    post:195      tags: [Auth]196      operationId: beginRegistration197      summary: Begin a passkey registration ceremony198      description: |199        Two contexts: (1) **add a passkey to the current account** - requires a session and a step-up;200        (2) **complete an invitation** - authenticated by the setup transaction (cookie `__Host-mcc_setup` or header201        `X-MCC-Setup-Transaction`); the transaction must have a handle and display name202        (see `POST /invitations/transaction/profile`). `residentKey=required`, `userVerification=required`,203        attestation `none`, algorithms ES256 and RS256. Rate limit: 10 requests per minute per IP.204      x-permission: authenticated205      x-step-up: true206      security:207        - cookieSession: []208        - bearer: []209        - setupCookie: []210        - setupHeader: []211      parameters:212        - {$ref: '#/components/parameters/Csrf'}213      requestBody:214        required: false215        content:216          application/json:217            schema: {$ref: '#/components/schemas/RegistrationBeginRequest'}218      responses:219        '200':220          description: Challenge created. `public_key` is the PublicKeyCredentialCreationOptions JSON.221          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}222          content: {application/json: {schema: {$ref: '#/components/schemas/WebAuthnChallenge'}}}223        '400': {$ref: '#/components/responses/BadRequest'}224        '401': {$ref: '#/components/responses/Unauthenticated'}225        '403': {$ref: '#/components/responses/Forbidden'}226        '410': {$ref: '#/components/responses/Gone'}227        '429': {$ref: '#/components/responses/RateLimited'}228  /auth/webauthn/registration/finish:229    post:230      tags: [Auth]231      operationId: finishRegistration232      summary: Finish a passkey registration ceremony233      description: |234        Stores the new passkey. In the invitation context this creates the account, completes the invitation, opens235        a session and returns it in `auth` (cookie set for web clients, tokens for native clients; `client` is then236        required). In the add-a-passkey context `auth` is absent. Rate limit: 10 requests per minute per IP.237      x-permission: authenticated238      x-step-up: true239      security:240        - cookieSession: []241        - bearer: []242        - setupCookie: []243        - setupHeader: []244      parameters:245        - {$ref: '#/components/parameters/Csrf'}246      requestBody:247        required: true248        content: {application/json: {schema: {$ref: '#/components/schemas/RegistrationFinishRequest'}}}249      responses:250        '200':251          description: Passkey registered.252          headers:253            X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}254            Set-Cookie:255              description: Session cookie, only when an invitation is completed by a web client.256              schema: {type: string}257          content: {application/json: {schema: {$ref: '#/components/schemas/RegistrationResult'}}}258        '400': {$ref: '#/components/responses/BadRequest'}259        '401': {$ref: '#/components/responses/Unauthenticated'}260        '403': {$ref: '#/components/responses/Forbidden'}261        '409': {$ref: '#/components/responses/Conflict'}262        '410': {$ref: '#/components/responses/Gone'}263        '429': {$ref: '#/components/responses/RateLimited'}264  /auth/stepup/begin:265    post:266      tags: [Auth]267      operationId: beginStepUp268      summary: Begin a step-up passkey ceremony for the current session269      description: 'The challenge only accepts passkeys of the current user. Rate limit: 10 requests per minute per session.'270      x-permission: authenticated271      parameters:272        - {$ref: '#/components/parameters/Csrf'}273      responses:274        '200':275          description: Challenge created.276          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}277          content: {application/json: {schema: {$ref: '#/components/schemas/WebAuthnChallenge'}}}278        '401': {$ref: '#/components/responses/Unauthenticated'}279        '403': {$ref: '#/components/responses/Forbidden'}280        '429': {$ref: '#/components/responses/RateLimited'}281  /auth/stepup/finish:282    post:283      tags: [Auth]284      operationId: finishStepUp285      summary: Finish a step-up ceremony286      description: 'Refreshes `authenticated_at` of the session; step-up is then valid for 5 minutes. Rate limit: 10 requests per minute per session.'287      x-permission: authenticated288      parameters:289        - {$ref: '#/components/parameters/Csrf'}290      requestBody:291        required: true292        content: {application/json: {schema: {$ref: '#/components/schemas/StepUpFinishRequest'}}}293      responses:294        '200':295          description: Step-up accepted.296          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}297          content: {application/json: {schema: {$ref: '#/components/schemas/StepUpResult'}}}298        '400': {$ref: '#/components/responses/BadRequest'}299        '401': {$ref: '#/components/responses/Unauthenticated'}300        '403': {$ref: '#/components/responses/Forbidden'}301        '429': {$ref: '#/components/responses/RateLimited'}302  /auth/refresh:303    post:304      tags: [Auth]305      operationId: refreshSession306      summary: Rotate the refresh token of a native session307      description: |308        Native clients only. The presented refresh token is consumed and a new access + refresh pair is returned.309        Presenting an already rotated token revokes the session (`401 refresh_reuse_detected`) and is audited.310        Rate limit: 30 requests per minute per IP.311      x-permission: none312      security: []313      requestBody:314        required: true315        content: {application/json: {schema: {$ref: '#/components/schemas/RefreshRequest'}}}316      responses:317        '200':318          description: New token pair.319          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}320          content: {application/json: {schema: {$ref: '#/components/schemas/TokenPair'}}}321        '400': {$ref: '#/components/responses/BadRequest'}322        '401': {$ref: '#/components/responses/Unauthenticated'}323        '429': {$ref: '#/components/responses/RateLimited'}324  /auth/logout:325    post:326      tags: [Auth]327      operationId: logout328      summary: Revoke the current session329      description: Revokes the current session (and its refresh tokens) and clears the session cookie.330      x-permission: authenticated331      parameters:332        - {$ref: '#/components/parameters/Csrf'}333      responses:334        '204':335          description: Session revoked.336          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}337        '401': {$ref: '#/components/responses/Unauthenticated'}338        '403': {$ref: '#/components/responses/Forbidden'}339  /me:340    get:341      tags: [Auth]342      operationId: getMe343      summary: Current user, effective permissions and session344      description: Also delivers the CSRF token of a cookie session (absent for bearer sessions).345      x-permission: authenticated346      responses:347        '200':348          description: Current account.349          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}350          content:351            application/json:352              schema: {$ref: '#/components/schemas/Me'}353              example:354                user:355                  id: 019a9b00-1111-7aaa-8bbb-000000000001356                  handle: spb357                  display_name: Simon-Pierre358                  role: owner359                  locale: fr360                  disabled: false361                  created_at: '2026-11-18T20:40:00Z'362                permissions: [cluster.read, nodes.read, nodes.private.read, actions.run.low, actions.run.medium]363                session:364                  id: 019a9c1e-9000-7000-8000-00000000a001365                  kind: cookie366                  device_id: 019a9c1e-9000-7000-8000-00000000d001367                  current: true368                  created_at: '2026-11-18T21:00:12Z'369                  last_seen_at: '2026-11-18T21:03:40Z'370                  authenticated_at: '2026-11-18T21:00:12Z'371                  step_up_valid_until: '2026-11-18T21:05:12Z'372                  idle_expires_at: '2026-11-18T21:33:40Z'373                  absolute_expires_at: '2026-11-19T09:00:12Z'374                csrf_token: 6fJmC0n1x1c0u0S7wq5a8nq3mVbYb1pZ5nq2dX0v9Qk375        '401': {$ref: '#/components/responses/Unauthenticated'}376    patch:377      tags: [Auth]378      operationId: updateMe379      summary: Update the display name or locale of the current user380      x-permission: authenticated381      parameters:382        - {$ref: '#/components/parameters/Csrf'}383      requestBody:384        required: true385        content: {application/json: {schema: {$ref: '#/components/schemas/UpdateMeRequest'}}}386      responses:387        '200':388          description: Updated user.389          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}390          content: {application/json: {schema: {$ref: '#/components/schemas/User'}}}391        '400': {$ref: '#/components/responses/BadRequest'}392        '401': {$ref: '#/components/responses/Unauthenticated'}393        '403': {$ref: '#/components/responses/Forbidden'}394  /me/passkeys:395    get:396      tags: [Auth]397      operationId: listMyPasskeys398      summary: List the passkeys of the current user399      x-permission: authenticated400      responses:401        '200':402          description: Passkeys (active ones only).403          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}404          content: {application/json: {schema: {$ref: '#/components/schemas/PasskeyList'}}}405        '401': {$ref: '#/components/responses/Unauthenticated'}406  /me/passkeys/{id}:407    parameters:408      - {$ref: '#/components/parameters/Id'}409    patch:410      tags: [Auth]411      operationId: updateMyPasskey412      summary: Rename a passkey of the current user413      x-permission: authenticated414      parameters:415        - {$ref: '#/components/parameters/Csrf'}416      requestBody:417        required: true418        content: {application/json: {schema: {$ref: '#/components/schemas/UpdatePasskeyRequest'}}}419      responses:420        '200':421          description: Updated passkey.422          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}423          content: {application/json: {schema: {$ref: '#/components/schemas/Passkey'}}}424        '400': {$ref: '#/components/responses/BadRequest'}425        '401': {$ref: '#/components/responses/Unauthenticated'}426        '403': {$ref: '#/components/responses/Forbidden'}427        '404': {$ref: '#/components/responses/NotFound'}428    delete:429      tags: [Auth]430      operationId: deleteMyPasskey431      summary: Revoke a passkey of the current user432      description: Refuses to delete the last active passkey of the account (`409 last_passkey`).433      x-permission: authenticated434      x-step-up: true435      parameters:436        - {$ref: '#/components/parameters/Csrf'}437      responses:438        '204':439          description: Passkey revoked.440          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}441        '401': {$ref: '#/components/responses/Unauthenticated'}442        '403': {$ref: '#/components/responses/Forbidden'}443        '404': {$ref: '#/components/responses/NotFound'}444        '409': {$ref: '#/components/responses/Conflict'}445  /me/sessions:446    get:447      tags: [Auth]448      operationId: listMySessions449      summary: List the active sessions of the current user450      x-permission: authenticated451      responses:452        '200':453          description: Sessions.454          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}455          content: {application/json: {schema: {$ref: '#/components/schemas/SessionList'}}}456        '401': {$ref: '#/components/responses/Unauthenticated'}457  /me/sessions/{id}:458    parameters:459      - {$ref: '#/components/parameters/Id'}460    delete:461      tags: [Auth]462      operationId: revokeMySession463      summary: Revoke one of the sessions of the current user464      x-permission: authenticated465      parameters:466        - {$ref: '#/components/parameters/Csrf'}467      responses:468        '204':469          description: Session revoked.470          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}471        '401': {$ref: '#/components/responses/Unauthenticated'}472        '403': {$ref: '#/components/responses/Forbidden'}473        '404': {$ref: '#/components/responses/NotFound'}474  /me/devices:475    get:476      tags: [Auth]477      operationId: listMyDevices478      summary: List the devices of the current user479      x-permission: authenticated480      responses:481        '200':482          description: Devices.483          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}484          content: {application/json: {schema: {$ref: '#/components/schemas/DeviceList'}}}485        '401': {$ref: '#/components/responses/Unauthenticated'}486  /me/devices/{id}:487    parameters:488      - {$ref: '#/components/parameters/Id'}489    delete:490      tags: [Auth]491      operationId: revokeMyDevice492      summary: Revoke a device and all its sessions493      x-permission: authenticated494      parameters:495        - {$ref: '#/components/parameters/Csrf'}496      responses:497        '204':498          description: Device and sessions revoked.499          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}500        '401': {$ref: '#/components/responses/Unauthenticated'}501        '403': {$ref: '#/components/responses/Forbidden'}502        '404': {$ref: '#/components/responses/NotFound'}503  /me/devices/current/push-token:504    put:505      tags: [Auth]506      operationId: putMyPushToken507      summary: Register the APNs token of the current device508      description: Native clients only. The token is never logged nor returned.509      x-permission: authenticated510      parameters:511        - {$ref: '#/components/parameters/Csrf'}512      requestBody:513        required: true514        content: {application/json: {schema: {$ref: '#/components/schemas/PushTokenRequest'}}}515      responses:516        '200':517          description: Updated device.518          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}519          content: {application/json: {schema: {$ref: '#/components/schemas/Device'}}}520        '400': {$ref: '#/components/responses/BadRequest'}521        '401': {$ref: '#/components/responses/Unauthenticated'}522        '403': {$ref: '#/components/responses/Forbidden'}523  /permissions:524    get:525      tags: [Auth]526      operationId: getPermissionCatalog527      summary: Permission catalog and role defaults528      x-permission: authenticated529      responses:530        '200':531          description: Catalog.532          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}533          content: {application/json: {schema: {$ref: '#/components/schemas/PermissionCatalog'}}}534        '401': {$ref: '#/components/responses/Unauthenticated'}535536  # ───────────────────────────── Invitations ─────────────────────────────537  /invitations:538    get:539      tags: [Invitations]540      operationId: listInvitations541      summary: List invitations542      description: Never returns the token (only its SHA-256 hash is stored).543      x-permission: invitations.manage544      parameters:545        - {$ref: '#/components/parameters/Limit'}546        - {$ref: '#/components/parameters/Cursor'}547        - {name: status, in: query, schema: {$ref: '#/components/schemas/InvitationStatus'}}548      responses:549        '200':550          description: Invitations, most recent first.551          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}552          content: {application/json: {schema: {$ref: '#/components/schemas/InvitationList'}}}553        '400': {$ref: '#/components/responses/BadRequest'}554        '401': {$ref: '#/components/responses/Unauthenticated'}555        '403': {$ref: '#/components/responses/Forbidden'}556    post:557      tags: [Invitations]558      operationId: createInvitation559      summary: Create a single-use invitation560      description: |561        The token and `setup_url` are returned **once** and cannot be retrieved later. An admin can neither create562        nor target an `owner`. With `target_user_id` the invitation links to an existing account563        (see `POST /invitations/transaction/link`); `handle` and `display_name` are then ignored.564      x-permission: invitations.manage565      x-step-up: true566      parameters:567        - {$ref: '#/components/parameters/Csrf'}568      requestBody:569        required: true570        content:571          application/json:572            schema: {$ref: '#/components/schemas/CreateInvitationRequest'}573            example: {role: operator, handle: erika, display_name: Erika, ttl_minutes: 15, note: Night shift operator}574      responses:575        '201':576          description: Invitation created; token shown once.577          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}578          content:579            application/json:580              schema: {$ref: '#/components/schemas/InvitationCreated'}581              example:582                invitation:583                  id: 019a9c20-0000-7000-8000-0000000000e1584                  purpose: new_account585                  role: operator586                  handle: erika587                  display_name: Erika588                  note: Night shift operator589                  status: pending590                  failed_attempts: 0591                  created_by: 019a9b00-1111-7aaa-8bbb-000000000001592                  created_by_display_name: Simon-Pierre593                  created_at: '2026-11-18T21:10:00Z'594                  expires_at: '2026-11-18T21:25:00Z'595                token: 3Jm0b0y9i2mXw1o0mWm3d8l3bq6mV1r8kq2o7x9A5cE596                setup_url: https://clustr.spboucher.ai/setup#3Jm0b0y9i2mXw1o0mWm3d8l3bq6mV1r8kq2o7x9A5cE597        '400': {$ref: '#/components/responses/BadRequest'}598        '401': {$ref: '#/components/responses/Unauthenticated'}599        '403': {$ref: '#/components/responses/Forbidden'}600        '404': {$ref: '#/components/responses/NotFound'}601        '409': {$ref: '#/components/responses/Conflict'}602  /invitations/{id}:603    parameters:604      - {$ref: '#/components/parameters/Id'}605    delete:606      tags: [Invitations]607      operationId: revokeInvitation608      summary: Revoke an invitation609      description: Also invalidates an open setup transaction of this invitation.610      x-permission: invitations.manage611      x-step-up: true612      parameters:613        - {$ref: '#/components/parameters/Csrf'}614      responses:615        '204':616          description: Invitation revoked.617          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}618        '401': {$ref: '#/components/responses/Unauthenticated'}619        '403': {$ref: '#/components/responses/Forbidden'}620        '404': {$ref: '#/components/responses/NotFound'}621        '409': {$ref: '#/components/responses/Conflict'}622  /invitations/exchange:623    post:624      tags: [Invitations]625      operationId: exchangeInvitation626      summary: Exchange an invitation token for a setup transaction627      description: |628        Unauthenticated. Consumes the token **atomically** and opens a 10-minute setup transaction. Web clients629        receive the cookie `__Host-mcc_setup`; native clients (`client.kind` other than `web`) receive630        `transaction_token`, to be sent in the header `X-MCC-Setup-Transaction`. Unknown, expired, consumed or631        revoked tokens all answer `410 gone`. Five failed attempts revoke the invitation.632        Rate limit: 5 requests per minute per IP.633      x-permission: none634      security: []635      requestBody:636        required: true637        content: {application/json: {schema: {$ref: '#/components/schemas/InvitationExchangeRequest'}}}638      responses:639        '200':640          description: Transaction opened.641          headers:642            X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}643            Set-Cookie:644              description: '`__Host-mcc_setup=<opaque>; Secure; HttpOnly; SameSite=Strict; Path=/; Max-Age=600` (web clients only).'645              schema: {type: string}646          content: {application/json: {schema: {$ref: '#/components/schemas/InvitationTransaction'}}}647        '400': {$ref: '#/components/responses/BadRequest'}648        '410': {$ref: '#/components/responses/Gone'}649        '429': {$ref: '#/components/responses/RateLimited'}650  /invitations/transaction:651    get:652      tags: [Invitations]653      operationId: getInvitationTransaction654      summary: Current setup transaction655      x-permission: none656      security:657        - setupCookie: []658        - setupHeader: []659      responses:660        '200':661          description: Transaction (never includes `transaction_token`).662          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}663          content: {application/json: {schema: {$ref: '#/components/schemas/InvitationTransaction'}}}664        '401': {$ref: '#/components/responses/Unauthenticated'}665        '410': {$ref: '#/components/responses/Gone'}666    delete:667      tags: [Invitations]668      operationId: abandonInvitationTransaction669      summary: Abandon the setup transaction670      description: The invitation stays consumed; a new invitation is needed.671      x-permission: none672      security:673        - setupCookie: []674        - setupHeader: []675      responses:676        '204':677          description: Transaction closed; setup cookie cleared.678          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}679        '401': {$ref: '#/components/responses/Unauthenticated'}680  /invitations/transaction/profile:681    post:682      tags: [Invitations]683      operationId: setInvitationProfile684      summary: Choose handle and display name for the new account685      description: Only accepted for the fields the invitation left open. `409 conflict` when the handle is taken.686      x-permission: none687      security:688        - setupCookie: []689        - setupHeader: []690      requestBody:691        required: true692        content: {application/json: {schema: {$ref: '#/components/schemas/InvitationProfileRequest'}}}693      responses:694        '200':695          description: Updated transaction.696          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}697          content: {application/json: {schema: {$ref: '#/components/schemas/InvitationTransaction'}}}698        '400': {$ref: '#/components/responses/BadRequest'}699        '401': {$ref: '#/components/responses/Unauthenticated'}700        '409': {$ref: '#/components/responses/Conflict'}701        '410': {$ref: '#/components/responses/Gone'}702  /invitations/transaction/link:703    post:704      tags: [Invitations]705      operationId: linkInvitationToAccount706      summary: Apply the invitation to the existing target account707      description: |708        Only for invitations created with `target_user_id` (`requires_existing_account=true`). Requires **both** the709        setup transaction and an authenticated session **of the target account** with a valid step-up, plus the710        explicit confirmation in the body. Applies the invited role to the account and completes the invitation.711        There is never an implicit merge by handle: a session of another account is `403 forbidden`.712      x-permission: authenticated713      x-step-up: true714      security:715        - cookieSession: []716          setupCookie: []717        - bearer: []718          setupHeader: []719      parameters:720        - {$ref: '#/components/parameters/Csrf'}721      requestBody:722        required: true723        content: {application/json: {schema: {$ref: '#/components/schemas/InvitationLinkRequest'}}}724      responses:725        '200':726          description: Invitation applied to the account.727          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}728          content: {application/json: {schema: {$ref: '#/components/schemas/InvitationLinkResult'}}}729        '400': {$ref: '#/components/responses/BadRequest'}730        '401': {$ref: '#/components/responses/Unauthenticated'}731        '403': {$ref: '#/components/responses/Forbidden'}732        '409': {$ref: '#/components/responses/Conflict'}733        '410': {$ref: '#/components/responses/Gone'}734735  # ───────────────────────────── Admin ─────────────────────────────736  /users:737    get:738      tags: [Admin]739      operationId: listUsers740      summary: List users741      x-permission: users.manage742      parameters:743        - {$ref: '#/components/parameters/Limit'}744        - {$ref: '#/components/parameters/Cursor'}745        - {$ref: '#/components/parameters/Q'}746        - {name: role, in: query, schema: {$ref: '#/components/schemas/UserRole'}}747        - {name: disabled, in: query, schema: {type: boolean}}748      responses:749        '200':750          description: Users.751          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}752          content: {application/json: {schema: {$ref: '#/components/schemas/UserList'}}}753        '400': {$ref: '#/components/responses/BadRequest'}754        '401': {$ref: '#/components/responses/Unauthenticated'}755        '403': {$ref: '#/components/responses/Forbidden'}756  /users/{id}:757    parameters:758      - {$ref: '#/components/parameters/Id'}759    get:760      tags: [Admin]761      operationId: getUser762      summary: Get a user763      x-permission: users.manage764      responses:765        '200':766          description: User.767          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}768          content: {application/json: {schema: {$ref: '#/components/schemas/User'}}}769        '401': {$ref: '#/components/responses/Unauthenticated'}770        '403': {$ref: '#/components/responses/Forbidden'}771        '404': {$ref: '#/components/responses/NotFound'}772    patch:773      tags: [Admin]774      operationId: updateUser775      summary: Change the role of a user, or disable / enable the account776      description: |777        An admin can neither modify an owner nor grant the `owner` role. Disabling a user revokes all its sessions.778        Demoting or disabling the last enabled owner is `409 conflict`.779      x-permission: users.manage780      x-step-up: true781      parameters:782        - {$ref: '#/components/parameters/Csrf'}783      requestBody:784        required: true785        content: {application/json: {schema: {$ref: '#/components/schemas/UpdateUserRequest'}}}786      responses:787        '200':788          description: Updated user.789          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}790          content: {application/json: {schema: {$ref: '#/components/schemas/User'}}}791        '400': {$ref: '#/components/responses/BadRequest'}792        '401': {$ref: '#/components/responses/Unauthenticated'}793        '403': {$ref: '#/components/responses/Forbidden'}794        '404': {$ref: '#/components/responses/NotFound'}795        '409': {$ref: '#/components/responses/Conflict'}796  /users/{id}/passkeys:797    parameters:798      - {$ref: '#/components/parameters/Id'}799    get:800      tags: [Admin]801      operationId: listUserPasskeys802      summary: List the passkeys of a user803      x-permission: users.manage804      responses:805        '200':806          description: Passkeys, revoked ones included.807          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}808          content: {application/json: {schema: {$ref: '#/components/schemas/PasskeyList'}}}809        '401': {$ref: '#/components/responses/Unauthenticated'}810        '403': {$ref: '#/components/responses/Forbidden'}811        '404': {$ref: '#/components/responses/NotFound'}812  /users/{id}/passkeys/{passkeyId}:813    parameters:814      - {$ref: '#/components/parameters/Id'}815      - {name: passkeyId, in: path, required: true, schema: {type: string, format: uuid}}816    delete:817      tags: [Admin]818      operationId: revokeUserPasskey819      summary: Revoke a passkey of a user820      description: 'Refuses to revoke the last active passkey (`409 last_passkey`); disable the account instead.'821      x-permission: users.manage822      x-step-up: true823      parameters:824        - {$ref: '#/components/parameters/Csrf'}825      responses:826        '204':827          description: Passkey revoked.828          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}829        '401': {$ref: '#/components/responses/Unauthenticated'}830        '403': {$ref: '#/components/responses/Forbidden'}831        '404': {$ref: '#/components/responses/NotFound'}832        '409': {$ref: '#/components/responses/Conflict'}833  /users/{id}/sessions:834    parameters:835      - {$ref: '#/components/parameters/Id'}836    get:837      tags: [Admin]838      operationId: listUserSessions839      summary: List the active sessions of a user840      x-permission: users.manage841      responses:842        '200':843          description: Sessions.844          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}845          content: {application/json: {schema: {$ref: '#/components/schemas/SessionList'}}}846        '401': {$ref: '#/components/responses/Unauthenticated'}847        '403': {$ref: '#/components/responses/Forbidden'}848        '404': {$ref: '#/components/responses/NotFound'}849  /sessions/{id}:850    parameters:851      - {$ref: '#/components/parameters/Id'}852    delete:853      tags: [Admin]854      operationId: revokeSession855      summary: Revoke any session856      x-permission: users.manage857      x-step-up: true858      parameters:859        - {$ref: '#/components/parameters/Csrf'}860      responses:861        '204':862          description: Session revoked.863          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}864        '401': {$ref: '#/components/responses/Unauthenticated'}865        '403': {$ref: '#/components/responses/Forbidden'}866        '404': {$ref: '#/components/responses/NotFound'}867  /users/{id}/devices:868    parameters:869      - {$ref: '#/components/parameters/Id'}870    get:871      tags: [Admin]872      operationId: listUserDevices873      summary: List the devices of a user874      x-permission: users.manage875      responses:876        '200':877          description: Devices.878          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}879          content: {application/json: {schema: {$ref: '#/components/schemas/DeviceList'}}}880        '401': {$ref: '#/components/responses/Unauthenticated'}881        '403': {$ref: '#/components/responses/Forbidden'}882        '404': {$ref: '#/components/responses/NotFound'}883  /devices/{id}:884    parameters:885      - {$ref: '#/components/parameters/Id'}886    delete:887      tags: [Admin]888      operationId: revokeDevice889      summary: Revoke any device and all its sessions890      x-permission: users.manage891      x-step-up: true892      parameters:893        - {$ref: '#/components/parameters/Csrf'}894      responses:895        '204':896          description: Device and sessions revoked.897          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}898        '401': {$ref: '#/components/responses/Unauthenticated'}899        '403': {$ref: '#/components/responses/Forbidden'}900        '404': {$ref: '#/components/responses/NotFound'}901  /policy-grants:902    get:903      tags: [Admin]904      operationId: listPolicyGrants905      summary: List policy grants906      x-permission: users.manage907      parameters:908        - {$ref: '#/components/parameters/Limit'}909        - {$ref: '#/components/parameters/Cursor'}910        - {name: subject_kind, in: query, schema: {$ref: '#/components/schemas/GrantSubjectKind'}}911        - {name: subject, in: query, schema: {type: string}}912        - {name: permission, in: query, schema: {type: string}}913      responses:914        '200':915          description: Grants.916          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}917          content: {application/json: {schema: {$ref: '#/components/schemas/PolicyGrantList'}}}918        '400': {$ref: '#/components/responses/BadRequest'}919        '401': {$ref: '#/components/responses/Unauthenticated'}920        '403': {$ref: '#/components/responses/Forbidden'}921    post:922      tags: [Admin]923      operationId: createPolicyGrant924      summary: Create an allow / deny grant925      description: 'Deny wins over allow. An admin cannot grant a permission it does not hold itself, nor target an owner.'926      x-permission: users.manage927      x-step-up: true928      parameters:929        - {$ref: '#/components/parameters/Csrf'}930      requestBody:931        required: true932        content:933          application/json:934            schema: {$ref: '#/components/schemas/CreatePolicyGrantRequest'}935            example: {subject_kind: role, subject: operator, permission: actions.run.medium, resource_kind: node, resource_id: 019a9b10-0000-7000-8000-000000000a01, effect: deny}936      responses:937        '201':938          description: Grant created.939          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}940          content: {application/json: {schema: {$ref: '#/components/schemas/PolicyGrant'}}}941        '400': {$ref: '#/components/responses/BadRequest'}942        '401': {$ref: '#/components/responses/Unauthenticated'}943        '403': {$ref: '#/components/responses/Forbidden'}944        '409': {$ref: '#/components/responses/Conflict'}945  /policy-grants/{id}:946    parameters:947      - {$ref: '#/components/parameters/Id'}948    delete:949      tags: [Admin]950      operationId: deletePolicyGrant951      summary: Delete a grant952      x-permission: users.manage953      x-step-up: true954      parameters:955        - {$ref: '#/components/parameters/Csrf'}956      responses:957        '204':958          description: Grant deleted.959          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}960        '401': {$ref: '#/components/responses/Unauthenticated'}961        '403': {$ref: '#/components/responses/Forbidden'}962        '404': {$ref: '#/components/responses/NotFound'}963  /agents:964    get:965      tags: [Admin]966      operationId: listAgents967      summary: List enrolled agents968      x-permission: agents.manage969      parameters:970        - {$ref: '#/components/parameters/Limit'}971        - {$ref: '#/components/parameters/Cursor'}972        - {name: node_id, in: query, schema: {type: string, format: uuid}}973        - {name: revoked, in: query, description: Include revoked agents (default false)., schema: {type: boolean, default: false}}974      responses:975        '200':976          description: Agents.977          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}978          content: {application/json: {schema: {$ref: '#/components/schemas/AgentList'}}}979        '400': {$ref: '#/components/responses/BadRequest'}980        '401': {$ref: '#/components/responses/Unauthenticated'}981        '403': {$ref: '#/components/responses/Forbidden'}982  /agents/enrollment-tokens:983    get:984      tags: [Admin]985      operationId: listEnrollmentTokens986      summary: List agent enrollment tokens987      description: Never returns the token value.988      x-permission: agents.manage989      parameters:990        - {$ref: '#/components/parameters/Limit'}991        - {$ref: '#/components/parameters/Cursor'}992      responses:993        '200':994          description: Enrollment tokens, most recent first.995          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}996          content: {application/json: {schema: {$ref: '#/components/schemas/EnrollmentTokenList'}}}997        '400': {$ref: '#/components/responses/BadRequest'}998        '401': {$ref: '#/components/responses/Unauthenticated'}999        '403': {$ref: '#/components/responses/Forbidden'}1000    post:1001      tags: [Admin]1002      operationId: createEnrollmentToken1003      summary: Create a single-use agent enrollment token1004      description: The token is returned **once**, with an install hint. Default TTL 15 minutes.1005      x-permission: agents.manage1006      x-step-up: true1007      parameters:1008        - {$ref: '#/components/parameters/Csrf'}1009      requestBody:1010        required: true1011        content:1012          application/json:1013            schema: {$ref: '#/components/schemas/CreateEnrollmentTokenRequest'}1014            example: {node_alias: m4mn, node_kind: mac, ttl_minutes: 15}1015      responses:1016        '201':1017          description: Token created; shown once.1018          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1019          content: {application/json: {schema: {$ref: '#/components/schemas/EnrollmentTokenCreated'}}}1020        '400': {$ref: '#/components/responses/BadRequest'}1021        '401': {$ref: '#/components/responses/Unauthenticated'}1022        '403': {$ref: '#/components/responses/Forbidden'}1023        '409': {$ref: '#/components/responses/Conflict'}1024  /agents/enrollment-tokens/{id}:1025    parameters:1026      - {$ref: '#/components/parameters/Id'}1027    delete:1028      tags: [Admin]1029      operationId: revokeEnrollmentToken1030      summary: Revoke an unused enrollment token1031      x-permission: agents.manage1032      x-step-up: true1033      parameters:1034        - {$ref: '#/components/parameters/Csrf'}1035      responses:1036        '204':1037          description: Token revoked.1038          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1039        '401': {$ref: '#/components/responses/Unauthenticated'}1040        '403': {$ref: '#/components/responses/Forbidden'}1041        '404': {$ref: '#/components/responses/NotFound'}1042  /agents/{id}/revoke:1043    parameters:1044      - {$ref: '#/components/parameters/Id'}1045    post:1046      tags: [Admin]1047      operationId: revokeAgent1048      summary: Revoke an agent certificate1049      description: The agent can no longer report nor receive commands; a new enrollment is required.1050      x-permission: agents.manage1051      x-step-up: true1052      parameters:1053        - {$ref: '#/components/parameters/Csrf'}1054      requestBody:1055        required: true1056        content: {application/json: {schema: {$ref: '#/components/schemas/RevokeAgentRequest'}}}1057      responses:1058        '200':1059          description: Revoked agent.1060          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1061          content: {application/json: {schema: {$ref: '#/components/schemas/Agent'}}}1062        '400': {$ref: '#/components/responses/BadRequest'}1063        '401': {$ref: '#/components/responses/Unauthenticated'}1064        '403': {$ref: '#/components/responses/Forbidden'}1065        '404': {$ref: '#/components/responses/NotFound'}1066        '409': {$ref: '#/components/responses/Conflict'}1067  /settings:1068    get:1069      tags: [Admin]1070      operationId: listSettings1071      summary: List settings1072      x-permission: settings.manage1073      responses:1074        '200':1075          description: All settings (retention, thresholds, `orchestrator.frozen`...).1076          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1077          content: {application/json: {schema: {$ref: '#/components/schemas/SettingList'}}}1078        '401': {$ref: '#/components/responses/Unauthenticated'}1079        '403': {$ref: '#/components/responses/Forbidden'}1080  /settings/{key}:1081    parameters:1082      - {name: key, in: path, required: true, description: 'Setting key, for example `retention.raw_days`.', schema: {type: string, pattern: '^[a-z0-9][a-z0-9_.]{0,63}$'}}1083    put:1084      tags: [Admin]1085      operationId: putSetting1086      summary: Set a setting1087      description: 'Unknown keys are `404`. The key `orchestrator.frozen` (emergency stop) can only be changed by an owner.'1088      x-permission: settings.manage1089      x-step-up: true1090      parameters:1091        - {$ref: '#/components/parameters/Csrf'}1092      requestBody:1093        required: true1094        content:1095          application/json:1096            schema: {$ref: '#/components/schemas/PutSettingRequest'}1097            example: {value: 7}1098      responses:1099        '200':1100          description: Updated setting.1101          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1102          content: {application/json: {schema: {$ref: '#/components/schemas/Setting'}}}1103        '400': {$ref: '#/components/responses/BadRequest'}1104        '401': {$ref: '#/components/responses/Unauthenticated'}1105        '403': {$ref: '#/components/responses/Forbidden'}1106        '404': {$ref: '#/components/responses/NotFound'}1107  /admin/status:1108    get:1109      tags: [Admin]1110      operationId: getAdminStatus1111      summary: Backend health1112      description: Database, ingest and orchestrator heartbeats, last successful backup, version and frozen flag.1113      x-permission: settings.manage1114      responses:1115        '200':1116          description: Backend status.1117          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1118          content: {application/json: {schema: {$ref: '#/components/schemas/AdminStatus'}}}1119        '401': {$ref: '#/components/responses/Unauthenticated'}1120        '403': {$ref: '#/components/responses/Forbidden'}11211122  # ───────────────────────────── Cluster ─────────────────────────────1123  /cluster/overview:1124    get:1125      tags: [Cluster]1126      operationId: getClusterOverview1127      summary: Cluster overview1128      description: |1129        Aggregated snapshot. Capacity totals only sum what agents actually report: `coverage` is the number of nodes1130        contributing to each total, to be compared with `nodes.total`. Sections the caller cannot read1131        (for example `recent_actions` without `actions.read`) are omitted.1132      x-permission: cluster.read1133      responses:1134        '200':1135          description: Overview.1136          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1137          content:1138            application/json:1139              schema: {$ref: '#/components/schemas/ClusterOverview'}1140              example:1141                generated_at: '2026-11-18T21:15:00Z'1142                nodes: {total: 30, fresh: 27, stale: 1, offline: 2, maintenance: 1}1143                capacity:1144                  cpu_cores: {total: 379, coverage: 28}1145                  memory: {total: 1108101562368, used: 402122547200, coverage: 28}1146                  storage: {total: 14629000000000, used: 5310000000000, coverage: 28}1147                alerts: {info: 0, warning: 3, critical: 1}1148                open_incidents: 11149                jobs: {queued: 0, running: 2}1150                services: {online: 93, stopped: 4, errored: 7, unknown: 0}1151                models: {total: 2, online: 2}1152                nas: {total: 2, online: 1, offline: 1, unknown: 0}1153                backups: {total: 6, ok: 4, failed: 1, unknown: 1, last_success_at: '2026-11-18T08:00:11Z'}1154                recent_actions: []1155        '401': {$ref: '#/components/responses/Unauthenticated'}1156        '403': {$ref: '#/components/responses/Forbidden'}1157  /cluster/trends:1158    get:1159      tags: [Cluster]1160      operationId: getClusterTrends1161      summary: Aggregated metric trend1162      description: 'Aggregates one metric across nodes over a range. Resolution is chosen by the server (1h: raw 10 s buckets; 24h: 1 min; 7d and 30d: 1 h).'1163      x-permission: cluster.read1164      parameters:1165        - {name: metric, in: query, required: true, description: 'Metric name from `GET /metrics/catalog`, for example `cpu.usage`.', schema: {type: string}}1166        - {name: range, in: query, schema: {$ref: '#/components/schemas/TimeRange'}}1167        - {name: group_by, in: query, schema: {$ref: '#/components/schemas/TrendGroupBy'}}1168      responses:1169        '200':1170          description: Aggregated series.1171          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1172          content: {application/json: {schema: {$ref: '#/components/schemas/TrendsResponse'}}}1173        '400': {$ref: '#/components/responses/BadRequest'}1174        '401': {$ref: '#/components/responses/Unauthenticated'}1175        '403': {$ref: '#/components/responses/Forbidden'}11761177  # ───────────────────────────── Nodes ─────────────────────────────1178  /nodes:1179    get:1180      tags: [Nodes]1181      operationId: listNodes1182      summary: List nodes1183      description: 'Private fields (`primary_ip`) are only present with `nodes.private.read`. Retired nodes are excluded unless `retired=true`.'1184      x-permission: nodes.read1185      parameters:1186        - {$ref: '#/components/parameters/Limit'}1187        - {$ref: '#/components/parameters/Cursor'}1188        - {$ref: '#/components/parameters/Q'}1189        - {name: site, in: query, schema: {type: string}}1190        - {name: role, in: query, schema: {type: string}}1191        - {name: tag, in: query, schema: {type: string}}1192        - {name: kind, in: query, schema: {$ref: '#/components/schemas/NodeKind'}}1193        - {name: freshness, in: query, schema: {$ref: '#/components/schemas/Freshness'}}1194        - {name: maintenance, in: query, schema: {type: boolean}}1195        - {name: retired, in: query, schema: {type: boolean, default: false}}1196        - {name: sort, in: query, schema: {type: string, enum: [alias, site, role, last_seen, cpu, memory, disk], default: alias}}1197        - {$ref: '#/components/parameters/Order'}1198      responses:1199        '200':1200          description: Nodes.1201          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1202          content:1203            application/json:1204              schema: {$ref: '#/components/schemas/NodeList'}1205              example:1206                items:1207                  - id: 019a9b10-0000-7000-8000-000000000a011208                    alias: M3U96a1209                    kind: mac1210                    hostname: MacStudio-de-simon-pierre-21211                    site: default1212                    role: worker1213                    environment: production1214                    tags: [studio, inference]1215                    model: Mac15,141216                    chip: Apple M3 Ultra1217                    arch: arm641218                    cpu_cores: 281219                    gpu_cores: 601220                    mem_bytes: 1030792151041221                    storage_bytes: 9946625843201222                    os_name: macOS1223                    os_version: '26.6'1224                    registered_via: agent1225                    maintenance: false1226                    maintenance_reason: ''1227                    created_at: '2026-11-18T20:45:00Z'1228                    last_seen_at: '2026-11-18T21:14:55Z'1229                    observed_at: '2026-11-18T21:14:55Z'1230                    freshness: fresh1231                    agent_version: 1.0.01232                    headline: {cpu_usage_pct: 12.4, mem_used_pct: 41.8, disk_used_pct: 78.3, load1: 3.1}1233                  - id: 019a9b10-0000-7000-8000-000000000a091234                    alias: M4BP361235                    kind: mac1236                    hostname: ''1237                    site: default1238                    role: worker1239                    environment: production1240                    tags: [laptop]1241                    registered_via: manual1242                    maintenance: false1243                    maintenance_reason: ''1244                    created_at: '2026-11-18T20:45:00Z'1245                    freshness: offline1246        '400': {$ref: '#/components/responses/BadRequest'}1247        '401': {$ref: '#/components/responses/Unauthenticated'}1248        '403': {$ref: '#/components/responses/Forbidden'}1249    post:1250      tags: [Nodes]1251      operationId: createNode1252      summary: Register a node manually1253      description: |1254        Creates a node with `registered_via=manual`, before any agent has spoken (`freshness=offline`). Expected1255        hardware is informative and is replaced by the first agent inventory. `409 conflict` when the alias exists.1256      x-permission: nodes.write1257      parameters:1258        - {$ref: '#/components/parameters/Csrf'}1259      requestBody:1260        required: true1261        content:1262          application/json:1263            schema: {$ref: '#/components/schemas/CreateNodeRequest'}1264            example: {alias: M4BP36, kind: mac, site: default, role: worker, tags: [laptop], expected: {model: MacBook Pro, cpu_cores: 14, mem_bytes: 38654705664}}1265      responses:1266        '201':1267          description: Node created.1268          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1269          content: {application/json: {schema: {$ref: '#/components/schemas/Node'}}}1270        '400': {$ref: '#/components/responses/BadRequest'}1271        '401': {$ref: '#/components/responses/Unauthenticated'}1272        '403': {$ref: '#/components/responses/Forbidden'}1273        '409': {$ref: '#/components/responses/Conflict'}1274  /nodes/{id}:1275    parameters:1276      - {$ref: '#/components/parameters/Id'}1277    get:1278      tags: [Nodes]1279      operationId: getNode1280      summary: Node detail1281      description: 'Inventory (interfaces, volumes, CPU performance levels), agent and latest values with per-metric availability. Addresses, MAC, serial number and hardware UUID require `nodes.private.read`.'1282      x-permission: nodes.read1283      responses:1284        '200':1285          description: Node detail.1286          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1287          content: {application/json: {schema: {$ref: '#/components/schemas/NodeDetail'}}}1288        '401': {$ref: '#/components/responses/Unauthenticated'}1289        '403': {$ref: '#/components/responses/Forbidden'}1290        '404': {$ref: '#/components/responses/NotFound'}1291    patch:1292      tags: [Nodes]1293      operationId: updateNode1294      summary: Update the alias, site, role, environment or tags of a node1295      description: 'Maintenance mode is not set here: use the action `node.maintenance.set` or a maintenance window.'1296      x-permission: nodes.write1297      parameters:1298        - {$ref: '#/components/parameters/Csrf'}1299      requestBody:1300        required: true1301        content: {application/json: {schema: {$ref: '#/components/schemas/UpdateNodeRequest'}}}1302      responses:1303        '200':1304          description: Updated node.1305          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1306          content: {application/json: {schema: {$ref: '#/components/schemas/Node'}}}1307        '400': {$ref: '#/components/responses/BadRequest'}1308        '401': {$ref: '#/components/responses/Unauthenticated'}1309        '403': {$ref: '#/components/responses/Forbidden'}1310        '404': {$ref: '#/components/responses/NotFound'}1311        '409': {$ref: '#/components/responses/Conflict'}1312    delete:1313      tags: [Nodes]1314      operationId: retireNode1315      summary: Retire a node1316      description: Sets `retired_at`, revokes the agent of the node and resolves its open alerts. History is kept.1317      x-permission: nodes.write1318      x-step-up: true1319      parameters:1320        - {$ref: '#/components/parameters/Csrf'}1321      responses:1322        '204':1323          description: Node retired.1324          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1325        '401': {$ref: '#/components/responses/Unauthenticated'}1326        '403': {$ref: '#/components/responses/Forbidden'}1327        '404': {$ref: '#/components/responses/NotFound'}1328        '409': {$ref: '#/components/responses/Conflict'}1329  /nodes/{id}/metrics:1330    parameters:1331      - {$ref: '#/components/parameters/Id'}1332    get:1333      tags: [Nodes]1334      operationId: getNodeMetrics1335      summary: Metric series of a node1336      description: |1337        `resolution=auto` picks raw (10 s) up to 2 h, 1 min up to 48 h, 1 h beyond, within retention (raw 7 days,1338        1 min 30 days, 1 h 400 days). Points are `[ts_ms, avg, min, max]`; at raw resolution avg = min = max.1339        Gaps are real gaps (no interpolation, no zero fill). At most 12 metrics and 5000 points per series.1340      x-permission: nodes.read1341      parameters:1342        - {name: metrics, in: query, required: true, description: Comma-separated metric names., style: form, explode: false, schema: {type: array, minItems: 1, maxItems: 12, items: {type: string}}}1343        - {$ref: '#/components/parameters/From'}1344        - {$ref: '#/components/parameters/To'}1345        - {name: resolution, in: query, schema: {$ref: '#/components/schemas/Resolution'}}1346        - {name: label, in: query, description: 'Label filter for labeled metrics (interface name, mount point...). All labels when omitted.', schema: {type: string}}1347      responses:1348        '200':1349          description: Series.1350          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1351          content:1352            application/json:1353              schema: {$ref: '#/components/schemas/MetricSeriesResponse'}1354              example:1355                resolution: 1m1356                from: '2026-11-18T20:15:00Z'1357                to: '2026-11-18T21:15:00Z'1358                series:1359                  - metric: cpu.usage1360                    unit: percent1361                    label: ''1362                    points: [[1795033200000, 12.4, 8.1, 19.7], [1795033260000, 14.0, 9.3, 22.5]]1363                availability: {cpu.usage: available, thermal.temp: permission_denied}1364        '400': {$ref: '#/components/responses/BadRequest'}1365        '401': {$ref: '#/components/responses/Unauthenticated'}1366        '403': {$ref: '#/components/responses/Forbidden'}1367        '404': {$ref: '#/components/responses/NotFound'}1368  /metrics/compare:1369    get:1370      tags: [Nodes]1371      operationId: compareMetrics1372      summary: Compare one metric across several nodes1373      x-permission: nodes.read1374      parameters:1375        - {name: node_ids, in: query, required: true, description: Comma-separated node ids (2 to 12)., style: form, explode: false, schema: {type: array, minItems: 1, maxItems: 12, items: {type: string, format: uuid}}}1376        - {name: metric, in: query, required: true, schema: {type: string}}1377        - {$ref: '#/components/parameters/From'}1378        - {$ref: '#/components/parameters/To'}1379        - {name: resolution, in: query, schema: {$ref: '#/components/schemas/Resolution'}}1380        - {name: label, in: query, schema: {type: string}}1381      responses:1382        '200':1383          description: One series per node (and per label).1384          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1385          content: {application/json: {schema: {$ref: '#/components/schemas/MetricCompareResponse'}}}1386        '400': {$ref: '#/components/responses/BadRequest'}1387        '401': {$ref: '#/components/responses/Unauthenticated'}1388        '403': {$ref: '#/components/responses/Forbidden'}1389  /metrics/catalog:1390    get:1391      tags: [Nodes]1392      operationId: getMetricCatalog1393      summary: Metric catalog1394      x-permission: nodes.read1395      responses:1396        '200':1397          description: Every metric with unit, interval and provenance.1398          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1399          content: {application/json: {schema: {$ref: '#/components/schemas/MetricCatalog'}}}1400        '401': {$ref: '#/components/responses/Unauthenticated'}1401        '403': {$ref: '#/components/responses/Forbidden'}1402  /nodes/{id}/processes:1403    parameters:1404      - {$ref: '#/components/parameters/Id'}1405    get:1406      tags: [Nodes]1407      operationId: listNodeProcesses1408      summary: Top processes of a node1409      description: Last top-N snapshot reported by the agent (at most 15 processes). Command lines are redacted by the agent.1410      x-permission: nodes.read1411      responses:1412        '200':1413          description: Processes.1414          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1415          content: {application/json: {schema: {$ref: '#/components/schemas/ProcessList'}}}1416        '401': {$ref: '#/components/responses/Unauthenticated'}1417        '403': {$ref: '#/components/responses/Forbidden'}1418        '404': {$ref: '#/components/responses/NotFound'}1419  /nodes/{id}/services:1420    parameters:1421      - {$ref: '#/components/parameters/Id'}1422    get:1423      tags: [Nodes]1424      operationId: listNodeServices1425      summary: Services of a node1426      x-permission: services.read1427      parameters:1428        - {$ref: '#/components/parameters/Limit'}1429        - {$ref: '#/components/parameters/Cursor'}1430      responses:1431        '200':1432          description: Services.1433          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1434          content: {application/json: {schema: {$ref: '#/components/schemas/ServiceList'}}}1435        '400': {$ref: '#/components/responses/BadRequest'}1436        '401': {$ref: '#/components/responses/Unauthenticated'}1437        '403': {$ref: '#/components/responses/Forbidden'}1438        '404': {$ref: '#/components/responses/NotFound'}1439  /nodes/{id}/health-history:1440    parameters:1441      - {$ref: '#/components/parameters/Id'}1442    get:1443      tags: [Nodes]1444      operationId: getNodeHealthHistory1445      summary: Health history of a node1446      description: Buckets of reachability (derived from received reports), maintenance and firing alerts.1447      x-permission: nodes.read1448      parameters:1449        - {name: range, in: query, schema: {$ref: '#/components/schemas/TimeRange'}}1450      responses:1451        '200':1452          description: Health buckets, oldest first.1453          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1454          content: {application/json: {schema: {$ref: '#/components/schemas/HealthHistory'}}}1455        '400': {$ref: '#/components/responses/BadRequest'}1456        '401': {$ref: '#/components/responses/Unauthenticated'}1457        '403': {$ref: '#/components/responses/Forbidden'}1458        '404': {$ref: '#/components/responses/NotFound'}14591460  # ───────────────────────────── Services ─────────────────────────────1461  /services:1462    get:1463      tags: [Services]1464      operationId: listServices1465      summary: List services1466      x-permission: services.read1467      parameters:1468        - {$ref: '#/components/parameters/Limit'}1469        - {$ref: '#/components/parameters/Cursor'}1470        - {$ref: '#/components/parameters/Q'}1471        - {name: node_id, in: query, schema: {type: string, format: uuid}}1472        - {name: manager, in: query, schema: {$ref: '#/components/schemas/ServiceManager'}}1473        - {name: state, in: query, schema: {$ref: '#/components/schemas/ServiceState'}}1474        - {name: app, in: query, description: Logical application name., schema: {type: string}}1475        - {name: managed, in: query, schema: {type: boolean}}1476      responses:1477        '200':1478          description: Services.1479          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1480          content: {application/json: {schema: {$ref: '#/components/schemas/ServiceList'}}}1481        '400': {$ref: '#/components/responses/BadRequest'}1482        '401': {$ref: '#/components/responses/Unauthenticated'}1483        '403': {$ref: '#/components/responses/Forbidden'}1484  /services/{id}:1485    parameters:1486      - {$ref: '#/components/parameters/Id'}1487    get:1488      tags: [Services]1489      operationId: getService1490      summary: Get a service1491      x-permission: services.read1492      responses:1493        '200':1494          description: Service.1495          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1496          content: {application/json: {schema: {$ref: '#/components/schemas/Service'}}}1497        '401': {$ref: '#/components/responses/Unauthenticated'}1498        '403': {$ref: '#/components/responses/Forbidden'}1499        '404': {$ref: '#/components/responses/NotFound'}1500    patch:1501      tags: [Services]1502      operationId: updateService1503      summary: Set the managed flag or the public URL of a service1504      description: '`managed=true` puts the service on the server allowlist for start / stop / restart actions; the agent must also allow it locally.'1505      x-permission: settings.manage1506      parameters:1507        - {$ref: '#/components/parameters/Csrf'}1508      requestBody:1509        required: true1510        content: {application/json: {schema: {$ref: '#/components/schemas/UpdateServiceRequest'}}}1511      responses:1512        '200':1513          description: Updated service.1514          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1515          content: {application/json: {schema: {$ref: '#/components/schemas/Service'}}}1516        '400': {$ref: '#/components/responses/BadRequest'}1517        '401': {$ref: '#/components/responses/Unauthenticated'}1518        '403': {$ref: '#/components/responses/Forbidden'}1519        '404': {$ref: '#/components/responses/NotFound'}1520  /services/{id}/history:1521    parameters:1522      - {$ref: '#/components/parameters/Id'}1523    get:1524      tags: [Services]1525      operationId: getServiceHistory1526      summary: Timeline of a service1527      description: Restarts, state changes, actions and deployments, most recent first.1528      x-permission: services.read1529      parameters:1530        - {$ref: '#/components/parameters/Limit'}1531        - {$ref: '#/components/parameters/Cursor'}1532      responses:1533        '200':1534          description: Timeline.1535          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1536          content: {application/json: {schema: {$ref: '#/components/schemas/ServiceHistory'}}}1537        '400': {$ref: '#/components/responses/BadRequest'}1538        '401': {$ref: '#/components/responses/Unauthenticated'}1539        '403': {$ref: '#/components/responses/Forbidden'}1540        '404': {$ref: '#/components/responses/NotFound'}15411542  # ───────────────────────────── Models ─────────────────────────────1543  /models:1544    get:1545      tags: [Models]1546      operationId: listInferenceServers1547      summary: List inference servers1548      description: |1549        Only what is observable is reported: process (RSS, uptime), port, health of `GET /v1/models`, model of the1550        command line, size of the model cache. `metrics_support` states explicitly, per metric family, whether the1551        server exposes it; for `mlx_lm.server` requests, tokens per second, TTFT, latency and queue are all1552        `unsupported` with a reason.1553      x-permission: models.read1554      parameters:1555        - {$ref: '#/components/parameters/Limit'}1556        - {$ref: '#/components/parameters/Cursor'}1557        - {name: node_id, in: query, schema: {type: string, format: uuid}}1558        - {name: health, in: query, schema: {$ref: '#/components/schemas/InferenceHealth'}}1559      responses:1560        '200':1561          description: Inference servers.1562          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1563          content:1564            application/json:1565              schema: {$ref: '#/components/schemas/InferenceServerList'}1566              example:1567                items:1568                  - id: 019a9b30-0000-7000-8000-00000000e0011569                    node_id: 019a9b10-0000-7000-8000-000000000a011570                    node_alias: M3U96a1571                    kind: mlx_lm1572                    port: 80811573                    model: mlx-community/Qwen2.5-7B-Instruct-4bit1574                    quantization: 4bit1575                    pid: 512341576                    rss_bytes: 53687091201577                    uptime_s: 864001578                    disk_bytes: 46123456781579                    health: ok1580                    health_at: '2026-11-18T21:14:50Z'1581                    health_latency_ms: 4.21582                    listed_models: [mlx-community/Qwen2.5-7B-Instruct-4bit]1583                    metrics_support:1584                      requests: {availability: unsupported, reason: mlx_lm.server exposes no request counter}1585                      tokens_per_s: {availability: unsupported, reason: mlx_lm.server exposes no throughput metric}1586                      ttft: {availability: unsupported, reason: mlx_lm.server exposes no latency metric}1587                      latency: {availability: unsupported, reason: mlx_lm.server exposes no latency metric}1588                      queue: {availability: unsupported, reason: mlx_lm.server has no observable queue}1589                    last_seen_at: '2026-11-18T21:14:55Z'1590                    observed_at: '2026-11-18T21:14:55Z'1591                    freshness: fresh1592        '400': {$ref: '#/components/responses/BadRequest'}1593        '401': {$ref: '#/components/responses/Unauthenticated'}1594        '403': {$ref: '#/components/responses/Forbidden'}1595  /models/{id}:1596    parameters:1597      - {$ref: '#/components/parameters/Id'}1598    get:1599      tags: [Models]1600      operationId: getInferenceServer1601      summary: Get an inference server1602      x-permission: models.read1603      responses:1604        '200':1605          description: Inference server.1606          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1607          content: {application/json: {schema: {$ref: '#/components/schemas/InferenceServer'}}}1608        '401': {$ref: '#/components/responses/Unauthenticated'}1609        '403': {$ref: '#/components/responses/Forbidden'}1610        '404': {$ref: '#/components/responses/NotFound'}16111612  # ───────────────────────────── Jobs ─────────────────────────────1613  /job-templates:1614    get:1615      tags: [Jobs]1616      operationId: listJobTemplates1617      summary: List job templates1618      description: Templates are declared in the local allowlist of the agents; there is no free-form job.1619      x-permission: jobs.read1620      responses:1621        '200':1622          description: Templates.1623          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1624          content: {application/json: {schema: {$ref: '#/components/schemas/JobTemplateList'}}}1625        '401': {$ref: '#/components/responses/Unauthenticated'}1626        '403': {$ref: '#/components/responses/Forbidden'}1627  /jobs:1628    get:1629      tags: [Jobs]1630      operationId: listJobs1631      summary: List jobs1632      x-permission: jobs.read1633      parameters:1634        - {$ref: '#/components/parameters/Limit'}1635        - {$ref: '#/components/parameters/Cursor'}1636        - {name: state, in: query, schema: {$ref: '#/components/schemas/JobState'}}1637        - {name: template, in: query, schema: {type: string}}1638        - {name: node_id, in: query, schema: {type: string, format: uuid}}1639        - {name: owner_id, in: query, schema: {type: string, format: uuid}}1640        - {name: schedule_id, in: query, schema: {type: string, format: uuid}}1641      responses:1642        '200':1643          description: Jobs, most recent first.1644          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1645          content: {application/json: {schema: {$ref: '#/components/schemas/JobList'}}}1646        '400': {$ref: '#/components/responses/BadRequest'}1647        '401': {$ref: '#/components/responses/Unauthenticated'}1648        '403': {$ref: '#/components/responses/Forbidden'}1649    post:1650      tags: [Jobs]1651      operationId: createJob1652      summary: Submit a job1653      description: 'Creates a job from a template; the run itself is carried by a `job.run` action (criticality medium, so `actions.run.medium` is also required). Idempotent through `Idempotency-Key`.'1654      x-permission: jobs.submit1655      parameters:1656        - {$ref: '#/components/parameters/Csrf'}1657        - {$ref: '#/components/parameters/IdempotencyKey'}1658      requestBody:1659        required: true1660        content:1661          application/json:1662            schema: {$ref: '#/components/schemas/CreateJobRequest'}1663            example: {template: disk.usage.report, params: {path_alias: home}, placement: {node_id: 019a9b10-0000-7000-8000-000000000a01}}1664      responses:1665        '200':1666          description: Replay of an identical request; the original job is returned.1667          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1668          content: {application/json: {schema: {$ref: '#/components/schemas/Job'}}}1669        '201':1670          description: Job created.1671          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1672          content: {application/json: {schema: {$ref: '#/components/schemas/Job'}}}1673        '400': {$ref: '#/components/responses/BadRequest'}1674        '401': {$ref: '#/components/responses/Unauthenticated'}1675        '403': {$ref: '#/components/responses/Forbidden'}1676        '409': {$ref: '#/components/responses/Conflict'}1677        '422': {$ref: '#/components/responses/Unprocessable'}1678        '503': {$ref: '#/components/responses/Unavailable'}1679  /jobs/{id}:1680    parameters:1681      - {$ref: '#/components/parameters/Id'}1682    get:1683      tags: [Jobs]1684      operationId: getJob1685      summary: Get a job1686      x-permission: jobs.read1687      responses:1688        '200':1689          description: Job.1690          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1691          content: {application/json: {schema: {$ref: '#/components/schemas/Job'}}}1692        '401': {$ref: '#/components/responses/Unauthenticated'}1693        '403': {$ref: '#/components/responses/Forbidden'}1694        '404': {$ref: '#/components/responses/NotFound'}1695  /jobs/{id}/cancel:1696    parameters:1697      - {$ref: '#/components/parameters/Id'}1698    post:1699      tags: [Jobs]1700      operationId: cancelJob1701      summary: Cancel a job1702      description: 'Queued jobs are cancelled immediately; running jobs get a `job.cancel` command. `409 conflict` when the job is already finished.'1703      x-permission: jobs.submit1704      parameters:1705        - {$ref: '#/components/parameters/Csrf'}1706      responses:1707        '200':1708          description: Job with cancellation requested or done.1709          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1710          content: {application/json: {schema: {$ref: '#/components/schemas/Job'}}}1711        '401': {$ref: '#/components/responses/Unauthenticated'}1712        '403': {$ref: '#/components/responses/Forbidden'}1713        '404': {$ref: '#/components/responses/NotFound'}1714        '409': {$ref: '#/components/responses/Conflict'}1715  /job-schedules:1716    get:1717      tags: [Jobs]1718      operationId: listJobSchedules1719      summary: List job schedules1720      x-permission: jobs.read1721      parameters:1722        - {$ref: '#/components/parameters/Limit'}1723        - {$ref: '#/components/parameters/Cursor'}1724      responses:1725        '200':1726          description: Schedules.1727          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1728          content: {application/json: {schema: {$ref: '#/components/schemas/JobScheduleList'}}}1729        '400': {$ref: '#/components/responses/BadRequest'}1730        '401': {$ref: '#/components/responses/Unauthenticated'}1731        '403': {$ref: '#/components/responses/Forbidden'}1732    post:1733      tags: [Jobs]1734      operationId: createJobSchedule1735      summary: Create a recurring job schedule1736      x-permission: jobs.submit1737      parameters:1738        - {$ref: '#/components/parameters/Csrf'}1739      requestBody:1740        required: true1741        content: {application/json: {schema: {$ref: '#/components/schemas/CreateJobScheduleRequest'}}}1742      responses:1743        '201':1744          description: Schedule created.1745          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1746          content: {application/json: {schema: {$ref: '#/components/schemas/JobSchedule'}}}1747        '400': {$ref: '#/components/responses/BadRequest'}1748        '401': {$ref: '#/components/responses/Unauthenticated'}1749        '403': {$ref: '#/components/responses/Forbidden'}1750        '409': {$ref: '#/components/responses/Conflict'}1751        '422': {$ref: '#/components/responses/Unprocessable'}1752  /job-schedules/{id}:1753    parameters:1754      - {$ref: '#/components/parameters/Id'}1755    patch:1756      tags: [Jobs]1757      operationId: updateJobSchedule1758      summary: Update a job schedule1759      x-permission: jobs.submit1760      parameters:1761        - {$ref: '#/components/parameters/Csrf'}1762      requestBody:1763        required: true1764        content: {application/json: {schema: {$ref: '#/components/schemas/UpdateJobScheduleRequest'}}}1765      responses:1766        '200':1767          description: Updated schedule.1768          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1769          content: {application/json: {schema: {$ref: '#/components/schemas/JobSchedule'}}}1770        '400': {$ref: '#/components/responses/BadRequest'}1771        '401': {$ref: '#/components/responses/Unauthenticated'}1772        '403': {$ref: '#/components/responses/Forbidden'}1773        '404': {$ref: '#/components/responses/NotFound'}1774        '409': {$ref: '#/components/responses/Conflict'}1775    delete:1776      tags: [Jobs]1777      operationId: deleteJobSchedule1778      summary: Delete a job schedule1779      x-permission: jobs.submit1780      parameters:1781        - {$ref: '#/components/parameters/Csrf'}1782      responses:1783        '204':1784          description: Schedule deleted. Jobs already created are kept.1785          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1786        '401': {$ref: '#/components/responses/Unauthenticated'}1787        '403': {$ref: '#/components/responses/Forbidden'}1788        '404': {$ref: '#/components/responses/NotFound'}17891790  # ───────────────────────────── Alerts ─────────────────────────────1791  /alerts:1792    get:1793      tags: [Alerts]1794      operationId: listAlerts1795      summary: List alerts1796      x-permission: alerts.read1797      parameters:1798        - {$ref: '#/components/parameters/Limit'}1799        - {$ref: '#/components/parameters/Cursor'}1800        - {name: state, in: query, schema: {$ref: '#/components/schemas/AlertState'}}1801        - {name: open, in: query, description: 'true = every state except `resolved`.', schema: {type: boolean}}1802        - {name: severity, in: query, schema: {$ref: '#/components/schemas/Severity'}}1803        - {name: node_id, in: query, schema: {type: string, format: uuid}}1804        - {name: rule_id, in: query, schema: {type: string, format: uuid}}1805        - {name: incident_id, in: query, schema: {type: string, format: uuid}}1806      responses:1807        '200':1808          description: Alerts, most recent first.1809          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1810          content: {application/json: {schema: {$ref: '#/components/schemas/AlertList'}}}1811        '400': {$ref: '#/components/responses/BadRequest'}1812        '401': {$ref: '#/components/responses/Unauthenticated'}1813        '403': {$ref: '#/components/responses/Forbidden'}1814  /alerts/{id}:1815    parameters:1816      - {$ref: '#/components/parameters/Id'}1817    get:1818      tags: [Alerts]1819      operationId: getAlert1820      summary: Get an alert with its timeline1821      x-permission: alerts.read1822      responses:1823        '200':1824          description: Alert and timeline.1825          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1826          content: {application/json: {schema: {$ref: '#/components/schemas/AlertDetail'}}}1827        '401': {$ref: '#/components/responses/Unauthenticated'}1828        '403': {$ref: '#/components/responses/Forbidden'}1829        '404': {$ref: '#/components/responses/NotFound'}1830  /alerts/{id}/acknowledge:1831    parameters:1832      - {$ref: '#/components/parameters/Id'}1833    post:1834      tags: [Alerts]1835      operationId: acknowledgeAlert1836      summary: Acknowledge a firing alert1837      x-permission: alerts.ack1838      parameters:1839        - {$ref: '#/components/parameters/Csrf'}1840      requestBody:1841        required: false1842        content: {application/json: {schema: {$ref: '#/components/schemas/AlertTransitionRequest'}}}1843      responses:1844        '200':1845          description: Acknowledged alert.1846          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1847          content: {application/json: {schema: {$ref: '#/components/schemas/Alert'}}}1848        '400': {$ref: '#/components/responses/BadRequest'}1849        '401': {$ref: '#/components/responses/Unauthenticated'}1850        '403': {$ref: '#/components/responses/Forbidden'}1851        '404': {$ref: '#/components/responses/NotFound'}1852        '409': {$ref: '#/components/responses/Conflict'}1853  /alerts/{id}/resolve:1854    parameters:1855      - {$ref: '#/components/parameters/Id'}1856    post:1857      tags: [Alerts]1858      operationId: resolveAlert1859      summary: Resolve an alert manually1860      description: If the condition still holds the rule opens a new alert at its next evaluation.1861      x-permission: alerts.ack1862      parameters:1863        - {$ref: '#/components/parameters/Csrf'}1864      requestBody:1865        required: false1866        content: {application/json: {schema: {$ref: '#/components/schemas/AlertTransitionRequest'}}}1867      responses:1868        '200':1869          description: Resolved alert.1870          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1871          content: {application/json: {schema: {$ref: '#/components/schemas/Alert'}}}1872        '400': {$ref: '#/components/responses/BadRequest'}1873        '401': {$ref: '#/components/responses/Unauthenticated'}1874        '403': {$ref: '#/components/responses/Forbidden'}1875        '404': {$ref: '#/components/responses/NotFound'}1876        '409': {$ref: '#/components/responses/Conflict'}1877  /alerts/{id}/comments:1878    parameters:1879      - {$ref: '#/components/parameters/Id'}1880    post:1881      tags: [Alerts]1882      operationId: commentAlert1883      summary: Add a comment to the timeline of an alert1884      x-permission: alerts.ack1885      parameters:1886        - {$ref: '#/components/parameters/Csrf'}1887      requestBody:1888        required: true1889        content: {application/json: {schema: {$ref: '#/components/schemas/CommentRequest'}}}1890      responses:1891        '201':1892          description: Timeline event created.1893          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1894          content: {application/json: {schema: {$ref: '#/components/schemas/TimelineEvent'}}}1895        '400': {$ref: '#/components/responses/BadRequest'}1896        '401': {$ref: '#/components/responses/Unauthenticated'}1897        '403': {$ref: '#/components/responses/Forbidden'}1898        '404': {$ref: '#/components/responses/NotFound'}1899  /alert-rules:1900    get:1901      tags: [Alerts]1902      operationId: listAlertRules1903      summary: List alert rules1904      x-permission: alerts.read1905      parameters:1906        - {$ref: '#/components/parameters/Limit'}1907        - {$ref: '#/components/parameters/Cursor'}1908        - {name: enabled, in: query, schema: {type: boolean}}1909      responses:1910        '200':1911          description: Rules.1912          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1913          content: {application/json: {schema: {$ref: '#/components/schemas/AlertRuleList'}}}1914        '400': {$ref: '#/components/responses/BadRequest'}1915        '401': {$ref: '#/components/responses/Unauthenticated'}1916        '403': {$ref: '#/components/responses/Forbidden'}1917    post:1918      tags: [Alerts]1919      operationId: createAlertRule1920      summary: Create an alert rule1921      x-permission: alerts.manage1922      parameters:1923        - {$ref: '#/components/parameters/Csrf'}1924      requestBody:1925        required: true1926        content:1927          application/json:1928            schema: {$ref: '#/components/schemas/AlertRuleInput'}1929            example: {name: Disk almost full, kind: threshold, metric: disk.used_pct, op: gte, threshold: 95, clear_threshold: 92, for_seconds: 300, clear_seconds: 120, severity: critical, scope: {all: true}}1930      responses:1931        '201':1932          description: Rule created.1933          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1934          content: {application/json: {schema: {$ref: '#/components/schemas/AlertRule'}}}1935        '400': {$ref: '#/components/responses/BadRequest'}1936        '401': {$ref: '#/components/responses/Unauthenticated'}1937        '403': {$ref: '#/components/responses/Forbidden'}1938        '409': {$ref: '#/components/responses/Conflict'}1939  /alert-rules/validate:1940    post:1941      tags: [Alerts]1942      operationId: validateAlertRule1943      summary: Evaluate a draft rule against historical data1944      description: 'Dry run: nothing is stored and no alert is opened. Returns the intervals during which the rule would have fired (default window: the last 7 days).'1945      x-permission: alerts.manage1946      parameters:1947        - {$ref: '#/components/parameters/Csrf'}1948      requestBody:1949        required: true1950        content: {application/json: {schema: {$ref: '#/components/schemas/ValidateAlertRuleRequest'}}}1951      responses:1952        '200':1953          description: Would-have-fired intervals.1954          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1955          content: {application/json: {schema: {$ref: '#/components/schemas/AlertRuleValidation'}}}1956        '400': {$ref: '#/components/responses/BadRequest'}1957        '401': {$ref: '#/components/responses/Unauthenticated'}1958        '403': {$ref: '#/components/responses/Forbidden'}1959        '422': {$ref: '#/components/responses/Unprocessable'}1960  /alert-rules/{id}:1961    parameters:1962      - {$ref: '#/components/parameters/Id'}1963    get:1964      tags: [Alerts]1965      operationId: getAlertRule1966      summary: Get an alert rule1967      x-permission: alerts.read1968      responses:1969        '200':1970          description: Rule.1971          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1972          content: {application/json: {schema: {$ref: '#/components/schemas/AlertRule'}}}1973        '401': {$ref: '#/components/responses/Unauthenticated'}1974        '403': {$ref: '#/components/responses/Forbidden'}1975        '404': {$ref: '#/components/responses/NotFound'}1976    patch:1977      tags: [Alerts]1978      operationId: updateAlertRule1979      summary: Update an alert rule1980      description: 'Built-in rules accept changes to `enabled`, thresholds, durations, severity, scope and `notify` only.'1981      x-permission: alerts.manage1982      parameters:1983        - {$ref: '#/components/parameters/Csrf'}1984      requestBody:1985        required: true1986        content: {application/json: {schema: {$ref: '#/components/schemas/UpdateAlertRuleRequest'}}}1987      responses:1988        '200':1989          description: Updated rule.1990          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}1991          content: {application/json: {schema: {$ref: '#/components/schemas/AlertRule'}}}1992        '400': {$ref: '#/components/responses/BadRequest'}1993        '401': {$ref: '#/components/responses/Unauthenticated'}1994        '403': {$ref: '#/components/responses/Forbidden'}1995        '404': {$ref: '#/components/responses/NotFound'}1996        '409': {$ref: '#/components/responses/Conflict'}1997    delete:1998      tags: [Alerts]1999      operationId: deleteAlertRule2000      summary: Delete an alert rule2001      description: 'Built-in rules cannot be deleted (`409 conflict`); disable them instead. Open alerts of the rule are resolved.'2002      x-permission: alerts.manage2003      parameters:2004        - {$ref: '#/components/parameters/Csrf'}2005      responses:2006        '204':2007          description: Rule deleted.2008          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2009        '401': {$ref: '#/components/responses/Unauthenticated'}2010        '403': {$ref: '#/components/responses/Forbidden'}2011        '404': {$ref: '#/components/responses/NotFound'}2012        '409': {$ref: '#/components/responses/Conflict'}2013  /silences:2014    get:2015      tags: [Alerts]2016      operationId: listSilences2017      summary: List silences2018      x-permission: alerts.read2019      parameters:2020        - {$ref: '#/components/parameters/Limit'}2021        - {$ref: '#/components/parameters/Cursor'}2022        - {name: active, in: query, description: Only silences in effect now., schema: {type: boolean}}2023      responses:2024        '200':2025          description: Silences.2026          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2027          content: {application/json: {schema: {$ref: '#/components/schemas/SilenceList'}}}2028        '400': {$ref: '#/components/responses/BadRequest'}2029        '401': {$ref: '#/components/responses/Unauthenticated'}2030        '403': {$ref: '#/components/responses/Forbidden'}2031    post:2032      tags: [Alerts]2033      operationId: createSilence2034      summary: Create a silence2035      description: A silence suppresses notifications; alerts are still evaluated and recorded with `suppressed_by=silence`.2036      x-permission: alerts.manage2037      parameters:2038        - {$ref: '#/components/parameters/Csrf'}2039      requestBody:2040        required: true2041        content: {application/json: {schema: {$ref: '#/components/schemas/CreateSilenceRequest'}}}2042      responses:2043        '201':2044          description: Silence created.2045          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2046          content: {application/json: {schema: {$ref: '#/components/schemas/Silence'}}}2047        '400': {$ref: '#/components/responses/BadRequest'}2048        '401': {$ref: '#/components/responses/Unauthenticated'}2049        '403': {$ref: '#/components/responses/Forbidden'}2050  /silences/{id}:2051    parameters:2052      - {$ref: '#/components/parameters/Id'}2053    delete:2054      tags: [Alerts]2055      operationId: deleteSilence2056      summary: Delete (end) a silence2057      description: 'Silences owned by a maintenance window cannot be deleted here (`409 conflict`).'2058      x-permission: alerts.manage2059      parameters:2060        - {$ref: '#/components/parameters/Csrf'}2061      responses:2062        '204':2063          description: Silence deleted.2064          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2065        '401': {$ref: '#/components/responses/Unauthenticated'}2066        '403': {$ref: '#/components/responses/Forbidden'}2067        '404': {$ref: '#/components/responses/NotFound'}2068        '409': {$ref: '#/components/responses/Conflict'}2069  /incidents:2070    get:2071      tags: [Alerts]2072      operationId: listIncidents2073      summary: List incidents2074      x-permission: alerts.read2075      parameters:2076        - {$ref: '#/components/parameters/Limit'}2077        - {$ref: '#/components/parameters/Cursor'}2078        - {name: state, in: query, schema: {$ref: '#/components/schemas/IncidentState'}}2079        - {name: severity, in: query, schema: {$ref: '#/components/schemas/Severity'}}2080      responses:2081        '200':2082          description: Incidents, most recent first.2083          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2084          content: {application/json: {schema: {$ref: '#/components/schemas/IncidentList'}}}2085        '400': {$ref: '#/components/responses/BadRequest'}2086        '401': {$ref: '#/components/responses/Unauthenticated'}2087        '403': {$ref: '#/components/responses/Forbidden'}2088    post:2089      tags: [Alerts]2090      operationId: createIncident2091      summary: Open an incident2092      x-permission: alerts.manage2093      parameters:2094        - {$ref: '#/components/parameters/Csrf'}2095      requestBody:2096        required: true2097        content: {application/json: {schema: {$ref: '#/components/schemas/CreateIncidentRequest'}}}2098      responses:2099        '201':2100          description: Incident opened.2101          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2102          content: {application/json: {schema: {$ref: '#/components/schemas/Incident'}}}2103        '400': {$ref: '#/components/responses/BadRequest'}2104        '401': {$ref: '#/components/responses/Unauthenticated'}2105        '403': {$ref: '#/components/responses/Forbidden'}2106        '404': {$ref: '#/components/responses/NotFound'}2107  /incidents/{id}:2108    parameters:2109      - {$ref: '#/components/parameters/Id'}2110    get:2111      tags: [Alerts]2112      operationId: getIncident2113      summary: Get an incident with its timeline and alerts2114      x-permission: alerts.read2115      responses:2116        '200':2117          description: Incident detail.2118          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2119          content: {application/json: {schema: {$ref: '#/components/schemas/IncidentDetail'}}}2120        '401': {$ref: '#/components/responses/Unauthenticated'}2121        '403': {$ref: '#/components/responses/Forbidden'}2122        '404': {$ref: '#/components/responses/NotFound'}2123    patch:2124      tags: [Alerts]2125      operationId: updateIncident2126      summary: Update an incident2127      description: Title, severity, state, summary, owner, and attached alerts.2128      x-permission: alerts.manage2129      parameters:2130        - {$ref: '#/components/parameters/Csrf'}2131      requestBody:2132        required: true2133        content: {application/json: {schema: {$ref: '#/components/schemas/UpdateIncidentRequest'}}}2134      responses:2135        '200':2136          description: Updated incident.2137          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2138          content: {application/json: {schema: {$ref: '#/components/schemas/Incident'}}}2139        '400': {$ref: '#/components/responses/BadRequest'}2140        '401': {$ref: '#/components/responses/Unauthenticated'}2141        '403': {$ref: '#/components/responses/Forbidden'}2142        '404': {$ref: '#/components/responses/NotFound'}2143        '409': {$ref: '#/components/responses/Conflict'}2144  /incidents/{id}/comments:2145    parameters:2146      - {$ref: '#/components/parameters/Id'}2147    post:2148      tags: [Alerts]2149      operationId: commentIncident2150      summary: Add a comment to the timeline of an incident2151      x-permission: alerts.ack2152      parameters:2153        - {$ref: '#/components/parameters/Csrf'}2154      requestBody:2155        required: true2156        content: {application/json: {schema: {$ref: '#/components/schemas/CommentRequest'}}}2157      responses:2158        '201':2159          description: Timeline event created.2160          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2161          content: {application/json: {schema: {$ref: '#/components/schemas/TimelineEvent'}}}2162        '400': {$ref: '#/components/responses/BadRequest'}2163        '401': {$ref: '#/components/responses/Unauthenticated'}2164        '403': {$ref: '#/components/responses/Forbidden'}2165        '404': {$ref: '#/components/responses/NotFound'}21662167  # ───────────────────────────── Maintenance ─────────────────────────────2168  /maintenance/windows:2169    get:2170      tags: [Maintenance]2171      operationId: listMaintenanceWindows2172      summary: Maintenance calendar for a time range2173      description: |2174        Returns the **occurrences** intersecting `[from, to)`: recurring windows are expanded by the server (in the2175        time zone of the window, so local wall-clock time is kept across DST changes), one item per occurrence with2176        `occurrence_start` / `occurrence_end`. A non-recurring window yields one item. Default range: now to now + 302177        days; maximum span 400 days. Not cursor-paginated: at most 1000 occurrences, `truncated=true` beyond.2178      x-permission: maintenance.read2179      parameters:2180        - {$ref: '#/components/parameters/From'}2181        - {$ref: '#/components/parameters/To'}2182        - {name: node_id, in: query, description: Only windows whose scope includes this node., schema: {type: string, format: uuid}}2183        - {name: status, in: query, schema: {$ref: '#/components/schemas/MaintenanceStatus'}}2184      responses:2185        '200':2186          description: Occurrences ordered by `occurrence_start`.2187          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2188          content:2189            application/json:2190              schema: {$ref: '#/components/schemas/MaintenanceOccurrenceList'}2191              example:2192                truncated: false2193                items:2194                  - occurrence_start: '2026-11-22T07:00:00Z'2195                    occurrence_end: '2026-11-22T08:00:00Z'2196                    note_count: 12197                    window:2198                      id: 019a9c40-0000-7000-8000-0000000000f12199                      title: Weekly macOS updates - studios2200                      description: ''2201                      category: update2202                      starts_at: '2026-11-22T07:00:00Z'2203                      ends_at: '2026-11-22T08:00:00Z'2204                      timezone: America/Toronto2205                      recurrence: weekly2206                      scope: {node_ids: [019a9b10-0000-7000-8000-000000000a01]}2207                      set_maintenance_mode: true2208                      silence_alerts: true2209                      status: scheduled2210                      created_at: '2026-11-18T21:20:00Z'2211                      updated_at: '2026-11-18T21:20:00Z'2212        '400': {$ref: '#/components/responses/BadRequest'}2213        '401': {$ref: '#/components/responses/Unauthenticated'}2214        '403': {$ref: '#/components/responses/Forbidden'}2215    post:2216      tags: [Maintenance]2217      operationId: createMaintenanceWindow2218      summary: Schedule a maintenance window2219      description: 'While an occurrence is active the scheduler sets maintenance mode on the nodes in scope (`set_maintenance_mode`) and creates a linked silence (`silence_alerts`).'2220      x-permission: maintenance.write2221      parameters:2222        - {$ref: '#/components/parameters/Csrf'}2223      requestBody:2224        required: true2225        content:2226          application/json:2227            schema: {$ref: '#/components/schemas/CreateMaintenanceWindowRequest'}2228            example:2229              title: Weekly macOS updates - studios2230              category: update2231              starts_at: '2026-11-22T07:00:00Z'2232              ends_at: '2026-11-22T08:00:00Z'2233              timezone: America/Toronto2234              recurrence: weekly2235              scope: {node_ids: [019a9b10-0000-7000-8000-000000000a01]}2236      responses:2237        '201':2238          description: Window created.2239          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2240          content: {application/json: {schema: {$ref: '#/components/schemas/MaintenanceWindow'}}}2241        '400': {$ref: '#/components/responses/BadRequest'}2242        '401': {$ref: '#/components/responses/Unauthenticated'}2243        '403': {$ref: '#/components/responses/Forbidden'}2244        '404': {$ref: '#/components/responses/NotFound'}2245  /maintenance/windows/{id}:2246    parameters:2247      - {$ref: '#/components/parameters/Id'}2248    get:2249      tags: [Maintenance]2250      operationId: getMaintenanceWindow2251      summary: Get a maintenance window2252      x-permission: maintenance.read2253      responses:2254        '200':2255          description: Window.2256          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2257          content: {application/json: {schema: {$ref: '#/components/schemas/MaintenanceWindow'}}}2258        '401': {$ref: '#/components/responses/Unauthenticated'}2259        '403': {$ref: '#/components/responses/Forbidden'}2260        '404': {$ref: '#/components/responses/NotFound'}2261    patch:2262      tags: [Maintenance]2263      operationId: updateMaintenanceWindow2264      summary: Update a maintenance window2265      description: 'Completed or cancelled windows cannot be modified (`409 conflict`).'2266      x-permission: maintenance.write2267      parameters:2268        - {$ref: '#/components/parameters/Csrf'}2269      requestBody:2270        required: true2271        content: {application/json: {schema: {$ref: '#/components/schemas/UpdateMaintenanceWindowRequest'}}}2272      responses:2273        '200':2274          description: Updated window.2275          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2276          content: {application/json: {schema: {$ref: '#/components/schemas/MaintenanceWindow'}}}2277        '400': {$ref: '#/components/responses/BadRequest'}2278        '401': {$ref: '#/components/responses/Unauthenticated'}2279        '403': {$ref: '#/components/responses/Forbidden'}2280        '404': {$ref: '#/components/responses/NotFound'}2281        '409': {$ref: '#/components/responses/Conflict'}2282    delete:2283      tags: [Maintenance]2284      operationId: cancelMaintenanceWindow2285      summary: Cancel a maintenance window2286      description: 'Sets `status=cancelled` (the window and its notes are kept). An active occurrence is ended: maintenance mode and the linked silence are lifted.'2287      x-permission: maintenance.write2288      parameters:2289        - {$ref: '#/components/parameters/Csrf'}2290      responses:2291        '204':2292          description: Window cancelled.2293          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2294        '401': {$ref: '#/components/responses/Unauthenticated'}2295        '403': {$ref: '#/components/responses/Forbidden'}2296        '404': {$ref: '#/components/responses/NotFound'}2297        '409': {$ref: '#/components/responses/Conflict'}2298  /maintenance/windows/{id}/complete:2299    parameters:2300      - {$ref: '#/components/parameters/Id'}2301    post:2302      tags: [Maintenance]2303      operationId: completeMaintenanceWindow2304      summary: Mark a maintenance window (or its current occurrence) as done2305      description: |2306        Ends the active occurrence early: maintenance mode and the linked silence are lifted. A non-recurring window2307        becomes `completed`; a recurring window returns to `scheduled` for its next occurrence. An optional closing2308        note is stored as a maintenance note on the occurrence.2309      x-permission: maintenance.write2310      parameters:2311        - {$ref: '#/components/parameters/Csrf'}2312      requestBody:2313        required: false2314        content: {application/json: {schema: {$ref: '#/components/schemas/CompleteMaintenanceWindowRequest'}}}2315      responses:2316        '200':2317          description: Updated window.2318          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2319          content: {application/json: {schema: {$ref: '#/components/schemas/MaintenanceWindow'}}}2320        '400': {$ref: '#/components/responses/BadRequest'}2321        '401': {$ref: '#/components/responses/Unauthenticated'}2322        '403': {$ref: '#/components/responses/Forbidden'}2323        '404': {$ref: '#/components/responses/NotFound'}2324        '409': {$ref: '#/components/responses/Conflict'}2325  /maintenance/notes:2326    get:2327      tags: [Maintenance]2328      operationId: listMaintenanceNotes2329      summary: List maintenance notes2330      description: Pinned notes first, then most recent first. Deleted notes are never returned.2331      x-permission: maintenance.read2332      parameters:2333        - {$ref: '#/components/parameters/Limit'}2334        - {$ref: '#/components/parameters/Cursor'}2335        - {$ref: '#/components/parameters/Q'}2336        - {name: window_id, in: query, schema: {type: string, format: uuid}}2337        - {name: node_id, in: query, schema: {type: string, format: uuid}}2338        - {name: occurrence, in: query, description: Start of a specific occurrence of the window., schema: {type: string, format: date-time}}2339      responses:2340        '200':2341          description: Notes.2342          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2343          content: {application/json: {schema: {$ref: '#/components/schemas/MaintenanceNoteList'}}}2344        '400': {$ref: '#/components/responses/BadRequest'}2345        '401': {$ref: '#/components/responses/Unauthenticated'}2346        '403': {$ref: '#/components/responses/Forbidden'}2347    post:2348      tags: [Maintenance]2349      operationId: createMaintenanceNote2350      summary: Write a maintenance note2351      description: 'At least one of `window_id` and `node_id` is required. `occurrence` attaches the note to one occurrence of a recurring window.'2352      x-permission: maintenance.write2353      parameters:2354        - {$ref: '#/components/parameters/Csrf'}2355      requestBody:2356        required: true2357        content:2358          application/json:2359            schema: {$ref: '#/components/schemas/CreateMaintenanceNoteRequest'}2360            example: {node_id: 019a9b10-0000-7000-8000-000000000a05, body: 'Internal disk at 3 GB free out of 926; cleanup planned on Sunday.', pinned: true}2361      responses:2362        '201':2363          description: Note created.2364          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2365          content: {application/json: {schema: {$ref: '#/components/schemas/MaintenanceNote'}}}2366        '400': {$ref: '#/components/responses/BadRequest'}2367        '401': {$ref: '#/components/responses/Unauthenticated'}2368        '403': {$ref: '#/components/responses/Forbidden'}2369        '404': {$ref: '#/components/responses/NotFound'}2370  /maintenance/notes/{id}:2371    parameters:2372      - {$ref: '#/components/parameters/Id'}2373    patch:2374      tags: [Maintenance]2375      operationId: updateMaintenanceNote2376      summary: Edit or pin a maintenance note2377      description: 'Only the author can edit the body; `pinned` can be changed by anyone with `maintenance.write`.'2378      x-permission: maintenance.write2379      parameters:2380        - {$ref: '#/components/parameters/Csrf'}2381      requestBody:2382        required: true2383        content: {application/json: {schema: {$ref: '#/components/schemas/UpdateMaintenanceNoteRequest'}}}2384      responses:2385        '200':2386          description: Updated note.2387          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2388          content: {application/json: {schema: {$ref: '#/components/schemas/MaintenanceNote'}}}2389        '400': {$ref: '#/components/responses/BadRequest'}2390        '401': {$ref: '#/components/responses/Unauthenticated'}2391        '403': {$ref: '#/components/responses/Forbidden'}2392        '404': {$ref: '#/components/responses/NotFound'}2393    delete:2394      tags: [Maintenance]2395      operationId: deleteMaintenanceNote2396      summary: Delete a maintenance note2397      description: 'Soft delete. Allowed to the author, or to anyone with `alerts.manage`.'2398      x-permission: maintenance.write2399      parameters:2400        - {$ref: '#/components/parameters/Csrf'}2401      responses:2402        '204':2403          description: Note deleted.2404          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2405        '401': {$ref: '#/components/responses/Unauthenticated'}2406        '403': {$ref: '#/components/responses/Forbidden'}2407        '404': {$ref: '#/components/responses/NotFound'}2408  /maintenance/calendar.ics:2409    get:2410      tags: [Maintenance]2411      operationId: exportMaintenanceCalendar2412      summary: iCalendar export of the maintenance calendar2413      description: 'RFC 5545 calendar (one VEVENT per window, RRULE for recurring ones). Cancelled windows are exported with `STATUS:CANCELLED`. Default range: 30 days back to 400 days ahead.'2414      x-permission: maintenance.read2415      parameters:2416        - {$ref: '#/components/parameters/From'}2417        - {$ref: '#/components/parameters/To'}2418        - {name: node_id, in: query, schema: {type: string, format: uuid}}2419      responses:2420        '200':2421          description: iCalendar document.2422          headers:2423            X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}2424            Content-Disposition: {description: '`attachment; filename="mcc-maintenance.ics"`', schema: {type: string}}2425          content:2426            text/calendar:2427              schema: {type: string}2428        '400': {$ref: '#/components/responses/BadRequest'}2429        '401': {$ref: '#/components/responses/Unauthenticated'}2430        '403': {$ref: '#/components/responses/Forbidden'}24312432  # ───────────────────────────── Network ─────────────────────────────2433  /network/topology:2434    get:2435      tags: [Network]2436      operationId: getNetworkTopology2437      summary: Observed network topology2438      description: |2439        Vertices: cluster nodes, the LAN gateway and the WireGuard hub. Links: node to LAN gateway and node to2440        WireGuard hub, each with the latency and loss measured by the agent of the node, or an availability flag2441        when not measured. Nothing is inferred: a node without a WireGuard interface has no hub link.2442        Addresses require `nodes.private.read`.2443      x-permission: cluster.read2444      responses:2445        '200':2446          description: Topology.2447          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2448          content: {application/json: {schema: {$ref: '#/components/schemas/NetworkTopology'}}}2449        '401': {$ref: '#/components/responses/Unauthenticated'}2450        '403': {$ref: '#/components/responses/Forbidden'}2451  /network/interfaces:2452    get:2453      tags: [Network]2454      operationId: listNetworkInterfaces2455      summary: Network interfaces across nodes2456      description: 'Addresses and MAC require `nodes.private.read`. At most 8 interfaces per node.'2457      x-permission: nodes.read2458      parameters:2459        - {$ref: '#/components/parameters/Limit'}2460        - {$ref: '#/components/parameters/Cursor'}2461        - {name: node_id, in: query, schema: {type: string, format: uuid}}2462      responses:2463        '200':2464          description: Interfaces.2465          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2466          content: {application/json: {schema: {$ref: '#/components/schemas/NetworkInterfaceList'}}}2467        '400': {$ref: '#/components/responses/BadRequest'}2468        '401': {$ref: '#/components/responses/Unauthenticated'}2469        '403': {$ref: '#/components/responses/Forbidden'}24702471  # ───────────────────────────── Storage ─────────────────────────────2472  /storage/volumes:2473    get:2474      tags: [Storage]2475      operationId: listVolumes2476      summary: Volumes across nodes2477      x-permission: nodes.read2478      parameters:2479        - {$ref: '#/components/parameters/Limit'}2480        - {$ref: '#/components/parameters/Cursor'}2481        - {name: node_id, in: query, schema: {type: string, format: uuid}}2482        - {name: kind, in: query, schema: {$ref: '#/components/schemas/VolumeKind'}}2483        - {name: min_used_pct, in: query, description: Only volumes at least this full., schema: {type: number, minimum: 0, maximum: 100}}2484      responses:2485        '200':2486          description: Volumes.2487          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2488          content: {application/json: {schema: {$ref: '#/components/schemas/VolumeList'}}}2489        '400': {$ref: '#/components/responses/BadRequest'}2490        '401': {$ref: '#/components/responses/Unauthenticated'}2491        '403': {$ref: '#/components/responses/Forbidden'}2492  /storage/nas:2493    get:2494      tags: [Storage]2495      operationId: listNasTargets2496      summary: List NAS targets2497      description: 'Registered manually; state is the one observed by the agents. Capacity is absent when not observed. `host` requires `nodes.private.read`.'2498      x-permission: cluster.read2499      responses:2500        '200':2501          description: NAS targets.2502          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2503          content: {application/json: {schema: {$ref: '#/components/schemas/NasTargetList'}}}2504        '401': {$ref: '#/components/responses/Unauthenticated'}2505        '403': {$ref: '#/components/responses/Forbidden'}2506    post:2507      tags: [Storage]2508      operationId: createNasTarget2509      summary: Register a NAS target2510      x-permission: settings.manage2511      parameters:2512        - {$ref: '#/components/parameters/Csrf'}2513      requestBody:2514        required: true2515        content:2516          application/json:2517            schema: {$ref: '#/components/schemas/CreateNasTargetRequest'}2518            example: {name: nas-1, host: 192.168.2.173, share: clustr, protocol: smb}2519      responses:2520        '201':2521          description: NAS target registered with state `unknown` until observed.2522          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2523          content: {application/json: {schema: {$ref: '#/components/schemas/NasTarget'}}}2524        '400': {$ref: '#/components/responses/BadRequest'}2525        '401': {$ref: '#/components/responses/Unauthenticated'}2526        '403': {$ref: '#/components/responses/Forbidden'}2527        '409': {$ref: '#/components/responses/Conflict'}2528  /storage/nas/{id}:2529    parameters:2530      - {$ref: '#/components/parameters/Id'}2531    delete:2532      tags: [Storage]2533      operationId: deleteNasTarget2534      summary: Remove a NAS target2535      x-permission: settings.manage2536      parameters:2537        - {$ref: '#/components/parameters/Csrf'}2538      responses:2539        '204':2540          description: NAS target removed.2541          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2542        '401': {$ref: '#/components/responses/Unauthenticated'}2543        '403': {$ref: '#/components/responses/Forbidden'}2544        '404': {$ref: '#/components/responses/NotFound'}2545  /storage/backups:2546    get:2547      tags: [Storage]2548      operationId: listBackups2549      summary: Observed backups2550      description: 'A backup is never reported `ok` without evidence: `last_status` is `unknown` until an agent has observed a run.'2551      x-permission: cluster.read2552      responses:2553        '200':2554          description: Backups.2555          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2556          content: {application/json: {schema: {$ref: '#/components/schemas/BackupList'}}}2557        '401': {$ref: '#/components/responses/Unauthenticated'}2558        '403': {$ref: '#/components/responses/Forbidden'}25592560  # ───────────────────────────── Actions ─────────────────────────────2561  /action-types:2562    get:2563      tags: [Actions]2564      operationId: listActionTypes2565      summary: Action catalog2566      description: 'Every action type with the JSON Schema of its parameters, criticality, required permission and flags. Types with `available=false` are listed but cannot be run (`422 action_unavailable`).'2567      x-permission: actions.read2568      responses:2569        '200':2570          description: Catalog.2571          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2572          content:2573            application/json:2574              schema: {$ref: '#/components/schemas/ActionTypeList'}2575              example:2576                items:2577                  - type: service.restart2578                    title: Restart service2579                    description: Restarts a managed service through its manager.2580                    criticality: medium2581                    permission: actions.run.medium2582                    target_kinds: [service]2583                    params_schema: {type: object, additionalProperties: false}2584                    requires_step_up: false2585                    requires_justification: false2586                    requires_confirmation: false2587                    requires_approval: false2588                    timeout_s: 1202589                    lock_scope: service2590                    available: true2591                  - type: system.reboot2592                    title: Reboot node2593                    description: Reboots the node. Disabled locally on agents by default.2594                    criticality: critical2595                    permission: actions.run.critical2596                    target_kinds: [node]2597                    params_schema: {type: object, additionalProperties: false}2598                    requires_step_up: true2599                    requires_justification: true2600                    requires_confirmation: true2601                    requires_approval: true2602                    timeout_s: 6002603                    lock_scope: node2604                    available: true2605        '401': {$ref: '#/components/responses/Unauthenticated'}2606        '403': {$ref: '#/components/responses/Forbidden'}2607  /actions:2608    get:2609      tags: [Actions]2610      operationId: listActions2611      summary: List actions2612      x-permission: actions.read2613      parameters:2614        - {$ref: '#/components/parameters/Limit'}2615        - {$ref: '#/components/parameters/Cursor'}2616        - {name: state, in: query, schema: {$ref: '#/components/schemas/ActionState'}}2617        - {name: type, in: query, schema: {type: string}}2618        - {name: criticality, in: query, schema: {$ref: '#/components/schemas/Criticality'}}2619        - {name: node_id, in: query, schema: {type: string, format: uuid}}2620        - {name: target_kind, in: query, schema: {$ref: '#/components/schemas/ActionTargetKind'}}2621        - {name: target_id, in: query, schema: {type: string, format: uuid}}2622        - {name: requested_by, in: query, schema: {type: string, format: uuid}}2623        - {$ref: '#/components/parameters/From'}2624        - {$ref: '#/components/parameters/To'}2625      responses:2626        '200':2627          description: Actions, most recent first.2628          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2629          content: {application/json: {schema: {$ref: '#/components/schemas/ActionList'}}}2630        '400': {$ref: '#/components/responses/BadRequest'}2631        '401': {$ref: '#/components/responses/Unauthenticated'}2632        '403': {$ref: '#/components/responses/Forbidden'}2633    post:2634      tags: [Actions]2635      operationId: createAction2636      summary: Request an action2637      description: |2638        Requests a typed action on a target. The permission depends on the criticality of the type:2639        `actions.run.low|medium|high|critical` (plus `logs.read` for `service.logs.tail`). `high` and `critical`2640        types require a step-up (`403 step_up_required`). Depending on the type flags the request must carry2641        `confirm` (exact alias of the target, checked by the server, else `422 confirmation_mismatch`) and2642        `justification` (`422 justification_required`).26432644        Server pre-checks: known target, agent online and not revoked, capability declared by the agent, node not in2645        maintenance (except maintenance actions), `params` valid against the schema of the type. A failed pre-check2646        is `422` and creates no action.26472648        Types with `requires_approval` start in `pending_approval` and need a second person2649        (`POST /actions/{id}/approve`); the others start `queued`.26502651        **Idempotency**: `Idempotency-Key` is required. Same key and same body returns the original action with2652        `200`; same key with a different body is `409 idempotency_conflict`. One lock per target: a concurrent2653        action on the same target is `409 target_locked`. While the emergency stop is engaged the answer is2654        `503 orchestrator_frozen`. Rate limit: 30 requests per minute per user.2655      x-permission: actions.run.low2656      x-permission-note: 'Minimum; the effective permission is actions.run.<criticality of the type>.'2657      x-step-up-note: 'Required when the action type has requires_step_up=true (high and critical).'2658      parameters:2659        - {$ref: '#/components/parameters/Csrf'}2660        - {$ref: '#/components/parameters/IdempotencyKey'}2661      requestBody:2662        required: true2663        content:2664          application/json:2665            schema: {$ref: '#/components/schemas/CreateActionRequest'}2666            examples:2667              restartService:2668                summary: Restart a managed service2669                value:2670                  type: service.restart2671                  target: {kind: service, id: 019a9b20-0000-7000-8000-00000000c001}2672                  params: {}2673              rebootNode:2674                summary: Critical action with confirmation and justification2675                value:2676                  type: system.reboot2677                  target: {kind: node, id: 019a9b10-0000-7000-8000-000000000a05}2678                  params: {}2679                  confirm: M4M64b2680                  justification: Kernel panic loop after the disk filled up; reboot agreed with the owner.2681      responses:2682        '200':2683          description: Replay of an identical request; the original action is returned.2684          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2685          content: {application/json: {schema: {$ref: '#/components/schemas/Action'}}}2686        '201':2687          description: Action created.2688          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2689          content:2690            application/json:2691              schema: {$ref: '#/components/schemas/Action'}2692              example:2693                id: 019a9c50-0000-7000-8000-00000000b0012694                type: service.restart2695                criticality: medium2696                target: {kind: service, id: 019a9b20-0000-7000-8000-00000000c001}2697                target_label: pm2:wp-web2698                node_id: 019a9b10-0000-7000-8000-000000000a022699                node_alias: M3U96b2700                params: {}2701                state: queued2702                requested_by: 019a9b00-1111-7aaa-8bbb-0000000000012703                requested_by_display_name: Simon-Pierre2704                requested_via: api2705                justification: ''2706                approval_required: false2707                outcome_unknown: false2708                created_at: '2026-11-18T21:30:00Z'2709                queued_at: '2026-11-18T21:30:00Z'2710                timeout_s: 1202711                correlation_id: 019a9c50-0000-7000-8000-00000000cc012712        '400': {$ref: '#/components/responses/BadRequest'}2713        '401': {$ref: '#/components/responses/Unauthenticated'}2714        '403': {$ref: '#/components/responses/Forbidden'}2715        '404': {$ref: '#/components/responses/NotFound'}2716        '409': {$ref: '#/components/responses/Conflict'}2717        '422': {$ref: '#/components/responses/Unprocessable'}2718        '429': {$ref: '#/components/responses/RateLimited'}2719        '503': {$ref: '#/components/responses/Unavailable'}2720  /actions/{id}:2721    parameters:2722      - {$ref: '#/components/parameters/Id'}2723    get:2724      tags: [Actions]2725      operationId: getAction2726      summary: Get an action with its events2727      description: 'Lifecycle events only (state changes, approvals); the output stream is served by `GET /actions/{id}/output`.'2728      x-permission: actions.read2729      responses:2730        '200':2731          description: Action detail.2732          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2733          content: {application/json: {schema: {$ref: '#/components/schemas/ActionDetail'}}}2734        '401': {$ref: '#/components/responses/Unauthenticated'}2735        '403': {$ref: '#/components/responses/Forbidden'}2736        '404': {$ref: '#/components/responses/NotFound'}2737  /actions/{id}/output:2738    parameters:2739      - {$ref: '#/components/parameters/Id'}2740    get:2741      tags: [Actions]2742      operationId: getActionOutput2743      summary: Redacted output of an action2744      description: 'Output chunks (stdout / stderr), redacted by the agent and by the server. Poll with `after` = last `next_after`, or follow the `action.output` events. Output of `service.logs.tail` also requires `logs.read`.'2745      x-permission: actions.read2746      parameters:2747        - {name: after, in: query, description: Return events with an id strictly greater than this value., schema: {type: integer, format: int64, minimum: 0, default: 0}}2748        - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 1000, default: 500}}2749      responses:2750        '200':2751          description: Output chunks in order.2752          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2753          content: {application/json: {schema: {$ref: '#/components/schemas/ActionOutput'}}}2754        '400': {$ref: '#/components/responses/BadRequest'}2755        '401': {$ref: '#/components/responses/Unauthenticated'}2756        '403': {$ref: '#/components/responses/Forbidden'}2757        '404': {$ref: '#/components/responses/NotFound'}2758  /actions/{id}/cancel:2759    parameters:2760      - {$ref: '#/components/parameters/Id'}2761    post:2762      tags: [Actions]2763      operationId: cancelAction2764      summary: Cancel an action2765      description: 'Allowed to the requester, or to anyone holding the run permission of the action criticality. Before dispatch the action is cancelled at once; afterwards cancellation is requested from the agent (best effort). `409 conflict` when already finished.'2766      x-permission: actions.read2767      parameters:2768        - {$ref: '#/components/parameters/Csrf'}2769      responses:2770        '200':2771          description: Action, cancelled or with cancellation requested.2772          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2773          content: {application/json: {schema: {$ref: '#/components/schemas/Action'}}}2774        '401': {$ref: '#/components/responses/Unauthenticated'}2775        '403': {$ref: '#/components/responses/Forbidden'}2776        '404': {$ref: '#/components/responses/NotFound'}2777        '409': {$ref: '#/components/responses/Conflict'}2778  /actions/{id}/approve:2779    parameters:2780      - {$ref: '#/components/parameters/Id'}2781    post:2782      tags: [Actions]2783      operationId: approveAction2784      summary: Approve an action pending approval2785      description: 'The approver must be a different person than the requester (`403 forbidden` otherwise). The action moves to `queued`. `409 conflict` when not `pending_approval`.'2786      x-permission: actions.approve2787      x-step-up: true2788      parameters:2789        - {$ref: '#/components/parameters/Csrf'}2790      requestBody:2791        required: false2792        content: {application/json: {schema: {$ref: '#/components/schemas/ApproveActionRequest'}}}2793      responses:2794        '200':2795          description: Approved action.2796          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2797          content: {application/json: {schema: {$ref: '#/components/schemas/Action'}}}2798        '400': {$ref: '#/components/responses/BadRequest'}2799        '401': {$ref: '#/components/responses/Unauthenticated'}2800        '403': {$ref: '#/components/responses/Forbidden'}2801        '404': {$ref: '#/components/responses/NotFound'}2802        '409': {$ref: '#/components/responses/Conflict'}2803        '503': {$ref: '#/components/responses/Unavailable'}2804  /actions/{id}/reject:2805    parameters:2806      - {$ref: '#/components/parameters/Id'}2807    post:2808      tags: [Actions]2809      operationId: rejectAction2810      summary: Reject an action pending approval2811      x-permission: actions.approve2812      parameters:2813        - {$ref: '#/components/parameters/Csrf'}2814      requestBody:2815        required: true2816        content: {application/json: {schema: {$ref: '#/components/schemas/RejectActionRequest'}}}2817      responses:2818        '200':2819          description: Rejected action.2820          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2821          content: {application/json: {schema: {$ref: '#/components/schemas/Action'}}}2822        '400': {$ref: '#/components/responses/BadRequest'}2823        '401': {$ref: '#/components/responses/Unauthenticated'}2824        '403': {$ref: '#/components/responses/Forbidden'}2825        '404': {$ref: '#/components/responses/NotFound'}2826        '409': {$ref: '#/components/responses/Conflict'}28272828  # ───────────────────────────── Audit ─────────────────────────────2829  /audit:2830    get:2831      tags: [Audit]2832      operationId: listAudit2833      summary: Query the audit log2834      description: Most recent first. Entries only contain allowlisted, non-sensitive parameters.2835      x-permission: audit.read2836      parameters:2837        - {$ref: '#/components/parameters/Limit'}2838        - {$ref: '#/components/parameters/Cursor'}2839        - {name: actor_id, in: query, schema: {type: string, format: uuid}}2840        - {name: action, in: query, description: 'Exact action name, or a prefix ending with `*` (for example `auth.*`).', schema: {type: string}}2841        - {name: target_kind, in: query, schema: {type: string}}2842        - {name: target_id, in: query, schema: {type: string}}2843        - {name: outcome, in: query, schema: {$ref: '#/components/schemas/AuditOutcome'}}2844        - {$ref: '#/components/parameters/From'}2845        - {$ref: '#/components/parameters/To'}2846        - {name: correlation_id, in: query, schema: {type: string, format: uuid}}2847      responses:2848        '200':2849          description: Audit entries.2850          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2851          content: {application/json: {schema: {$ref: '#/components/schemas/AuditList'}}}2852        '400': {$ref: '#/components/responses/BadRequest'}2853        '401': {$ref: '#/components/responses/Unauthenticated'}2854        '403': {$ref: '#/components/responses/Forbidden'}2855  /audit/export:2856    get:2857      tags: [Audit]2858      operationId: exportAudit2859      summary: Export a range of the audit log2860      description: |2861        Returns the file itself: JSON Lines, one `AuditEntry` per line, ascending `seq`, followed by ONE final line2862        `{"manifest": {...}, "signature": "<key_id>:<base64>"}`. The manifest states the range, the entry count, the2863        first and last `seq`, the head hash and the SHA-256 of every byte that precedes the manifest line; it is2864        signed with Ed25519, so the file alone can be verified offline (`mccctl audit-verify-export <file>`), and2865        any changed byte is detected. The response headers repeat the hash of the last exported entry and carry a2866        detached signature of that hash. Maximum range: 366 days. The public key is given by `GET /audit/verify`.2867        The export itself is audited.2868      x-permission: audit.export2869      x-step-up: true2870      parameters:2871        - {name: from, in: query, required: true, schema: {type: string, format: date-time}}2872        - {name: to, in: query, required: true, schema: {type: string, format: date-time}}2873        - {name: format, in: query, schema: {type: string, enum: [jsonl], default: jsonl}}2874      responses:2875        '200':2876          description: Audit export file.2877          headers:2878            X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}2879            Content-Disposition: {description: '`attachment; filename="mcc-audit-<from>-<to>.jsonl"`', schema: {type: string}}2880            X-MCC-Audit-Head-Hash: {description: 'Hex SHA-256 chain hash of the last exported entry.', schema: {type: string}}2881            X-MCC-Audit-Signature: {description: 'Base64 Ed25519 signature of the head hash; the key id is the prefix before the colon (`<key_id>:<signature>`).', schema: {type: string}}2882          content:2883            application/x-ndjson:2884              schema: {type: string}2885        '400': {$ref: '#/components/responses/BadRequest'}2886        '401': {$ref: '#/components/responses/Unauthenticated'}2887        '403': {$ref: '#/components/responses/Forbidden'}2888  /audit/verify:2889    get:2890      tags: [Audit]2891      operationId: verifyAudit2892      summary: Verify the audit hash chain2893      description: Recomputes the chain over the whole log (or from `from_seq`) and reports the first broken link, if any.2894      x-permission: audit.read2895      parameters:2896        - {name: from_seq, in: query, schema: {type: integer, format: int64, minimum: 1}}2897      responses:2898        '200':2899          description: 'Verification result (`ok=false` is a successful verification that found a break).'2900          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2901          content: {application/json: {schema: {$ref: '#/components/schemas/AuditVerification'}}}2902        '400': {$ref: '#/components/responses/BadRequest'}2903        '401': {$ref: '#/components/responses/Unauthenticated'}2904        '403': {$ref: '#/components/responses/Forbidden'}29052906  # ───────────────────────────── Events ─────────────────────────────2907  /events:2908    get:2909      tags: [Events]2910      operationId: streamEvents2911      summary: Real-time event stream (Server-Sent Events)2912      description: |2913        `text/event-stream`. Each frame is29142915        ```2916        id: <seq>2917        event: <topic>2918        data: <json>2919        ```29202921        where `<seq>` is a monotonic sequence and `<json>` is, on one line, the payload schema of the topic:29222923        | `event` | `data` schema | Visible with |2924        |---|---|---|2925        | `node.state` | `NodeStateEvent` | `nodes.read` |2926        | `node.updated` | `NodeUpdatedEvent` | `nodes.read` |2927        | `alert.changed` | `AlertChangedEvent` | `alerts.read` |2928        | `incident.changed` | `IncidentChangedEvent` | `alerts.read` |2929        | `action.changed` | `ActionChangedEvent` | `actions.read` |2930        | `action.output` | `ActionOutputEvent` | `actions.read` (and `logs.read` for log tails) |2931        | `service.changed` | `ServiceChangedEvent` | `services.read` |2932        | `job.changed` | `JobChangedEvent` | `jobs.read` |2933        | `maintenance.changed` | `MaintenanceChangedEvent` | `maintenance.read` |2934        | `audit.appended` | `AuditAppendedEvent` | `audit.read` |2935        | `resync` | `ResyncEvent` | always |29362937        Events are filtered by permission on the server. A comment line `: ping` is sent every 15 seconds.2938        **Resume**: reconnect with `Last-Event-ID` (set automatically by EventSource) or `last_event_id`; missed2939        events are replayed. When the requested sequence is no longer retained (more than 1 hour old) the server2940        sends a single `resync` event and continues live: the client must reload its state through the REST API.2941        Events are notifications: payloads are small and the REST resource remains the source of truth.29422943        The schema `EventStreamFrame` attached to this response describes one **decoded** frame for code generators;2944        the body on the wire is the SSE text format above.2945      x-permission: authenticated2946      parameters:2947        - {name: Last-Event-ID, in: header, description: Sequence of the last event received; the stream resumes after it., schema: {type: string}}2948        - {name: last_event_id, in: query, description: 'Same as the `Last-Event-ID` header, for clients that cannot set headers.', schema: {type: string}}2949        - {name: topics, in: query, description: Comma-separated topics to receive (all permitted topics when omitted)., style: form, explode: false, schema: {type: array, items: {$ref: '#/components/schemas/EventTopic'}}}2950      responses:2951        '200':2952          description: Event stream; stays open.2953          headers:2954            X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}2955            Cache-Control: {description: Always `no-store`., schema: {type: string}}2956          content:2957            text/event-stream:2958              schema: {$ref: '#/components/schemas/EventStreamFrame'}2959        '400': {$ref: '#/components/responses/BadRequest'}2960        '401': {$ref: '#/components/responses/Unauthenticated'}2961        '403': {$ref: '#/components/responses/Forbidden'}2962        '429': {$ref: '#/components/responses/RateLimited'}2963        '503': {$ref: '#/components/responses/Unavailable'}29642965  # ───────────────────────────── Dashboards ─────────────────────────────2966  /me/dashboards:2967    get:2968      tags: [Dashboards]2969      operationId: listMyDashboards2970      summary: Dashboards of the current user2971      x-permission: authenticated2972      responses:2973        '200':2974          description: Dashboards.2975          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}2976          content: {application/json: {schema: {$ref: '#/components/schemas/DashboardList'}}}2977        '401': {$ref: '#/components/responses/Unauthenticated'}2978  /me/dashboards/{name}:2979    parameters:2980      - {name: name, in: path, required: true, description: 'Dashboard name; `default` is the home dashboard.', schema: {type: string, pattern: '^[a-z0-9][a-z0-9_-]{0,39}$'}}2981    put:2982      tags: [Dashboards]2983      operationId: putMyDashboard2984      summary: Create or replace a dashboard layout2985      x-permission: authenticated2986      parameters:2987        - {$ref: '#/components/parameters/Csrf'}2988      requestBody:2989        required: true2990        content:2991          application/json:2992            schema: {$ref: '#/components/schemas/PutDashboardRequest'}2993            example:2994              layout:2995                - {id: w1, type: cluster.capacity, x: 0, y: 0, w: 6, h: 2, config: {}}2996                - {id: w2, type: metric.chart, x: 6, y: 0, w: 6, h: 4, config: {metric: cpu.usage, range: 24h}}2997      responses:2998        '200':2999          description: Stored dashboard.3000          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3001          content: {application/json: {schema: {$ref: '#/components/schemas/Dashboard'}}}3002        '400': {$ref: '#/components/responses/BadRequest'}3003        '401': {$ref: '#/components/responses/Unauthenticated'}3004        '403': {$ref: '#/components/responses/Forbidden'}3005    delete:3006      tags: [Dashboards]3007      operationId: deleteMyDashboard3008      summary: Delete a dashboard3009      description: Deleting `default` restores the built-in layout.3010      x-permission: authenticated3011      parameters:3012        - {$ref: '#/components/parameters/Csrf'}3013      responses:3014        '204':3015          description: Dashboard deleted.3016          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3017        '401': {$ref: '#/components/responses/Unauthenticated'}3018        '403': {$ref: '#/components/responses/Forbidden'}3019        '404': {$ref: '#/components/responses/NotFound'}30203021  # ───────────────────────────── Activity ─────────────────────────────3022  /activity:3023    get:3024      tags: [Activity]3025      operationId: listActivity3026      summary: Recent operator-visible activity3027      description: |3028        Redacted subset of what happened recently (actions, acknowledgements, maintenance, sign-ins), for users3029        without `audit.read`: no IP, no device, no session, no parameters. Each item is only returned when the3030        caller can read the underlying resource.3031      x-permission: cluster.read3032      parameters:3033        - {$ref: '#/components/parameters/Limit'}3034        - {$ref: '#/components/parameters/Cursor'}3035        - {name: kind, in: query, schema: {$ref: '#/components/schemas/ActivityKind'}}3036        - {name: node_id, in: query, schema: {type: string, format: uuid}}3037      responses:3038        '200':3039          description: Activity items, most recent first.3040          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3041          content: {application/json: {schema: {$ref: '#/components/schemas/ActivityList'}}}3042        '400': {$ref: '#/components/responses/BadRequest'}3043        '401': {$ref: '#/components/responses/Unauthenticated'}3044        '403': {$ref: '#/components/responses/Forbidden'}30453046  # ───────────────────────────── Search ─────────────────────────────3047  /search:3048    get:3049      tags: [Search]3050      operationId: search3051      summary: Universal search3052      description: 'Searches nodes, services, alerts, actions, incidents, jobs, inference servers, maintenance windows and notes. Only kinds the caller can read are searched.'3053      x-permission: authenticated3054      parameters:3055        - {name: q, in: query, required: true, schema: {type: string, minLength: 1, maxLength: 120}}3056        - {name: kinds, in: query, description: Comma-separated kinds to search (all when omitted)., style: form, explode: false, schema: {type: array, items: {$ref: '#/components/schemas/SearchResultKind'}}}3057        - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 50, default: 20}}3058      responses:3059        '200':3060          description: Results ordered by relevance.3061          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3062          content: {application/json: {schema: {$ref: '#/components/schemas/SearchResults'}}}3063        '400': {$ref: '#/components/responses/BadRequest'}3064        '401': {$ref: '#/components/responses/Unauthenticated'}30653066  # ───────────────────────────── Meta ─────────────────────────────3067  /health/live:3068    get:3069      tags: [Meta]3070      operationId: getLiveness3071      summary: Liveness probe3072      description: Unauthenticated and minimal; the process answers.3073      x-permission: none3074      security: []3075      responses:3076        '200':3077          description: Alive.3078          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3079          content: {application/json: {schema: {$ref: '#/components/schemas/HealthStatus'}}}3080  /health/ready:3081    get:3082      tags: [Meta]3083      operationId: getReadiness3084      summary: Readiness probe3085      description: Unauthenticated and minimal; `503` when the database is unreachable. No detail is disclosed (see `GET /admin/status`).3086      x-permission: none3087      security: []3088      responses:3089        '200':3090          description: Ready.3091          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3092          content: {application/json: {schema: {$ref: '#/components/schemas/HealthStatus'}}}3093        '503': {$ref: '#/components/responses/Unavailable'}3094  /version:3095    get:3096      tags: [Meta]3097      operationId: getVersion3098      summary: API and server version3099      description: Unauthenticated, so that clients can check compatibility before signing in. Only version identifiers are disclosed.3100      x-permission: none3101      security: []3102      responses:3103        '200':3104          description: Version.3105          headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3106          content: {application/json: {schema: {$ref: '#/components/schemas/VersionInfo'}}}31073108components:3109  securitySchemes:3110    cookieSession:3111      type: apiKey3112      in: cookie3113      name: __Host-mcc_session3114      description: 'Web session cookie (opaque, Secure, HttpOnly, SameSite=Strict). Idle timeout 30 min, absolute lifetime 12 h. Non-safe methods also require the `X-MCC-CSRF` header.'3115    bearer:3116      type: http3117      scheme: bearer3118      description: 'Native clients: opaque access token valid 10 minutes, renewed through `POST /auth/refresh`.'3119    setupCookie:3120      type: apiKey3121      in: cookie3122      name: __Host-mcc_setup3123      description: 'Setup transaction of an exchanged invitation (web clients). Valid 10 minutes.'3124    setupHeader:3125      type: apiKey3126      in: header3127      name: X-MCC-Setup-Transaction3128      description: 'Setup transaction token of an exchanged invitation (native clients). Valid 10 minutes.'31293130  headers:3131    CorrelationId:3132      description: Correlation id of the request; also present in error bodies and in the audit log.3133      schema: {type: string, format: uuid}3134    RetryAfter:3135      description: Number of seconds to wait before retrying.3136      schema: {type: integer, minimum: 1}31373138  parameters:3139    Id:3140      name: id3141      in: path3142      required: true3143      schema: {type: string, format: uuid}3144    Csrf:3145      name: X-MCC-CSRF3146      in: header3147      required: false3148      description: 'CSRF token of the session. **Required for cookie sessions** on every non-safe method (`403 csrf_failed` otherwise); ignored for bearer sessions.'3149      schema: {type: string}3150    IdempotencyKey:3151      name: Idempotency-Key3152      in: header3153      required: true3154      description: 'Client-generated key (a UUID is recommended), unique per user. Same key and same body returns the original resource; same key with another body is `409 idempotency_conflict`.'3155      schema: {type: string, minLength: 8, maxLength: 128}3156    Limit:3157      name: limit3158      in: query3159      description: Page size.3160      schema: {type: integer, minimum: 1, maximum: 200, default: 50}3161    Cursor:3162      name: cursor3163      in: query3164      description: Opaque cursor taken from `next_cursor` of the previous page.3165      schema: {type: string}3166    Q:3167      name: q3168      in: query3169      description: Free-text filter (case-insensitive substring).3170      schema: {type: string, maxLength: 120}3171    Order:3172      name: order3173      in: query3174      description: Sort direction.3175      schema: {type: string, enum: [asc, desc], default: asc}3176    From:3177      name: from3178      in: query3179      description: Start of the time range (inclusive, UTC).3180      schema: {type: string, format: date-time}3181    To:3182      name: to3183      in: query3184      description: End of the time range (exclusive, UTC). Defaults to now.3185      schema: {type: string, format: date-time}31863187  responses:3188    BadRequest:3189      description: '`validation_failed` - malformed body, parameter or header.'3190      headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3191      content:3192        application/json:3193          schema: {$ref: '#/components/schemas/ErrorResponse'}3194          example:3195            error:3196              code: validation_failed3197              message: Invalid request.3198              details: {fields: {ttl_minutes: must be between 1 and 1440}}3199              correlation_id: 019a9c50-0000-7000-8000-00000000cc013200    Unauthenticated:3201      description: '`unauthenticated`, `session_expired`, `webauthn_failed` or `refresh_reuse_detected`.'3202      headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3203      content:3204        application/json:3205          schema: {$ref: '#/components/schemas/ErrorResponse'}3206          example:3207            error: {code: unauthenticated, message: Authentication required., correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3208    Forbidden:3209      description: '`forbidden` (missing permission or deny grant), `step_up_required` (passkey ceremony older than 5 minutes) or `csrf_failed`.'3210      headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3211      content:3212        application/json:3213          schema: {$ref: '#/components/schemas/ErrorResponse'}3214          examples:3215            forbidden:3216              value:3217                error: {code: forbidden, message: Permission actions.run.high is required., details: {permission: actions.run.high}, correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3218            stepUpRequired:3219              value:3220                error: {code: step_up_required, message: A recent passkey verification is required., details: {max_age_seconds: 300}, correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3221            csrfFailed:3222              value:3223                error: {code: csrf_failed, message: Missing or invalid CSRF token., correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3224    NotFound:3225      description: '`not_found` - unknown resource, or resource hidden from the caller.'3226      headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3227      content:3228        application/json:3229          schema: {$ref: '#/components/schemas/ErrorResponse'}3230          example:3231            error: {code: not_found, message: Resource not found., correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3232    Conflict:3233      description: '`conflict`, `idempotency_conflict`, `target_locked` or `last_passkey`.'3234      headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3235      content:3236        application/json:3237          schema: {$ref: '#/components/schemas/ErrorResponse'}3238          examples:3239            conflict:3240              value:3241                error: {code: conflict, message: Alias already in use., correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3242            idempotencyConflict:3243              value:3244                error: {code: idempotency_conflict, message: Idempotency-Key already used with a different request., correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3245            targetLocked:3246              value:3247                error: {code: target_locked, message: Another action is in progress on this target., details: {action_id: 019a9c50-0000-7000-8000-00000000b001}, correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3248            lastPasskey:3249              value:3250                error: {code: last_passkey, message: The last passkey of an account cannot be deleted., correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3251    Gone:3252      description: '`gone` - invitation or setup transaction expired, consumed or revoked. The cause is deliberately not disclosed.'3253      headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3254      content:3255        application/json:3256          schema: {$ref: '#/components/schemas/ErrorResponse'}3257          example:3258            error: {code: gone, message: This invitation is no longer valid., correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3259    Unprocessable:3260      description: '`precheck_failed`, `confirmation_mismatch`, `justification_required`, `agent_offline`, `capability_missing`, `node_in_maintenance`, `action_unavailable` or `unprocessable`.'3261      headers: {X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}}3262      content:3263        application/json:3264          schema: {$ref: '#/components/schemas/ErrorResponse'}3265          example:3266            error: {code: agent_offline, message: The agent of M4BP36 is offline., details: {check: agent_online, node_id: 019a9b10-0000-7000-8000-000000000a09}, correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3267    RateLimited:3268      description: '`rate_limited` - too many requests.'3269      headers:3270        X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}3271        Retry-After: {$ref: '#/components/headers/RetryAfter'}3272      content:3273        application/json:3274          schema: {$ref: '#/components/schemas/ErrorResponse'}3275          example:3276            error: {code: rate_limited, message: Too many requests., details: {retry_after_seconds: 42}, correlation_id: 019a9c50-0000-7000-8000-00000000cc01}3277    Unavailable:3278      description: '`unavailable` (a dependency is down) or `orchestrator_frozen` (emergency stop engaged).'3279      headers:3280        X-Correlation-Id: {$ref: '#/components/headers/CorrelationId'}3281        Retry-After: {$ref: '#/components/headers/RetryAfter'}3282      content:3283        application/json:3284          schema: {$ref: '#/components/schemas/ErrorResponse'}3285          example:3286            error: {code: unavailable, message: Service temporarily unavailable., correlation_id: 019a9c50-0000-7000-8000-00000000cc01}32873288  schemas:3289    # ───────────── Common ─────────────3290    ErrorResponse:3291      type: object3292      required: [error]3293      properties:3294        error: {$ref: '#/components/schemas/ErrorBody'}3295    ErrorBody:3296      type: object3297      required: [code, message, correlation_id]3298      properties:3299        code:3300          type: string3301          description: |3302            Stable machine-readable code. Clients must tolerate unknown codes (fall back on the HTTP status). Known3303            codes: `validation_failed`, `unauthenticated`, `session_expired`, `webauthn_failed`,3304            `refresh_reuse_detected`, `forbidden`, `step_up_required`, `csrf_failed`, `not_found`, `conflict`,3305            `idempotency_conflict`, `target_locked`, `last_passkey`, `gone`, `precheck_failed`,3306            `confirmation_mismatch`, `justification_required`, `agent_offline`, `capability_missing`,3307            `node_in_maintenance`, `action_unavailable`, `unprocessable`, `rate_limited`, `internal`,3308            `unavailable`, `orchestrator_frozen`.3309        message: {type: string, description: Human-readable message in English; clients localize from `code`.}3310        details: {type: object, additionalProperties: true, description: Code-specific details. Never contains secrets.}3311        correlation_id: {type: string, format: uuid}3312    Freshness:3313      type: string3314      enum: [fresh, stale, offline]3315      description: 'Computed by the server from the last report: `fresh` under 30 s, `stale` 30 to 120 s, `offline` beyond 120 s or never seen.'3316    Availability:3317      type: string3318      enum: [available, unavailable, unsupported, permission_denied, stale, offline]3319      description: 'State of a metric. `unsupported`: cannot be measured on this platform; `permission_denied`: needs a privilege the agent does not have; `unavailable`: temporarily not measurable; `stale` / `offline`: follows the freshness of the node.'3320    Severity: {type: string, enum: [info, warning, critical]}3321    Criticality: {type: string, enum: [low, medium, high, critical]}3322    UserRole: {type: string, enum: [owner, admin, operator, viewer]}3323    ClientKind: {type: string, enum: [web, macos, ios], description: Kind of client and of device.}3324    SessionKind: {type: string, enum: [cookie, bearer]}3325    NodeKind: {type: string, enum: [mac, linux, nas]}3326    ServiceManager: {type: string, enum: [pm2, launchd, systemd, docker]}3327    ServiceState: {type: string, enum: [online, stopped, errored, unknown], description: Normalized state; the raw manager state is in `meta`.}3328    InferenceHealth: {type: string, enum: [ok, failing, unknown]}3329    VolumeKind: {type: string, enum: [internal, external, network]}3330    ActionState:3331      type: string3332      enum: [pending_approval, queued, dispatched, running, succeeded, failed, cancelled, timed_out, rejected, expired]3333    ActionTargetKind: {type: string, enum: [node, service, job, inference_server]}3334    JobState: {type: string, enum: [queued, running, succeeded, failed, cancelled, timed_out]}3335    AlertState: {type: string, enum: [pending, firing, acknowledged, resolved]}3336    IncidentState: {type: string, enum: [open, mitigated, resolved]}3337    AuditOutcome: {type: string, enum: [success, denied, failure]}3338    GrantEffect: {type: string, enum: [allow, deny]}3339    GrantSubjectKind: {type: string, enum: [user, role]}3340    TimeRange: {type: string, enum: [1h, 24h, 7d, 30d], default: 24h}3341    Resolution: {type: string, enum: [auto, raw, 1m, 1h], default: auto}3342    TrendGroupBy: {type: string, enum: [cluster, site, role, tag], default: cluster}3343    MaintenanceStatus: {type: string, enum: [scheduled, in_progress, completed, cancelled]}3344    MaintenanceCategory: {type: string, enum: [planned, emergency, update, hardware, inspection]}3345    MaintenanceRecurrence: {type: string, enum: [none, daily, weekly, monthly]}3346    InvitationStatus:3347      type: string3348      enum: [pending, exchanged, completed, expired, revoked]3349      description: '`pending`: token not used; `exchanged`: token consumed, setup transaction open or abandoned; `completed`: account created or linked.'3350    MetricPoints:3351      type: array3352      description: 'Points as `[ts_ms, avg, min, max]` (Unix milliseconds UTC). At raw resolution avg = min = max. Missing buckets are omitted.'3353      items:3354        type: array3355        minItems: 43356        maxItems: 43357        items: {type: number, format: double}33583359    # ───────────── Auth ─────────────3360    WebAuthnChallenge:3361      type: object3362      required: [challenge_id, public_key, expires_at]3363      properties:3364        challenge_id: {type: string, format: uuid}3365        public_key:3366          type: object3367          additionalProperties: true3368          description: 'WebAuthn options JSON to pass to the platform API: PublicKeyCredentialRequestOptions (authentication, step-up) or PublicKeyCredentialCreationOptions (registration). Binary members are base64url.'3369        expires_at: {type: string, format: date-time}3370    ClientInfo:3371      type: object3372      required: [kind]3373      properties:3374        kind: {$ref: '#/components/schemas/ClientKind'}3375        label: {type: string, maxLength: 80, description: 'Device label shown in the device list, for example "MacBook Pro of Erika".'}3376        model: {type: string, maxLength: 80}3377        os_version: {type: string, maxLength: 40}3378        app_version: {type: string, maxLength: 40}3379        device_id: {type: string, format: uuid, description: 'Identifier returned as `AuthResult.device_id` by a previous sign-in on this device (native: kept in the Keychain; web: the server uses the `__Host-mcc_device` cookie instead). It is reused only if it belongs to the authenticated user, has the same kind and is not revoked; otherwise a new device is created.'}3380    AuthenticationFinishRequest:3381      type: object3382      required: [challenge_id, credential, client]3383      properties:3384        challenge_id: {type: string, format: uuid}3385        credential: {type: object, additionalProperties: true, description: PublicKeyCredential JSON (assertion) produced by the platform API.}3386        client: {$ref: '#/components/schemas/ClientInfo'}3387    AuthResult:3388      type: object3389      required: [user, session, device_id]3390      properties:3391        user: {$ref: '#/components/schemas/User'}3392        session: {$ref: '#/components/schemas/Session'}3393        device_id: {type: string, format: uuid, description: Device this session is bound to. Native clients store it and send it back as `client.device_id`.}3394        csrf_token: {type: string, description: Web clients only.}3395        access_token: {type: string, description: Native clients only. Opaque; valid until `access_expires_at`.}3396        access_expires_at: {type: string, format: date-time, description: Native clients only.}3397        refresh_token: {type: string, description: Native clients only. Rotating and device-bound; store in the Keychain.}3398        refresh_expires_at: {type: string, format: date-time, description: Native clients only.}3399    RegistrationBeginRequest:3400      type: object3401      properties:3402        label: {type: string, maxLength: 80, description: Label proposed for the new passkey.}3403    RegistrationFinishRequest:3404      type: object3405      required: [challenge_id, credential]3406      properties:3407        challenge_id: {type: string, format: uuid}3408        credential: {type: object, additionalProperties: true, description: PublicKeyCredential JSON (attestation) produced by the platform API.}3409        label: {type: string, maxLength: 80}3410        client: {$ref: '#/components/schemas/ClientInfo'}3411    RegistrationResult:3412      type: object3413      required: [passkey]3414      properties:3415        passkey: {$ref: '#/components/schemas/Passkey'}3416        auth: {$ref: '#/components/schemas/AuthResult'}3417    StepUpFinishRequest:3418      type: object3419      required: [challenge_id, credential]3420      properties:3421        challenge_id: {type: string, format: uuid}3422        credential: {type: object, additionalProperties: true, description: PublicKeyCredential JSON (assertion).}3423    StepUpResult:3424      type: object3425      required: [authenticated_at, step_up_valid_until]3426      properties:3427        authenticated_at: {type: string, format: date-time}3428        step_up_valid_until: {type: string, format: date-time}3429    RefreshRequest:3430      type: object3431      required: [refresh_token]3432      properties:3433        refresh_token: {type: string}3434    TokenPair:3435      type: object3436      required: [access_token, access_expires_at, refresh_token, refresh_expires_at]3437      properties:3438        access_token: {type: string}3439        access_expires_at: {type: string, format: date-time}3440        refresh_token: {type: string}3441        refresh_expires_at: {type: string, format: date-time}3442    User:3443      type: object3444      required: [id, handle, display_name, role, locale, disabled, created_at]3445      properties:3446        id: {type: string, format: uuid}3447        handle: {type: string, pattern: '^[a-z0-9][a-z0-9._-]{1,31}$'}3448        display_name: {type: string, minLength: 1, maxLength: 80}3449        role: {$ref: '#/components/schemas/UserRole'}3450        locale: {type: string, enum: [fr, en]}3451        disabled: {type: boolean}3452        disabled_at: {type: string, format: date-time}3453        created_at: {type: string, format: date-time}3454        passkey_count: {type: integer, description: Admin views only.}3455        last_seen_at: {type: string, format: date-time, description: Admin views only; last activity of any session.}3456    UserList:3457      type: object3458      required: [items]3459      properties:3460        items: {type: array, items: {$ref: '#/components/schemas/User'}}3461        next_cursor: {type: string}3462    UpdateMeRequest:3463      type: object3464      properties:3465        display_name: {type: string, minLength: 1, maxLength: 80}3466        locale: {type: string, enum: [fr, en]}3467    UpdateUserRequest:3468      type: object3469      properties:3470        role: {$ref: '#/components/schemas/UserRole'}3471        disabled: {type: boolean}3472    Me:3473      type: object3474      required: [user, permissions, session]3475      properties:3476        user: {$ref: '#/components/schemas/User'}3477        permissions:3478          type: array3479          items: {type: string}3480          description: Effective global permissions (role defaults and grants without resource). Resource-scoped grants are evaluated by the server per request.3481        session: {$ref: '#/components/schemas/Session'}3482        csrf_token: {type: string, description: Cookie sessions only.}3483    Passkey:3484      type: object3485      required: [id, label, transports, backup_eligible, backup_state, created_at]3486      properties:3487        id: {type: string, format: uuid}3488        label: {type: string}3489        transports: {type: array, items: {type: string}}3490        backup_eligible: {type: boolean}3491        backup_state: {type: boolean, description: True for a synced (multi-device) passkey.}3492        aaguid: {type: string, description: Hex AAGUID of the authenticator when known.}3493        created_at: {type: string, format: date-time}3494        last_used_at: {type: string, format: date-time}3495        revoked_at: {type: string, format: date-time}3496    PasskeyList:3497      type: object3498      required: [items]3499      properties:3500        items: {type: array, items: {$ref: '#/components/schemas/Passkey'}}3501        next_cursor: {type: string}3502    UpdatePasskeyRequest:3503      type: object3504      required: [label]3505      properties:3506        label: {type: string, minLength: 1, maxLength: 80}3507    Session:3508      type: object3509      required: [id, kind, device_id, current, created_at, last_seen_at, authenticated_at, step_up_valid_until, idle_expires_at, absolute_expires_at]3510      properties:3511        id: {type: string, format: uuid}3512        kind: {$ref: '#/components/schemas/SessionKind'}3513        user_id: {type: string, format: uuid}3514        device_id: {type: string, format: uuid}3515        device_label: {type: string}3516        passkey_id: {type: string, format: uuid}3517        current: {type: boolean, description: True for the session making the request.}3518        created_at: {type: string, format: date-time}3519        last_seen_at: {type: string, format: date-time}3520        authenticated_at: {type: string, format: date-time, description: Last passkey ceremony of the session.}3521        step_up_valid_until: {type: string, format: date-time, description: '`authenticated_at` + 5 minutes; step-up operations are accepted until then.'}3522        idle_expires_at: {type: string, format: date-time}3523        absolute_expires_at: {type: string, format: date-time}3524        ip: {type: string, description: Last client address.}3525        user_agent: {type: string}3526    SessionList:3527      type: object3528      required: [items]3529      properties:3530        items: {type: array, items: {$ref: '#/components/schemas/Session'}}3531        next_cursor: {type: string}3532    Device:3533      type: object3534      required: [id, kind, label, model, os_version, app_version, push_enabled, current, created_at]3535      properties:3536        id: {type: string, format: uuid}3537        user_id: {type: string, format: uuid}3538        kind: {$ref: '#/components/schemas/ClientKind'}3539        label: {type: string}3540        model: {type: string}3541        os_version: {type: string}3542        app_version: {type: string}3543        push_enabled: {type: boolean, description: True when a push token is registered. The token itself is never returned.}3544        push_env: {type: string, enum: [development, production]}3545        current: {type: boolean}3546        created_at: {type: string, format: date-time}3547        last_seen_at: {type: string, format: date-time}3548        revoked_at: {type: string, format: date-time}3549    DeviceList:3550      type: object3551      required: [items]3552      properties:3553        items: {type: array, items: {$ref: '#/components/schemas/Device'}}3554        next_cursor: {type: string}3555    PushTokenRequest:3556      type: object3557      required: [token, environment]3558      properties:3559        token: {type: string, minLength: 32, maxLength: 512, description: APNs device token (hex).}3560        environment: {type: string, enum: [development, production]}3561    PermissionInfo:3562      type: object3563      required: [name, description, step_up]3564      properties:3565        name: {type: string}3566        description: {type: string}3567        step_up: {type: boolean, description: True when exercising the permission always requires a step-up.}3568    RolePermissions:3569      type: object3570      required: [role, permissions]3571      properties:3572        role: {$ref: '#/components/schemas/UserRole'}3573        permissions: {type: array, items: {type: string}}3574    PermissionCatalog:3575      type: object3576      required: [permissions, role_defaults]3577      properties:3578        permissions: {type: array, items: {$ref: '#/components/schemas/PermissionInfo'}}3579        role_defaults: {type: array, items: {$ref: '#/components/schemas/RolePermissions'}}35803581    # ───────────── Invitations ─────────────3582    CreateInvitationRequest:3583      type: object3584      required: [role]3585      properties:3586        role: {$ref: '#/components/schemas/UserRole'}3587        handle: {type: string, pattern: '^[a-z0-9][a-z0-9._-]{1,31}$', description: Proposed handle; left to the invitee when omitted.}3588        display_name: {type: string, minLength: 1, maxLength: 80}3589        target_user_id: {type: string, format: uuid, description: Existing account to link the invitation to.}3590        ttl_minutes: {type: integer, minimum: 1, maximum: 1440, default: 15}3591        note: {type: string, maxLength: 500}3592    InvitationPurpose:3593      type: string3594      enum: [new_account, link, recovery]3595      description: '`new_account`: creates an account; `link`: applies to the existing account `target_user_id` (session of that account + step-up required); `recovery`: out-of-band (`mccctl recovery-invite`) registration of a new passkey on the existing account `target_user_id`. The API only creates `new_account` and `link` invitations.'3596    Invitation:3597      type: object3598      required: [id, purpose, role, note, status, failed_attempts, created_at, expires_at]3599      properties:3600        id: {type: string, format: uuid}3601        purpose: {$ref: '#/components/schemas/InvitationPurpose'}3602        role: {$ref: '#/components/schemas/UserRole'}3603        handle: {type: string}3604        display_name: {type: string}3605        target_user_id: {type: string, format: uuid}3606        note: {type: string}3607        status: {$ref: '#/components/schemas/InvitationStatus'}3608        failed_attempts: {type: integer}3609        created_by: {type: string, format: uuid, description: Absent for out-of-band invitations created with `mccctl`.}3610        created_by_display_name: {type: string}3611        created_at: {type: string, format: date-time}3612        expires_at: {type: string, format: date-time}3613        consumed_at: {type: string, format: date-time}3614        revoked_at: {type: string, format: date-time}3615        completed_at: {type: string, format: date-time}3616        resulting_user_id: {type: string, format: uuid}3617    InvitationList:3618      type: object3619      required: [items]3620      properties:3621        items: {type: array, items: {$ref: '#/components/schemas/Invitation'}}3622        next_cursor: {type: string}3623    InvitationCreated:3624      type: object3625      required: [invitation, token, setup_url]3626      properties:3627        invitation: {$ref: '#/components/schemas/Invitation'}3628        token: {type: string, description: 'Invitation token (32 random bytes, base64url). Shown once.'}3629        setup_url: {type: string, format: uri, description: 'Link carrying the token in the URL fragment, which is never sent to the server. Shown once.'}3630    InvitationExchangeRequest:3631      type: object3632      required: [token]3633      properties:3634        token: {type: string, minLength: 20, maxLength: 128}3635        client: {$ref: '#/components/schemas/ClientInfo'}3636    InvitationTransaction:3637      type: object3638      required: [purpose, role, requires_existing_account, profile_required, expires_at, inviter_display_name]3639      properties:3640        purpose: {$ref: '#/components/schemas/InvitationPurpose'}3641        role: {$ref: '#/components/schemas/UserRole'}3642        handle: {type: string, description: Handle fixed by the invitation or chosen through the profile step.}3643        display_name: {type: string}3644        requires_existing_account: {type: boolean, description: 'True for an invitation targeting an existing account: sign in to that account, step up, then call the link operation.'}3645        profile_required: {type: boolean, description: True while handle or display name still has to be chosen.}3646        expires_at: {type: string, format: date-time}3647        inviter_display_name: {type: string, description: '"mccctl" for out-of-band invitations.'}3648        transaction_token: {type: string, description: 'Only returned by the exchange, and only to native clients (`client.kind` other than `web`).'}3649    InvitationProfileRequest:3650      type: object3651      required: [handle, display_name]3652      properties:3653        handle: {type: string, pattern: '^[a-z0-9][a-z0-9._-]{1,31}$'}3654        display_name: {type: string, minLength: 1, maxLength: 80}3655    InvitationLinkRequest:3656      type: object3657      required: [confirm]3658      properties:3659        confirm: {type: boolean, description: Must be `true`; explicit confirmation by the account holder.}3660    InvitationLinkResult:3661      type: object3662      required: [user]3663      properties:3664        user: {$ref: '#/components/schemas/User'}36653666    # ───────────── Admin ─────────────3667    PolicyGrant:3668      type: object3669      required: [id, subject_kind, subject, permission, effect, created_at]3670      properties:3671        id: {type: string, format: uuid}3672        subject_kind: {$ref: '#/components/schemas/GrantSubjectKind'}3673        subject: {type: string, description: User id or role name.}3674        permission: {type: string}3675        resource_kind: {type: string, description: 'Absent = every resource. Otherwise `node`, `service`, `site` or `tag`.'}3676        resource_id: {type: string}3677        effect: {$ref: '#/components/schemas/GrantEffect'}3678        created_by: {type: string, format: uuid}3679        created_at: {type: string, format: date-time}3680    PolicyGrantList:3681      type: object3682      required: [items]3683      properties:3684        items: {type: array, items: {$ref: '#/components/schemas/PolicyGrant'}}3685        next_cursor: {type: string}3686    CreatePolicyGrantRequest:3687      type: object3688      required: [subject_kind, subject, permission, effect]3689      properties:3690        subject_kind: {$ref: '#/components/schemas/GrantSubjectKind'}3691        subject: {type: string}3692        permission: {type: string}3693        resource_kind: {type: string, enum: [node, service, site, tag]}3694        resource_id: {type: string}3695        effect: {$ref: '#/components/schemas/GrantEffect'}3696    AgentOverhead:3697      type: object3698      description: Resource use of the agent process itself.3699      properties:3700        cpu_pct: {type: number}3701        rss_bytes: {type: integer, format: int64}3702    Agent:3703      type: object3704      required: [id, node_id, node_alias, version, os, capabilities, cert_serial, cert_fingerprint_sha256, cert_not_after, enrolled_at, freshness]3705      properties:3706        id: {type: string, format: uuid}3707        node_id: {type: string, format: uuid}3708        node_alias: {type: string}3709        version: {type: string}3710        os: {type: string}3711        capabilities: {type: array, items: {type: string}, description: Action types the agent accepts locally.}3712        cert_serial: {type: string}3713        cert_fingerprint_sha256: {type: string, description: Hex SHA-256 of the client certificate.}3714        cert_not_after: {type: string, format: date-time}3715        enrolled_at: {type: string, format: date-time}3716        last_seen_at: {type: string, format: date-time}3717        freshness: {$ref: '#/components/schemas/Freshness'}3718        overhead: {$ref: '#/components/schemas/AgentOverhead'}3719        revoked_at: {type: string, format: date-time}3720        revoked_reason: {type: string}3721    AgentList:3722      type: object3723      required: [items]3724      properties:3725        items: {type: array, items: {$ref: '#/components/schemas/Agent'}}3726        next_cursor: {type: string}3727    RevokeAgentRequest:3728      type: object3729      required: [reason]3730      properties:3731        reason: {type: string, minLength: 1, maxLength: 500}3732    CreateEnrollmentTokenRequest:3733      type: object3734      required: [node_alias, node_kind]3735      properties:3736        node_alias: {type: string, minLength: 1, maxLength: 64, description: Alias of the node; the node is created at enrollment when unknown.}3737        node_kind: {$ref: '#/components/schemas/NodeKind'}3738        ttl_minutes: {type: integer, minimum: 1, maximum: 1440, default: 15}3739    EnrollmentToken:3740      type: object3741      required: [id, node_alias, node_kind, status, created_at, expires_at]3742      properties:3743        id: {type: string, format: uuid}3744        node_alias: {type: string}3745        node_kind: {$ref: '#/components/schemas/NodeKind'}3746        status: {type: string, enum: [pending, consumed, expired, revoked]}3747        created_by: {type: string, format: uuid}3748        created_at: {type: string, format: date-time}3749        expires_at: {type: string, format: date-time}3750        consumed_at: {type: string, format: date-time}3751        revoked_at: {type: string, format: date-time}3752    EnrollmentTokenList:3753      type: object3754      required: [items]3755      properties:3756        items: {type: array, items: {$ref: '#/components/schemas/EnrollmentToken'}}3757        next_cursor: {type: string}3758    EnrollmentTokenCreated:3759      type: object3760      required: [enrollment_token, token, install_hint, ca_fingerprint_sha256]3761      properties:3762        enrollment_token: {$ref: '#/components/schemas/EnrollmentToken'}3763        token: {type: string, description: Enrollment token. Shown once.}3764        install_hint: {type: string, description: Command line to run on the node to install and enroll the agent.}3765        ca_fingerprint_sha256: {type: string, description: Hex SHA-256 of the ingest CA certificate the agent must pin.}3766    Setting:3767      type: object3768      required: [key, value, updated_at]3769      properties:3770        key: {type: string}3771        value: {description: 'Any JSON value (boolean, number, string, array or object) valid for the key.'}3772        description: {type: string}3773        updated_at: {type: string, format: date-time}3774        updated_by: {type: string, format: uuid}3775    SettingList:3776      type: object3777      required: [items]3778      properties:3779        items: {type: array, items: {$ref: '#/components/schemas/Setting'}}3780    PutSettingRequest:3781      type: object3782      required: [value]3783      properties:3784        value: {description: Any JSON value valid for the key.}3785    ComponentStatus:3786      type: object3787      required: [status]3788      properties:3789        status: {type: string, enum: [ok, degraded, down, unknown]}3790        heartbeat_at: {type: string, format: date-time, description: Last heartbeat written by the component.}3791        latency_ms: {type: number}3792        detail: {type: string}3793    BackupStatus:3794      type: object3795      required: [status]3796      properties:3797        status: {type: string, enum: [ok, failed, unknown], description: '`unknown` until a backup run has been observed.'}3798        last_run_at: {type: string, format: date-time}3799        last_success_at: {type: string, format: date-time}3800        detail: {type: string}3801    AdminStatus:3802      type: object3803      required: [version, generated_at, frozen, database, ingest, orchestrator, backup]3804      properties:3805        version: {type: string}3806        commit: {type: string}3807        generated_at: {type: string, format: date-time}3808        frozen: {type: boolean, description: Emergency stop engaged (`orchestrator.frozen`).}3809        database: {$ref: '#/components/schemas/ComponentStatus'}3810        ingest: {$ref: '#/components/schemas/ComponentStatus'}3811        orchestrator: {$ref: '#/components/schemas/ComponentStatus'}3812        backup: {$ref: '#/components/schemas/BackupStatus'}3813        agents_connected: {type: integer}3814        sse_clients: {type: integer}3815        last_report_at: {type: string, format: date-time, description: Last telemetry report ingested from any agent.}38163817    # ───────────── Cluster ─────────────3818    NodeCounts:3819      type: object3820      required: [total, fresh, stale, offline, maintenance]3821      properties:3822        total: {type: integer, description: Non-retired nodes.}3823        fresh: {type: integer}3824        stale: {type: integer}3825        offline: {type: integer}3826        maintenance: {type: integer, description: Nodes in maintenance mode (also counted in their freshness bucket).}3827    CapacityTotal:3828      type: object3829      required: [total, coverage]3830      properties:3831        total: {type: integer, format: int64, description: Sum over the reporting nodes (cores or bytes).}3832        used: {type: integer, format: int64, description: Absent when not applicable (CPU cores) or when no node reports usage.}3833        coverage: {type: integer, description: Number of nodes contributing to the total.}3834    ClusterCapacity:3835      type: object3836      required: [cpu_cores, memory, storage]3837      properties:3838        cpu_cores: {$ref: '#/components/schemas/CapacityTotal'}3839        memory: {$ref: '#/components/schemas/CapacityTotal'}3840        storage: {$ref: '#/components/schemas/CapacityTotal'}3841    SeverityCounts:3842      type: object3843      required: [info, warning, critical]3844      properties:3845        info: {type: integer}3846        warning: {type: integer}3847        critical: {type: integer}3848    JobCounts:3849      type: object3850      required: [queued, running]3851      properties:3852        queued: {type: integer}3853        running: {type: integer}3854    ServiceCounts:3855      type: object3856      required: [online, stopped, errored, unknown]3857      properties:3858        online: {type: integer}3859        stopped: {type: integer}3860        errored: {type: integer}3861        unknown: {type: integer}3862    ModelCounts:3863      type: object3864      required: [total, online]3865      properties:3866        total: {type: integer}3867        online: {type: integer, description: Inference servers with health `ok` on a fresh node.}3868    NasSummary:3869      type: object3870      required: [total, online, offline, unknown]3871      properties:3872        total: {type: integer}3873        online: {type: integer}3874        offline: {type: integer}3875        unknown: {type: integer}3876    BackupSummary:3877      type: object3878      required: [total, ok, failed, unknown]3879      properties:3880        total: {type: integer}3881        ok: {type: integer}3882        failed: {type: integer}3883        unknown: {type: integer}3884        last_success_at: {type: string, format: date-time}3885    ClusterOverview:3886      type: object3887      required: [generated_at, nodes, capacity]3888      properties:3889        generated_at: {type: string, format: date-time}3890        nodes: {$ref: '#/components/schemas/NodeCounts'}3891        capacity: {$ref: '#/components/schemas/ClusterCapacity'}3892        alerts: {$ref: '#/components/schemas/SeverityCounts'}3893        open_incidents: {type: integer}3894        jobs: {$ref: '#/components/schemas/JobCounts'}3895        services: {$ref: '#/components/schemas/ServiceCounts'}3896        models: {$ref: '#/components/schemas/ModelCounts'}3897        nas: {$ref: '#/components/schemas/NasSummary'}3898        backups: {$ref: '#/components/schemas/BackupSummary'}3899        recent_actions: {type: array, items: {$ref: '#/components/schemas/Action'}, description: Last 10 actions; requires `actions.read`.}3900    TrendSeries:3901      type: object3902      required: [group, coverage, points]3903      properties:3904        group: {type: string, description: 'Group value (`cluster`, a site, a role or a tag).'}3905        coverage: {type: integer, description: Number of nodes contributing to the series.}3906        points: {$ref: '#/components/schemas/MetricPoints'}3907    TrendsResponse:3908      type: object3909      required: [metric, unit, range, group_by, resolution, aggregation, series, generated_at]3910      properties:3911        metric: {type: string}3912        unit: {type: string}3913        range: {$ref: '#/components/schemas/TimeRange'}3914        group_by: {$ref: '#/components/schemas/TrendGroupBy'}3915        resolution: {$ref: '#/components/schemas/Resolution'}3916        aggregation: {type: string, enum: [mean, sum], description: 'How nodes are combined: `mean` for ratios and gauges in percent, `sum` for additive quantities.'}3917        series: {type: array, items: {$ref: '#/components/schemas/TrendSeries'}}3918        generated_at: {type: string, format: date-time}39193920    # ───────────── Nodes ─────────────3921    NodeHeadline:3922      type: object3923      description: Headline values of the latest report. A field is absent when the metric is not available.3924      properties:3925        cpu_usage_pct: {type: number}3926        mem_used_pct: {type: number}3927        disk_used_pct: {type: number, description: Fullest internal volume.}3928        load1: {type: number}3929    Node:3930      type: object3931      required: [id, alias, kind, hostname, site, role, environment, tags, registered_via, maintenance, maintenance_reason, created_at, freshness]3932      properties:3933        id: {type: string, format: uuid}3934        alias: {type: string}3935        kind: {$ref: '#/components/schemas/NodeKind'}3936        hostname: {type: string}3937        site: {type: string}3938        role: {type: string}3939        environment: {type: string}3940        tags: {type: array, items: {type: string}}3941        model: {type: string}3942        chip: {type: string}3943        arch: {type: string}3944        cpu_cores: {type: integer}3945        gpu_cores: {type: integer}3946        mem_bytes: {type: integer, format: int64}3947        storage_bytes: {type: integer, format: int64}3948        os_name: {type: string}3949        os_version: {type: string}3950        primary_ip: {type: string, description: Requires `nodes.private.read`. An address is not an identifier (DHCP).}3951        registered_via: {type: string, enum: [manual, agent]}3952        maintenance: {type: boolean}3953        maintenance_reason: {type: string}3954        created_at: {type: string, format: date-time}3955        last_seen_at: {type: string, format: date-time}3956        retired_at: {type: string, format: date-time}3957        observed_at: {type: string, format: date-time, description: Agent-side timestamp of the latest report. Absent when the node never reported.}3958        freshness: {$ref: '#/components/schemas/Freshness'}3959        agent_version: {type: string}3960        headline: {$ref: '#/components/schemas/NodeHeadline'}3961        open_alerts: {type: integer}3962    NodeList:3963      type: object3964      required: [items]3965      properties:3966        items: {type: array, items: {$ref: '#/components/schemas/Node'}}3967        next_cursor: {type: string}3968    ExpectedHardware:3969      type: object3970      description: Declared (not measured) hardware of a manually registered node.3971      properties:3972        model: {type: string, maxLength: 80}3973        chip: {type: string, maxLength: 80}3974        cpu_cores: {type: integer, minimum: 1}3975        mem_bytes: {type: integer, format: int64, minimum: 1}3976        storage_bytes: {type: integer, format: int64, minimum: 1}3977    CreateNodeRequest:3978      type: object3979      required: [alias, kind]3980      properties:3981        alias: {type: string, minLength: 1, maxLength: 64, pattern: '^[A-Za-z0-9][A-Za-z0-9._-]*$'}3982        kind: {$ref: '#/components/schemas/NodeKind'}3983        site: {type: string, maxLength: 64}3984        role: {type: string, maxLength: 64}3985        environment: {type: string, maxLength: 64}3986        tags: {type: array, maxItems: 32, items: {type: string, maxLength: 48}}3987        expected: {$ref: '#/components/schemas/ExpectedHardware'}3988    UpdateNodeRequest:3989      type: object3990      properties:3991        alias: {type: string, minLength: 1, maxLength: 64, pattern: '^[A-Za-z0-9][A-Za-z0-9._-]*$'}3992        site: {type: string, maxLength: 64}3993        role: {type: string, maxLength: 64}3994        environment: {type: string, maxLength: 64}3995        tags: {type: array, maxItems: 32, items: {type: string, maxLength: 48}}3996    CpuPerfLevel:3997      type: object3998      required: [name, cores]3999      properties:4000        name: {type: string, description: 'Name reported by the system (`Performance`, `Efficiency`, `Super`...); never assumed.'}4001        cores: {type: integer}4002    NetworkInterface:4003      type: object4004      required: [node_id, node_alias, name, kind, up, ipv4, ipv6, freshness]4005      properties:4006        node_id: {type: string, format: uuid}4007        node_alias: {type: string}4008        name: {type: string, description: 'System name, for example `en0` or `wg1`.'}4009        kind: {type: string, enum: [ethernet, wifi, wireguard, tailscale, loopback, other]}4010        up: {type: boolean}4011        mac: {type: string, description: Requires `nodes.private.read`.}4012        ipv4: {type: array, items: {type: string}, description: Requires `nodes.private.read` (empty otherwise).}4013        ipv6: {type: array, items: {type: string}, description: Requires `nodes.private.read` (empty otherwise).}4014        link_speed_mbps: {type: integer}4015        rx_bytes_per_s: {type: number}4016        tx_bytes_per_s: {type: number}4017        rx_errors_per_s: {type: number}4018        tx_errors_per_s: {type: number}4019        observed_at: {type: string, format: date-time}4020        freshness: {$ref: '#/components/schemas/Freshness'}4021    NetworkInterfaceList:4022      type: object4023      required: [items]4024      properties:4025        items: {type: array, items: {$ref: '#/components/schemas/NetworkInterface'}}4026        next_cursor: {type: string}4027    MetricValue:4028      type: object4029      required: [availability]4030      properties:4031        value: {type: number, format: double, description: Present only when `availability` is `available` or `stale`.}4032        unit: {type: string}4033        availability: {$ref: '#/components/schemas/Availability'}4034        reason: {type: string, description: 'Why the metric is not available, for example "requires root (powermetrics)".'}4035    NodeDetail:4036      type: object4037      required: [node, cpu_levels, interfaces, volumes, latest]4038      properties:4039        node: {$ref: '#/components/schemas/Node'}4040        os_build: {type: string}4041        hardware_uuid: {type: string, description: Stable hardware identifier. Requires `nodes.private.read`.}4042        serial_number: {type: string, description: Requires `nodes.private.read`.}4043        cpu_levels: {type: array, items: {$ref: '#/components/schemas/CpuPerfLevel'}}4044        interfaces: {type: array, items: {$ref: '#/components/schemas/NetworkInterface'}}4045        volumes: {type: array, items: {$ref: '#/components/schemas/Volume'}}4046        inventory_at: {type: string, format: date-time}4047        agent: {$ref: '#/components/schemas/Agent'}4048        latest:4049          type: object4050          description: 'Latest value of every catalog metric without label, keyed by metric name (for example `cpu.usage`). Metrics that cannot be measured are present with their availability and no value.'4051          additionalProperties: {$ref: '#/components/schemas/MetricValue'}4052        active_maintenance_window_id: {type: string, format: uuid}4053    MetricSeries:4054      type: object4055      required: [metric, unit, label, points]4056      properties:4057        metric: {type: string}4058        unit: {type: string}4059        label: {type: string, description: Empty for metrics without label.}4060        node_id: {type: string, format: uuid, description: Present in comparisons.}4061        node_alias: {type: string, description: Present in comparisons.}4062        points: {$ref: '#/components/schemas/MetricPoints'}4063    MetricSeriesResponse:4064      type: object4065      required: [resolution, from, to, series, availability]4066      properties:4067        resolution: {$ref: '#/components/schemas/Resolution'}4068        from: {type: string, format: date-time}4069        to: {type: string, format: date-time}4070        series: {type: array, items: {$ref: '#/components/schemas/MetricSeries'}}4071        availability:4072          type: object4073          description: Current availability of each requested metric, keyed by metric name.4074          additionalProperties: {$ref: '#/components/schemas/Availability'}4075    MetricCompareResponse:4076      type: object4077      required: [metric, unit, resolution, from, to, series, availability]4078      properties:4079        metric: {type: string}4080        unit: {type: string}4081        resolution: {$ref: '#/components/schemas/Resolution'}4082        from: {type: string, format: date-time}4083        to: {type: string, format: date-time}4084        series: {type: array, items: {$ref: '#/components/schemas/MetricSeries'}}4085        availability:4086          type: object4087          description: Current availability of the metric on each node, keyed by node id.4088          additionalProperties: {$ref: '#/components/schemas/Availability'}4089    MetricCatalogEntry:4090      type: object4091      required: [name, unit, kind, interval_s, labeled, source, description]4092      properties:4093        name: {type: string}4094        unit: {type: string}4095        kind: {type: string, enum: [gauge, counter_rate]}4096        interval_s: {type: integer}4097        labeled: {type: boolean}4098        source: {type: string, description: 'Provenance, for example `sysctl`, `ioreg` or `df`.'}4099        description: {type: string}4100    MetricCatalog:4101      type: object4102      required: [items]4103      properties:4104        items: {type: array, items: {$ref: '#/components/schemas/MetricCatalogEntry'}}4105    Process:4106      type: object4107      required: [pid, name]4108      properties:4109        pid: {type: integer}4110        name: {type: string}4111        user: {type: string}4112        cpu_pct: {type: number}4113        mem_bytes: {type: integer, format: int64}4114        command: {type: string, description: Redacted command line; requires `nodes.private.read`.}4115    ProcessList:4116      type: object4117      required: [node_id, freshness, availability, items]4118      properties:4119        node_id: {type: string, format: uuid}4120        observed_at: {type: string, format: date-time}4121        freshness: {$ref: '#/components/schemas/Freshness'}4122        availability: {$ref: '#/components/schemas/Availability'}4123        items: {type: array, items: {$ref: '#/components/schemas/Process'}}4124    HealthBucket:4125      type: object4126      required: [start, end, state, alerts_firing]4127      properties:4128        start: {type: string, format: date-time}4129        end: {type: string, format: date-time}4130        state: {type: string, enum: [up, degraded, down, maintenance, unknown], description: '`up`: reports received over the whole bucket; `degraded`: partial; `down`: none; `unknown`: before the first report.'}4131        alerts_firing: {type: integer}4132    HealthHistory:4133      type: object4134      required: [node_id, range, bucket_seconds, items]4135      properties:4136        node_id: {type: string, format: uuid}4137        range: {$ref: '#/components/schemas/TimeRange'}4138        bucket_seconds: {type: integer}4139        uptime_ratio: {type: number, minimum: 0, maximum: 1, description: Share of known buckets that are `up` or `degraded`. Absent when nothing is known.}4140        items: {type: array, items: {$ref: '#/components/schemas/HealthBucket'}}41414142    # ───────────── Services, models ─────────────4143    ServiceHealth:4144      type: object4145      required: [status]4146      properties:4147        status: {type: string, enum: [ok, failing, unknown]}4148        checked_at: {type: string, format: date-time}4149        latency_ms: {type: number}4150        detail: {type: string}4151    Service:4152      type: object4153      required: [id, node_id, node_alias, manager, name, state, ports, managed, first_seen_at, last_seen_at, freshness]4154      properties:4155        id: {type: string, format: uuid}4156        node_id: {type: string, format: uuid}4157        node_alias: {type: string}4158        manager: {$ref: '#/components/schemas/ServiceManager'}4159        name: {type: string}4160        state: {$ref: '#/components/schemas/ServiceState'}4161        pid: {type: integer}4162        restarts: {type: integer}4163        mem_bytes: {type: integer, format: int64}4164        cpu_pct: {type: number}4165        uptime_s: {type: integer, format: int64}4166        version: {type: string}4167        ports: {type: array, items: {type: integer}}4168        app: {type: string, description: Logical application when known.}4169        public_url: {type: string}4170        health: {$ref: '#/components/schemas/ServiceHealth'}4171        managed: {type: boolean, description: True when start / stop / restart actions are allowed on the server side.}4172        meta: {type: object, additionalProperties: true, description: Raw manager details (redacted). Only in the single-service view.}4173        first_seen_at: {type: string, format: date-time}4174        last_seen_at: {type: string, format: date-time}4175        gone_at: {type: string, format: date-time, description: Set when the manager no longer lists the service.}4176        observed_at: {type: string, format: date-time}4177        freshness: {$ref: '#/components/schemas/Freshness'}4178    ServiceList:4179      type: object4180      required: [items]4181      properties:4182        items: {type: array, items: {$ref: '#/components/schemas/Service'}}4183        next_cursor: {type: string}4184    UpdateServiceRequest:4185      type: object4186      properties:4187        managed: {type: boolean}4188        public_url: {type: string, maxLength: 300, description: Empty string clears the URL.}4189    ServiceHistoryEntry:4190      type: object4191      required: [ts, kind, summary]4192      properties:4193        ts: {type: string, format: date-time}4194        kind: {type: string, enum: [restart, state_change, action, deploy, appeared, disappeared]}4195        summary: {type: string}4196        from_state: {$ref: '#/components/schemas/ServiceState'}4197        to_state: {$ref: '#/components/schemas/ServiceState'}4198        action_id: {type: string, format: uuid}4199        actor_display_name: {type: string}4200        version: {type: string}4201    ServiceHistory:4202      type: object4203      required: [items]4204      properties:4205        items: {type: array, items: {$ref: '#/components/schemas/ServiceHistoryEntry'}}4206        next_cursor: {type: string}4207    MetricSupport:4208      type: object4209      required: [availability]4210      properties:4211        availability: {$ref: '#/components/schemas/Availability'}4212        reason: {type: string, description: Why the metric family is not exposed by this kind of server.}4213    InferenceMetricsSupport:4214      type: object4215      description: Explicit statement of what the inference server exposes. Nothing here is ever estimated.4216      required: [requests, tokens_per_s, ttft, latency, queue]4217      properties:4218        requests: {$ref: '#/components/schemas/MetricSupport'}4219        tokens_per_s: {$ref: '#/components/schemas/MetricSupport'}4220        ttft: {$ref: '#/components/schemas/MetricSupport'}4221        latency: {$ref: '#/components/schemas/MetricSupport'}4222        queue: {$ref: '#/components/schemas/MetricSupport'}4223    InferenceServer:4224      type: object4225      required: [id, node_id, node_alias, kind, port, health, listed_models, metrics_support, last_seen_at, freshness]4226      properties:4227        id: {type: string, format: uuid}4228        node_id: {type: string, format: uuid}4229        node_alias: {type: string}4230        kind: {type: string, description: 'Server software: `mlx_lm`, `ollama`, `llama.cpp`...'}4231        port: {type: integer}4232        model: {type: string, description: Model announced on the command line.}4233        quantization: {type: string}4234        pid: {type: integer}4235        rss_bytes: {type: integer, format: int64}4236        uptime_s: {type: integer, format: int64}4237        disk_bytes: {type: integer, format: int64, description: Size on disk of the model cache.}4238        health: {$ref: '#/components/schemas/InferenceHealth'}4239        health_at: {type: string, format: date-time}4240        health_latency_ms: {type: number}4241        listed_models: {type: array, items: {type: string}, description: Model ids returned by `GET /v1/models` of the server.}4242        metrics_support: {$ref: '#/components/schemas/InferenceMetricsSupport'}4243        last_seen_at: {type: string, format: date-time}4244        gone_at: {type: string, format: date-time}4245        observed_at: {type: string, format: date-time}4246        freshness: {$ref: '#/components/schemas/Freshness'}4247    InferenceServerList:4248      type: object4249      required: [items]4250      properties:4251        items: {type: array, items: {$ref: '#/components/schemas/InferenceServer'}}4252        next_cursor: {type: string}42534254    # ───────────── Jobs ─────────────4255    JobTemplate:4256      type: object4257      required: [name, title, description, params_schema, timeout_s, max_attempts, available]4258      properties:4259        name: {type: string}4260        title: {type: string}4261        description: {type: string}4262        params_schema: {type: object, additionalProperties: true, description: JSON Schema of `params`.}4263        timeout_s: {type: integer}4264        max_attempts: {type: integer}4265        available: {type: boolean, description: True when at least one online agent declares the template.}4266        node_ids: {type: array, items: {type: string, format: uuid}, description: Nodes whose agent declares the template.}4267    JobTemplateList:4268      type: object4269      required: [items]4270      properties:4271        items: {type: array, items: {$ref: '#/components/schemas/JobTemplate'}}4272    JobPlacement:4273      type: object4274      description: 'Placement constraints. With no field the scheduler picks any eligible node.'4275      properties:4276        node_id: {type: string, format: uuid}4277        site: {type: string}4278        role: {type: string}4279        tags: {type: array, items: {type: string}}4280    Job:4281      type: object4282      required: [id, template, params, state, placement, attempt, max_attempts, depends_on, created_at]4283      properties:4284        id: {type: string, format: uuid}4285        template: {type: string}4286        owner_id: {type: string, format: uuid}4287        owner_display_name: {type: string}4288        params: {type: object, additionalProperties: true}4289        state: {$ref: '#/components/schemas/JobState'}4290        node_id: {type: string, format: uuid}4291        node_alias: {type: string}4292        placement: {$ref: '#/components/schemas/JobPlacement'}4293        progress: {type: number, minimum: 0, maximum: 1, description: Absent when the template reports no progress.}4294        attempt: {type: integer}4295        max_attempts: {type: integer}4296        schedule_id: {type: string, format: uuid}4297        depends_on: {type: array, items: {type: string, format: uuid}}4298        action_id: {type: string, format: uuid, description: Current or last `job.run` action.}4299        created_at: {type: string, format: date-time}4300        started_at: {type: string, format: date-time}4301        finished_at: {type: string, format: date-time}4302        next_attempt_at: {type: string, format: date-time}4303        result: {type: object, additionalProperties: true}4304        error: {type: string}4305        usage: {type: object, additionalProperties: true, description: 'Measured resource usage (CPU seconds, peak RSS...) when reported.'}4306    JobList:4307      type: object4308      required: [items]4309      properties:4310        items: {type: array, items: {$ref: '#/components/schemas/Job'}}4311        next_cursor: {type: string}4312    CreateJobRequest:4313      type: object4314      required: [template]4315      properties:4316        template: {type: string}4317        params: {type: object, additionalProperties: true}4318        placement: {$ref: '#/components/schemas/JobPlacement'}4319        max_attempts: {type: integer, minimum: 1, maximum: 5, default: 1}4320        depends_on: {type: array, maxItems: 16, items: {type: string, format: uuid}}4321    JobSchedule:4322      type: object4323      required: [id, name, template, params, placement, every_seconds, enabled, next_run_at, created_at]4324      properties:4325        id: {type: string, format: uuid}4326        name: {type: string}4327        template: {type: string}4328        params: {type: object, additionalProperties: true}4329        placement: {$ref: '#/components/schemas/JobPlacement'}4330        every_seconds: {type: integer, minimum: 60}4331        enabled: {type: boolean}4332        next_run_at: {type: string, format: date-time}4333        last_run_at: {type: string, format: date-time}4334        created_by: {type: string, format: uuid}4335        created_at: {type: string, format: date-time}4336    JobScheduleList:4337      type: object4338      required: [items]4339      properties:4340        items: {type: array, items: {$ref: '#/components/schemas/JobSchedule'}}4341        next_cursor: {type: string}4342    CreateJobScheduleRequest:4343      type: object4344      required: [name, template, every_seconds]4345      properties:4346        name: {type: string, minLength: 1, maxLength: 80}4347        template: {type: string}4348        params: {type: object, additionalProperties: true}4349        placement: {$ref: '#/components/schemas/JobPlacement'}4350        every_seconds: {type: integer, minimum: 60}4351        enabled: {type: boolean, default: true}4352        first_run_at: {type: string, format: date-time, description: Defaults to now + `every_seconds`.}4353    UpdateJobScheduleRequest:4354      type: object4355      properties:4356        name: {type: string, minLength: 1, maxLength: 80}4357        params: {type: object, additionalProperties: true}4358        placement: {$ref: '#/components/schemas/JobPlacement'}4359        every_seconds: {type: integer, minimum: 60}4360        enabled: {type: boolean}43614362    # ───────────── Alerts, incidents ─────────────4363    AlertScope:4364      type: object4365      description: 'Exactly one form: `{"all": true}`, `{"node_ids": [...]}` or `{"tags": [...]}`.'4366      properties:4367        all: {type: boolean}4368        node_ids: {type: array, items: {type: string, format: uuid}}4369        tags: {type: array, items: {type: string}}4370    AlertRuleKind: {type: string, enum: [threshold, absence, service_state]}4371    AlertOp:4372      type: string4373      enum: [gt, gte, lt, lte]4374      description: 'Comparison of the metric with the threshold: greater than, greater or equal, less than, less or equal.'4375    AlertRule:4376      type: object4377      required: [id, name, description, enabled, builtin, kind, for_seconds, clear_seconds, severity, scope, notify, created_at, updated_at]4378      properties:4379        id: {type: string, format: uuid}4380        name: {type: string}4381        description: {type: string}4382        enabled: {type: boolean}4383        builtin: {type: boolean}4384        kind: {$ref: '#/components/schemas/AlertRuleKind'}4385        metric: {type: string, description: Threshold rules.}4386        label_match: {type: string, description: 'Threshold rules on labeled metrics: exact label or `*`.'}4387        op: {$ref: '#/components/schemas/AlertOp'}4388        threshold: {type: number}4389        clear_threshold: {type: number, description: Hysteresis; defaults to `threshold`.}4390        for_seconds: {type: integer, minimum: 0, description: The condition must hold this long before firing.}4391        clear_seconds: {type: integer, minimum: 0, description: The condition must be clear this long before resolving.}4392        severity: {$ref: '#/components/schemas/Severity'}4393        scope: {$ref: '#/components/schemas/AlertScope'}4394        notify: {type: boolean}4395        created_by: {type: string, format: uuid}4396        created_at: {type: string, format: date-time}4397        updated_at: {type: string, format: date-time}4398    AlertRuleList:4399      type: object4400      required: [items]4401      properties:4402        items: {type: array, items: {$ref: '#/components/schemas/AlertRule'}}4403        next_cursor: {type: string}4404    AlertRuleInput:4405      type: object4406      required: [name, kind]4407      description: '`threshold` rules require `metric`, `op` and `threshold`; `metric` is a catalog metric, a server-derived one (`disk.used_pct`, `swap.used_pct`) or a server-computed one (`mcc.agent.cert_days_left`, `mcc.audit.denied_10m`, `mcc.auth.new_device_login`). `absence` rules fire when a node stops reporting for `for_seconds`. `service_state` rules fire when a managed service is `errored` or `stopped` (`metric` may restrict the states, for example `errored`; `label_match` may name one service as `manager:name`).'4408      properties:4409        name: {type: string, minLength: 1, maxLength: 120}4410        description: {type: string, maxLength: 1000}4411        enabled: {type: boolean, default: true}4412        kind: {$ref: '#/components/schemas/AlertRuleKind'}4413        metric: {type: string}4414        label_match: {type: string}4415        op: {$ref: '#/components/schemas/AlertOp'}4416        threshold: {type: number}4417        clear_threshold: {type: number}4418        for_seconds: {type: integer, minimum: 0, maximum: 86400, default: 300}4419        clear_seconds: {type: integer, minimum: 0, maximum: 86400, default: 120}4420        severity: {$ref: '#/components/schemas/Severity'}4421        scope: {$ref: '#/components/schemas/AlertScope'}4422        notify: {type: boolean, default: true}4423    UpdateAlertRuleRequest:4424      type: object4425      properties:4426        name: {type: string, minLength: 1, maxLength: 120}4427        description: {type: string, maxLength: 1000}4428        enabled: {type: boolean}4429        metric: {type: string}4430        label_match: {type: string}4431        op: {$ref: '#/components/schemas/AlertOp'}4432        threshold: {type: number}4433        clear_threshold: {type: number}4434        for_seconds: {type: integer, minimum: 0, maximum: 86400}4435        clear_seconds: {type: integer, minimum: 0, maximum: 86400}4436        severity: {$ref: '#/components/schemas/Severity'}4437        scope: {$ref: '#/components/schemas/AlertScope'}4438        notify: {type: boolean}4439    ValidateAlertRuleRequest:4440      type: object4441      required: [rule]4442      properties:4443        rule: {$ref: '#/components/schemas/AlertRuleInput'}4444        from: {type: string, format: date-time, description: Defaults to 7 days ago.}4445        to: {type: string, format: date-time, description: Defaults to now.}4446    AlertFiringInterval:4447      type: object4448      required: [node_id, node_alias, label, started_at]4449      properties:4450        node_id: {type: string, format: uuid}4451        node_alias: {type: string}4452        label: {type: string}4453        started_at: {type: string, format: date-time}4454        ended_at: {type: string, format: date-time, description: Absent when the rule would still be firing at the end of the window.}4455        peak_value: {type: number}4456    AlertRuleValidation:4457      type: object4458      required: [evaluated_from, evaluated_to, resolution, nodes_evaluated, total_firings, intervals, warnings]4459      properties:4460        evaluated_from: {type: string, format: date-time}4461        evaluated_to: {type: string, format: date-time}4462        resolution: {$ref: '#/components/schemas/Resolution'}4463        nodes_evaluated: {type: integer}4464        nodes_without_data: {type: integer, description: Nodes in scope for which the metric has no data in the window.}4465        total_firings: {type: integer}4466        intervals: {type: array, items: {$ref: '#/components/schemas/AlertFiringInterval'}}4467        warnings: {type: array, items: {type: string}, description: 'For example "evaluated on 1-minute aggregates: spikes shorter than a minute are not visible".'}4468    Alert:4469      type: object4470      required: [id, rule_id, rule_name, label, fingerprint, state, severity, summary, started_at, last_eval_at, flap_count]4471      properties:4472        id: {type: string, format: uuid}4473        rule_id: {type: string, format: uuid}4474        rule_name: {type: string}4475        node_id: {type: string, format: uuid}4476        node_alias: {type: string}4477        label: {type: string}4478        fingerprint: {type: string}4479        state: {$ref: '#/components/schemas/AlertState'}4480        severity: {$ref: '#/components/schemas/Severity'}4481        summary: {type: string}4482        last_value: {type: number}4483        started_at: {type: string, format: date-time}4484        fired_at: {type: string, format: date-time}4485        acknowledged_at: {type: string, format: date-time}4486        acknowledged_by: {type: string, format: uuid}4487        acknowledged_by_display_name: {type: string}4488        resolved_at: {type: string, format: date-time}4489        last_eval_at: {type: string, format: date-time}4490        flap_count: {type: integer}4491        suppressed_by: {type: string, enum: [silence, maintenance], description: Present when notifications are suppressed.}4492        incident_id: {type: string, format: uuid}4493    AlertList:4494      type: object4495      required: [items]4496      properties:4497        items: {type: array, items: {$ref: '#/components/schemas/Alert'}}4498        next_cursor: {type: string}4499    TimelineEvent:4500      type: object4501      required: [id, ts, kind, body]4502      properties:4503        id: {type: string, format: uuid}4504        ts: {type: string, format: date-time}4505        kind: {type: string, description: 'One of `opened`, `fired`, `acknowledged`, `resolved`, `reopened`, `comment`, `suppressed`, `notified`, `state_changed`, `alert_linked`, `alert_unlinked`, `owner_changed` (open list).'}4506        actor_id: {type: string, format: uuid, description: Absent for system events.}4507        actor_display_name: {type: string}4508        body: {type: string}4509    AlertDetail:4510      type: object4511      required: [alert, timeline]4512      properties:4513        alert: {$ref: '#/components/schemas/Alert'}4514        timeline: {type: array, items: {$ref: '#/components/schemas/TimelineEvent'}}4515    AlertTransitionRequest:4516      type: object4517      properties:4518        comment: {type: string, maxLength: 4000}4519    CommentRequest:4520      type: object4521      required: [body]4522      properties:4523        body: {type: string, minLength: 1, maxLength: 4000}4524    Silence:4525      type: object4526      required: [id, reason, scope, starts_at, ends_at, active, created_at]4527      properties:4528        id: {type: string, format: uuid}4529        reason: {type: string}4530        scope: {$ref: '#/components/schemas/AlertScope'}4531        rule_id: {type: string, format: uuid, description: Limits the silence to one rule.}4532        starts_at: {type: string, format: date-time}4533        ends_at: {type: string, format: date-time}4534        active: {type: boolean}4535        maintenance_window_id: {type: string, format: uuid, description: Set for silences owned by a maintenance window.}4536        created_by: {type: string, format: uuid}4537        created_at: {type: string, format: date-time}4538    SilenceList:4539      type: object4540      required: [items]4541      properties:4542        items: {type: array, items: {$ref: '#/components/schemas/Silence'}}4543        next_cursor: {type: string}4544    CreateSilenceRequest:4545      type: object4546      required: [reason, scope, ends_at]4547      properties:4548        reason: {type: string, minLength: 1, maxLength: 500}4549        scope: {$ref: '#/components/schemas/AlertScope'}4550        rule_id: {type: string, format: uuid}4551        starts_at: {type: string, format: date-time, description: Defaults to now.}4552        ends_at: {type: string, format: date-time}4553    Incident:4554      type: object4555      required: [id, title, severity, state, summary, opened_at, alert_count]4556      properties:4557        id: {type: string, format: uuid}4558        title: {type: string}4559        severity: {$ref: '#/components/schemas/Severity'}4560        state: {$ref: '#/components/schemas/IncidentState'}4561        summary: {type: string}4562        owner_id: {type: string, format: uuid}4563        owner_display_name: {type: string}4564        opened_at: {type: string, format: date-time}4565        resolved_at: {type: string, format: date-time}4566        created_by: {type: string, format: uuid}4567        alert_count: {type: integer}4568    IncidentList:4569      type: object4570      required: [items]4571      properties:4572        items: {type: array, items: {$ref: '#/components/schemas/Incident'}}4573        next_cursor: {type: string}4574    IncidentDetail:4575      type: object4576      required: [incident, timeline, alerts]4577      properties:4578        incident: {$ref: '#/components/schemas/Incident'}4579        timeline: {type: array, items: {$ref: '#/components/schemas/TimelineEvent'}}4580        alerts: {type: array, items: {$ref: '#/components/schemas/Alert'}}4581    CreateIncidentRequest:4582      type: object4583      required: [title, severity]4584      properties:4585        title: {type: string, minLength: 1, maxLength: 160}4586        severity: {$ref: '#/components/schemas/Severity'}4587        summary: {type: string, maxLength: 8000}4588        owner_id: {type: string, format: uuid}4589        alert_ids: {type: array, maxItems: 100, items: {type: string, format: uuid}}4590    UpdateIncidentRequest:4591      type: object4592      properties:4593        title: {type: string, minLength: 1, maxLength: 160}4594        severity: {$ref: '#/components/schemas/Severity'}4595        state: {$ref: '#/components/schemas/IncidentState'}4596        summary: {type: string, maxLength: 8000}4597        owner_id: {type: string, format: uuid}4598        add_alert_ids: {type: array, maxItems: 100, items: {type: string, format: uuid}}4599        remove_alert_ids: {type: array, maxItems: 100, items: {type: string, format: uuid}}46004601    # ───────────── Maintenance ─────────────4602    MaintenanceScope:4603      type: object4604      required: [node_ids]4605      properties:4606        node_ids: {type: array, items: {type: string, format: uuid}, description: 'Nodes concerned. Empty = informational window touching no node (no maintenance mode, no silence).'}4607    MaintenanceWindow:4608      type: object4609      required: [id, title, description, category, starts_at, ends_at, timezone, recurrence, scope, set_maintenance_mode, silence_alerts, status, created_at, updated_at]4610      properties:4611        id: {type: string, format: uuid}4612        title: {type: string}4613        description: {type: string}4614        category: {$ref: '#/components/schemas/MaintenanceCategory'}4615        starts_at: {type: string, format: date-time, description: Start of the first occurrence.}4616        ends_at: {type: string, format: date-time, description: End of the first occurrence.}4617        timezone: {type: string, description: 'IANA time zone used to expand recurrences, for example `America/Toronto`.'}4618        recurrence: {$ref: '#/components/schemas/MaintenanceRecurrence'}4619        recurrence_until: {type: string, format: date-time}4620        scope: {$ref: '#/components/schemas/MaintenanceScope'}4621        set_maintenance_mode: {type: boolean}4622        silence_alerts: {type: boolean}4623        status: {$ref: '#/components/schemas/MaintenanceStatus'}4624        activated_occurrence: {type: string, format: date-time, description: Start of the occurrence currently applied by the scheduler.}4625        created_by: {type: string, format: uuid}4626        created_by_display_name: {type: string}4627        created_at: {type: string, format: date-time}4628        updated_at: {type: string, format: date-time}4629        warnings: {type: array, items: {type: string}, description: 'Only in the answers to create and update: non-blocking warnings, for example an overlap with another window on the same node.'}4630    MaintenanceOccurrence:4631      type: object4632      required: [window, occurrence_start, occurrence_end, note_count]4633      properties:4634        window: {$ref: '#/components/schemas/MaintenanceWindow'}4635        occurrence_start: {type: string, format: date-time}4636        occurrence_end: {type: string, format: date-time}4637        active: {type: boolean, description: True for the occurrence in progress.}4638        note_count: {type: integer, description: Notes attached to this occurrence (or to the window for non-recurring windows).}4639    MaintenanceOccurrenceList:4640      type: object4641      required: [items, truncated]4642      properties:4643        items: {type: array, items: {$ref: '#/components/schemas/MaintenanceOccurrence'}}4644        truncated: {type: boolean}4645    CreateMaintenanceWindowRequest:4646      type: object4647      required: [title, starts_at, ends_at, scope]4648      properties:4649        title: {type: string, minLength: 1, maxLength: 160}4650        description: {type: string, maxLength: 8000}4651        category: {$ref: '#/components/schemas/MaintenanceCategory'}4652        starts_at: {type: string, format: date-time}4653        ends_at: {type: string, format: date-time}4654        timezone: {type: string, default: America/Toronto}4655        recurrence: {$ref: '#/components/schemas/MaintenanceRecurrence'}4656        recurrence_until: {type: string, format: date-time}4657        scope: {$ref: '#/components/schemas/MaintenanceScope'}4658        set_maintenance_mode: {type: boolean, default: true}4659        silence_alerts: {type: boolean, default: true}4660    UpdateMaintenanceWindowRequest:4661      type: object4662      properties:4663        title: {type: string, minLength: 1, maxLength: 160}4664        description: {type: string, maxLength: 8000}4665        category: {$ref: '#/components/schemas/MaintenanceCategory'}4666        starts_at: {type: string, format: date-time}4667        ends_at: {type: string, format: date-time}4668        timezone: {type: string}4669        recurrence: {$ref: '#/components/schemas/MaintenanceRecurrence'}4670        recurrence_until: {type: string, format: date-time}4671        scope: {$ref: '#/components/schemas/MaintenanceScope'}4672        set_maintenance_mode: {type: boolean}4673        silence_alerts: {type: boolean}4674    CompleteMaintenanceWindowRequest:4675      type: object4676      properties:4677        note: {type: string, minLength: 1, maxLength: 20000, description: Closing note stored as a maintenance note.}4678    MaintenanceNote:4679      type: object4680      required: [id, author_id, author_display_name, body, pinned, created_at]4681      properties:4682        id: {type: string, format: uuid}4683        window_id: {type: string, format: uuid}4684        node_id: {type: string, format: uuid}4685        node_alias: {type: string}4686        occurrence: {type: string, format: date-time, description: Start of the occurrence the note belongs to.}4687        author_id: {type: string, format: uuid}4688        author_display_name: {type: string}4689        body: {type: string, description: Plain text or Markdown; rendered sanitized by clients.}4690        pinned: {type: boolean}4691        created_at: {type: string, format: date-time}4692        edited_at: {type: string, format: date-time}4693    MaintenanceNoteList:4694      type: object4695      required: [items]4696      properties:4697        items: {type: array, items: {$ref: '#/components/schemas/MaintenanceNote'}}4698        next_cursor: {type: string}4699    CreateMaintenanceNoteRequest:4700      type: object4701      required: [body]4702      properties:4703        window_id: {type: string, format: uuid}4704        node_id: {type: string, format: uuid}4705        occurrence: {type: string, format: date-time}4706        body: {type: string, minLength: 1, maxLength: 20000}4707        pinned: {type: boolean, default: false}4708    UpdateMaintenanceNoteRequest:4709      type: object4710      properties:4711        body: {type: string, minLength: 1, maxLength: 20000}4712        pinned: {type: boolean}47134714    # ───────────── Network, storage ─────────────4715    TopologyNode:4716      type: object4717      required: [id, kind, label]4718      properties:4719        id: {type: string, description: 'Vertex id: the node id for cluster nodes, `lan-gateway` or `wg-hub` for infrastructure vertices.'}4720        kind: {type: string, enum: [node, lan_gateway, wg_hub]}4721        label: {type: string}4722        node_id: {type: string, format: uuid, description: 'Cluster node behind the vertex (also set for the hub when it is itself a node).'}4723        address: {type: string, description: Requires `nodes.private.read`.}4724        freshness: {$ref: '#/components/schemas/Freshness'}4725    TopologyLink:4726      type: object4727      required: [id, source, target, kind, state, latency_availability, loss_availability, freshness]4728      properties:4729        id: {type: string}4730        source: {type: string, description: Vertex id of the node that measures the link.}4731        target: {type: string}4732        kind: {type: string, enum: [lan, wireguard]}4733        interface: {type: string, description: Interface carrying the link on the source node.}4734        state: {type: string, enum: [up, down, unknown]}4735        latency_ms: {type: number, description: Present only when `latency_availability` is `available` or `stale`.}4736        loss_pct: {type: number, description: Present only when `loss_availability` is `available` or `stale`.}4737        latency_availability: {$ref: '#/components/schemas/Availability'}4738        loss_availability: {$ref: '#/components/schemas/Availability'}4739        observed_at: {type: string, format: date-time}4740        freshness: {$ref: '#/components/schemas/Freshness'}4741    NetworkTopology:4742      type: object4743      required: [generated_at, nodes, links]4744      properties:4745        generated_at: {type: string, format: date-time}4746        nodes: {type: array, items: {$ref: '#/components/schemas/TopologyNode'}}4747        links: {type: array, items: {$ref: '#/components/schemas/TopologyLink'}}4748    Volume:4749      type: object4750      required: [id, node_id, node_alias, mount, kind, last_seen_at, freshness]4751      properties:4752        id: {type: string, format: uuid}4753        node_id: {type: string, format: uuid}4754        node_alias: {type: string}4755        mount: {type: string}4756        device: {type: string}4757        fs: {type: string}4758        kind: {$ref: '#/components/schemas/VolumeKind'}4759        total_bytes: {type: integer, format: int64}4760        used_bytes: {type: integer, format: int64}4761        smart_status: {type: string, description: 'Summary status as reported by the system (for example `Verified`). Absent when not observable.'}4762        remote: {type: string, description: Remote of a network volume; requires `nodes.private.read`.}4763        last_seen_at: {type: string, format: date-time}4764        gone_at: {type: string, format: date-time}4765        observed_at: {type: string, format: date-time}4766        freshness: {$ref: '#/components/schemas/Freshness'}4767    VolumeList:4768      type: object4769      required: [items]4770      properties:4771        items: {type: array, items: {$ref: '#/components/schemas/Volume'}}4772        next_cursor: {type: string}4773    NasTarget:4774      type: object4775      required: [id, name, share, protocol, note, state, mounted_on]4776      properties:4777        id: {type: string, format: uuid}4778        name: {type: string}4779        host: {type: string, description: IP address. Requires `nodes.private.read`.}4780        share: {type: string}4781        protocol: {type: string, enum: [smb, nfs, afp]}4782        note: {type: string}4783        state: {type: string, enum: [online, offline, unknown]}4784        state_at: {type: string, format: date-time, description: When the state was last observed.}4785        observed_by: {type: string, format: uuid, description: Node whose agent made the observation.}4786        latency_ms: {type: number}4787        mounted_on: {type: integer, description: Number of nodes with the share mounted.}4788        total_bytes: {type: integer, format: int64, description: Absent when not observed.}4789        used_bytes: {type: integer, format: int64, description: Absent when not observed.}4790    NasTargetList:4791      type: object4792      required: [items]4793      properties:4794        items: {type: array, items: {$ref: '#/components/schemas/NasTarget'}}4795    CreateNasTargetRequest:4796      type: object4797      required: [name, host]4798      properties:4799        name: {type: string, minLength: 1, maxLength: 64}4800        host: {type: string, description: IPv4 or IPv6 address.}4801        share: {type: string, maxLength: 120}4802        protocol: {type: string, enum: [smb, nfs, afp], default: smb}4803        note: {type: string, maxLength: 500}4804    Backup:4805      type: object4806      required: [id, name, kind, last_status, detail]4807      properties:4808        id: {type: string, format: uuid}4809        name: {type: string}4810        node_id: {type: string, format: uuid}4811        node_alias: {type: string}4812        kind: {type: string, description: 'For example `postgres`, `app` or `mcc`.'}4813        last_run_at: {type: string, format: date-time}4814        last_success_at: {type: string, format: date-time}4815        last_status: {type: string, enum: [ok, failed, unknown]}4816        size_bytes: {type: integer, format: int64}4817        detail: {type: string}4818        observed_at: {type: string, format: date-time}4819    BackupList:4820      type: object4821      required: [items]4822      properties:4823        items: {type: array, items: {$ref: '#/components/schemas/Backup'}}48244825    # ───────────── Actions ─────────────4826    ActionType:4827      type: object4828      required: [type, title, description, criticality, permission, target_kinds, params_schema, requires_step_up, requires_justification, requires_confirmation, requires_approval, timeout_s, lock_scope, available]4829      properties:4830        type: {type: string, description: 'For example `service.restart`.'}4831        title: {type: string}4832        description: {type: string}4833        criticality: {$ref: '#/components/schemas/Criticality'}4834        permission: {type: string, description: Permission required to request the action.}4835        extra_permissions: {type: array, items: {type: string}, description: 'Additional permissions, for example `logs.read` for `service.logs.tail`.'}4836        target_kinds: {type: array, items: {$ref: '#/components/schemas/ActionTargetKind'}}4837        params_schema: {type: object, additionalProperties: true, description: JSON Schema (draft 2020-12) of `params`.}4838        requires_step_up: {type: boolean}4839        requires_justification: {type: boolean}4840        requires_confirmation: {type: boolean, description: The request must carry `confirm` = alias of the target node (or name of the target service).}4841        requires_approval: {type: boolean, description: A second person holding `actions.approve` must approve.}4842        timeout_s: {type: integer}4843        lock_scope: {type: string, enum: [node, service, job, none]}4844        available: {type: boolean, description: False for types not enabled in this version.}4845        unavailable_reason: {type: string}4846    ActionTypeList:4847      type: object4848      required: [items]4849      properties:4850        items: {type: array, items: {$ref: '#/components/schemas/ActionType'}}4851    ActionTarget:4852      type: object4853      required: [kind, id]4854      properties:4855        kind: {$ref: '#/components/schemas/ActionTargetKind'}4856        id: {type: string, format: uuid}4857    CreateActionRequest:4858      type: object4859      required: [type, target]4860      properties:4861        type: {type: string}4862        target: {$ref: '#/components/schemas/ActionTarget'}4863        params: {type: object, additionalProperties: true, description: Validated against `params_schema` of the type. Defaults to an empty object.}4864        confirm: {type: string, maxLength: 128, description: Confirmation text typed by the user; must equal the alias of the target. Checked by the server.}4865        justification: {type: string, maxLength: 2000}4866        override_maintenance: {type: boolean, default: false, description: 'Explicitly run the action although the node is in maintenance mode (otherwise `422 node_in_maintenance`). Recorded in the audit log.'}4867    Action:4868      type: object4869      required: [id, type, criticality, target, params, state, requested_via, justification, approval_required, outcome_unknown, created_at, timeout_s, correlation_id]4870      properties:4871        id: {type: string, format: uuid}4872        type: {type: string}4873        criticality: {$ref: '#/components/schemas/Criticality'}4874        target: {$ref: '#/components/schemas/ActionTarget'}4875        target_label: {type: string, description: Alias or name of the target at request time.}4876        node_id: {type: string, format: uuid}4877        node_alias: {type: string}4878        params: {type: object, additionalProperties: true}4879        state: {$ref: '#/components/schemas/ActionState'}4880        requested_by: {type: string, format: uuid, description: Absent for actions created by the system (scheduler).}4881        requested_by_display_name: {type: string}4882        requested_via: {type: string, description: '`api`, `scheduler` or `cli`.'}4883        justification: {type: string}4884        approval_required: {type: boolean}4885        approved_by: {type: string, format: uuid}4886        approved_by_display_name: {type: string}4887        approved_at: {type: string, format: date-time}4888        rejection_reason: {type: string}4889        outcome_unknown: {type: boolean, description: 'True when the command was delivered but no result came back before the deadline: the effect on the node is unknown and the command is never re-sent.'}4890        created_at: {type: string, format: date-time}4891        queued_at: {type: string, format: date-time}4892        started_at: {type: string, format: date-time}4893        finished_at: {type: string, format: date-time}4894        deadline_at: {type: string, format: date-time}4895        cancel_requested_at: {type: string, format: date-time}4896        timeout_s: {type: integer}4897        result: {type: object, additionalProperties: true}4898        error_code: {type: string}4899        error_message: {type: string}4900        job_id: {type: string, format: uuid}4901        correlation_id: {type: string, format: uuid}4902    ActionList:4903      type: object4904      required: [items]4905      properties:4906        items: {type: array, items: {$ref: '#/components/schemas/Action'}}4907        next_cursor: {type: string}4908    ActionEvent:4909      type: object4910      required: [id, ts, kind, data]4911      properties:4912        id: {type: integer, format: int64}4913        ts: {type: string, format: date-time}4914        kind: {type: string, description: '`state` (data = new state), `approval`, `precheck`, `output` (data = redacted text chunk) or `note` (open list).'}4915        stream: {type: string, enum: [stdout, stderr], description: Output events only.}4916        data: {type: string}4917    ActionDetail:4918      type: object4919      required: [action, events]4920      properties:4921        action: {$ref: '#/components/schemas/Action'}4922        events: {type: array, items: {$ref: '#/components/schemas/ActionEvent'}}4923    ActionOutput:4924      type: object4925      required: [items, next_after, complete]4926      properties:4927        items: {type: array, items: {$ref: '#/components/schemas/ActionEvent'}}4928        next_after: {type: integer, format: int64, description: Value to pass as `after` to get what follows.}4929        complete: {type: boolean, description: True when the action is finished and every chunk has been returned.}4930        truncated: {type: boolean, description: True when the agent stopped capturing output at its line or byte cap.}4931    ApproveActionRequest:4932      type: object4933      properties:4934        comment: {type: string, maxLength: 2000}4935    RejectActionRequest:4936      type: object4937      required: [reason]4938      properties:4939        reason: {type: string, minLength: 1, maxLength: 2000}49404941    # ───────────── Audit ─────────────4942    AuditEntry:4943      type: object4944      required: [seq, ts, actor_kind, actor_label, action, params, outcome, detail, correlation_id, prev_hash, hash]4945      properties:4946        seq: {type: integer, format: int64}4947        ts: {type: string, format: date-time}4948        actor_kind: {type: string, enum: [user, agent, system, cli]}4949        actor_id: {type: string, format: uuid}4950        actor_label: {type: string}4951        device_id: {type: string, format: uuid}4952        session_id: {type: string, format: uuid}4953        ip: {type: string}4954        action: {type: string, description: 'For example `auth.login`, `action.create` or `invitation.create`.'}4955        target_kind: {type: string}4956        target_id: {type: string}4957        params: {type: object, additionalProperties: true, description: Allowlisted non-sensitive parameters only.}4958        outcome: {$ref: '#/components/schemas/AuditOutcome'}4959        detail: {type: string}4960        correlation_id: {type: string, format: uuid}4961        prev_hash: {type: string, description: Hex SHA-256 of the previous entry.}4962        hash: {type: string, description: Hex SHA-256 of this entry chained on `prev_hash`.}4963    AuditList:4964      type: object4965      required: [items]4966      properties:4967        items: {type: array, items: {$ref: '#/components/schemas/AuditEntry'}}4968        next_cursor: {type: string}4969    AuditVerification:4970      type: object4971      required: [ok, checked_entries, verified_at]4972      properties:4973        ok: {type: boolean}4974        checked_entries: {type: integer, format: int64}4975        first_seq: {type: integer, format: int64}4976        last_seq: {type: integer, format: int64}4977        head_hash: {type: string, description: Hex hash of the last entry.}4978        first_broken_seq: {type: integer, format: int64, description: Present when `ok` is false.}4979        reason: {type: string, description: Present when `ok` is false.}4980        verified_at: {type: string, format: date-time}4981        export_key_id: {type: string, description: Identifier of the key that signs audit exports.}4982        export_public_key: {type: string, description: 'Base64 Ed25519 public key that signs audit exports (`mccctl audit-verify-export --pubkey`).'}49834984    # ───────────── Events (SSE payloads) ─────────────4985    EventTopic:4986      type: string4987      enum: [node.state, node.updated, alert.changed, incident.changed, action.changed, action.output, service.changed, job.changed, maintenance.changed, audit.appended, resync]4988    NodeStateEvent:4989      type: object4990      description: 'Topic `node.state`: freshness, maintenance or headline values of a node changed. Emitted at most once per report per node.'4991      required: [node_id, alias, freshness, maintenance]4992      properties:4993        node_id: {type: string, format: uuid}4994        alias: {type: string}4995        freshness: {$ref: '#/components/schemas/Freshness'}4996        observed_at: {type: string, format: date-time}4997        maintenance: {type: boolean}4998        headline: {$ref: '#/components/schemas/NodeHeadline'}4999    NodeUpdatedEvent:5000      type: object5001      description: 'Topic `node.updated`: the node resource changed; reload it.'5002      required: [node_id, change]5003      properties:5004        node_id: {type: string, format: uuid}5005        change: {type: string, enum: [created, updated, inventory, agent, retired]}5006    AlertChangedEvent:5007      type: object5008      description: 'Topic `alert.changed`.'5009      required: [alert_id, rule_id, state, severity, summary]5010      properties:5011        alert_id: {type: string, format: uuid}5012        rule_id: {type: string, format: uuid}5013        node_id: {type: string, format: uuid}5014        state: {$ref: '#/components/schemas/AlertState'}5015        severity: {$ref: '#/components/schemas/Severity'}5016        summary: {type: string}5017        suppressed: {type: boolean}5018        incident_id: {type: string, format: uuid}5019    IncidentChangedEvent:5020      type: object5021      description: 'Topic `incident.changed`.'5022      required: [incident_id, state, severity, title]5023      properties:5024        incident_id: {type: string, format: uuid}5025        state: {$ref: '#/components/schemas/IncidentState'}5026        severity: {$ref: '#/components/schemas/Severity'}5027        title: {type: string}5028    ActionChangedEvent:5029      type: object5030      description: 'Topic `action.changed`: an action was created or changed state.'5031      required: [action_id, type, state, target, outcome_unknown]5032      properties:5033        action_id: {type: string, format: uuid}5034        type: {type: string}5035        state: {$ref: '#/components/schemas/ActionState'}5036        target: {$ref: '#/components/schemas/ActionTarget'}5037        node_id: {type: string, format: uuid}5038        requested_by: {type: string, format: uuid}5039        outcome_unknown: {type: boolean}5040    ActionOutputEvent:5041      type: object5042      description: 'Topic `action.output`: one redacted output chunk; `event_id` continues the `after` cursor of the output operation.'5043      required: [action_id, event_id, ts, data]5044      properties:5045        action_id: {type: string, format: uuid}5046        event_id: {type: integer, format: int64}5047        ts: {type: string, format: date-time}5048        stream: {type: string, enum: [stdout, stderr]}5049        data: {type: string}5050    ServiceChangedEvent:5051      type: object5052      description: 'Topic `service.changed`: state, restart count, managed flag or presence of a service changed.'5053      required: [service_id, node_id, manager, name, state]5054      properties:5055        service_id: {type: string, format: uuid}5056        node_id: {type: string, format: uuid}5057        manager: {$ref: '#/components/schemas/ServiceManager'}5058        name: {type: string}5059        state: {$ref: '#/components/schemas/ServiceState'}5060        previous_state: {$ref: '#/components/schemas/ServiceState'}5061        gone: {type: boolean}5062    JobChangedEvent:5063      type: object5064      description: 'Topic `job.changed`.'5065      required: [job_id, template, state]5066      properties:5067        job_id: {type: string, format: uuid}5068        template: {type: string}5069        state: {$ref: '#/components/schemas/JobState'}5070        node_id: {type: string, format: uuid}5071        progress: {type: number}5072    MaintenanceChangedEvent:5073      type: object5074      description: 'Topic `maintenance.changed`: a window, an occurrence or a note changed.'5075      required: [change]5076      properties:5077        change: {type: string, enum: [window_created, window_updated, window_cancelled, window_completed, occurrence_started, occurrence_ended, note_created, note_updated, note_deleted]}5078        window_id: {type: string, format: uuid}5079        note_id: {type: string, format: uuid}5080        occurrence: {type: string, format: date-time}5081        node_ids: {type: array, items: {type: string, format: uuid}}5082    AuditAppendedEvent:5083      type: object5084      description: 'Topic `audit.appended` (only with `audit.read`).'5085      required: [seq, ts, action, actor_label, outcome]5086      properties:5087        seq: {type: integer, format: int64}5088        ts: {type: string, format: date-time}5089        action: {type: string}5090        actor_label: {type: string}5091        outcome: {$ref: '#/components/schemas/AuditOutcome'}5092        target_kind: {type: string}5093        target_id: {type: string}5094    ResyncEvent:5095      type: object5096      description: 'Event `resync`: the requested sequence is no longer retained; reload state through the REST API.'5097      required: [reason]5098      properties:5099        reason: {type: string, enum: [retention_exceeded, server_restart]}5100        oldest_available_seq: {type: integer, format: int64}5101    EventPayloads:5102      type: object5103      description: |5104        Typing aid listing the payload schema of every topic. On the wire `data` is **directly** the payload object5105        of the topic of the frame (not wrapped in this object). In a decoded frame exactly one property is set: the5106        one matching `event`.5107      properties:5108        node_state: {$ref: '#/components/schemas/NodeStateEvent'}5109        node_updated: {$ref: '#/components/schemas/NodeUpdatedEvent'}5110        alert_changed: {$ref: '#/components/schemas/AlertChangedEvent'}5111        incident_changed: {$ref: '#/components/schemas/IncidentChangedEvent'}5112        action_changed: {$ref: '#/components/schemas/ActionChangedEvent'}5113        action_output: {$ref: '#/components/schemas/ActionOutputEvent'}5114        service_changed: {$ref: '#/components/schemas/ServiceChangedEvent'}5115        job_changed: {$ref: '#/components/schemas/JobChangedEvent'}5116        maintenance_changed: {$ref: '#/components/schemas/MaintenanceChangedEvent'}5117        audit_appended: {$ref: '#/components/schemas/AuditAppendedEvent'}5118        resync: {$ref: '#/components/schemas/ResyncEvent'}5119    EventStreamFrame:5120      type: object5121      description: One decoded SSE frame (see the description of the events operation). Not a JSON body.5122      required: [id, event, data]5123      properties:5124        id: {type: string, description: Monotonic sequence; send back as `Last-Event-ID` to resume.}5125        event: {$ref: '#/components/schemas/EventTopic'}5126        data: {$ref: '#/components/schemas/EventPayloads'}51275128    # ───────────── Dashboards, activity, search, meta ─────────────5129    DashboardWidget:5130      type: object5131      required: [id, type, x, y, w, h, config]5132      properties:5133        id: {type: string, minLength: 1, maxLength: 40}5134        type: {type: string, maxLength: 60, description: 'Widget type known to the clients, for example `metric.chart`. Unknown types are kept and rendered as a placeholder.'}5135        x: {type: integer, minimum: 0}5136        y: {type: integer, minimum: 0}5137        w: {type: integer, minimum: 1, maximum: 12}5138        h: {type: integer, minimum: 1, maximum: 12}5139        config: {type: object, additionalProperties: true}5140    Dashboard:5141      type: object5142      required: [name, layout, updated_at]5143      properties:5144        name: {type: string}5145        layout: {type: array, items: {$ref: '#/components/schemas/DashboardWidget'}}5146        updated_at: {type: string, format: date-time}5147    DashboardList:5148      type: object5149      required: [items]5150      properties:5151        items: {type: array, items: {$ref: '#/components/schemas/Dashboard'}}5152    PutDashboardRequest:5153      type: object5154      required: [layout]5155      properties:5156        layout: {type: array, maxItems: 60, items: {$ref: '#/components/schemas/DashboardWidget'}}5157    ActivityKind:5158      type: string5159      enum: [action, alert_ack, alert_resolve, incident, maintenance, maintenance_note, login]5160    ActivityItem:5161      type: object5162      required: [id, ts, kind, summary]5163      properties:5164        id: {type: string, description: Opaque id of the item.}5165        ts: {type: string, format: date-time}5166        kind: {$ref: '#/components/schemas/ActivityKind'}5167        actor_display_name: {type: string}5168        summary: {type: string}5169        target_kind: {type: string}5170        target_id: {type: string}5171        target_label: {type: string}5172        outcome: {$ref: '#/components/schemas/AuditOutcome'}5173    ActivityList:5174      type: object5175      required: [items]5176      properties:5177        items: {type: array, items: {$ref: '#/components/schemas/ActivityItem'}}5178        next_cursor: {type: string}5179    SearchResultKind:5180      type: string5181      enum: [node, service, alert, action, incident, job, inference_server, maintenance_window, maintenance_note]5182    SearchResult:5183      type: object5184      required: [kind, id, title, score]5185      properties:5186        kind: {$ref: '#/components/schemas/SearchResultKind'}5187        id: {type: string, format: uuid}5188        title: {type: string}5189        subtitle: {type: string}5190        node_id: {type: string, format: uuid, description: Node the result belongs to when relevant.}5191        state: {type: string, description: 'State of the resource in its own vocabulary (alert state or service state for example).'}5192        freshness: {$ref: '#/components/schemas/Freshness'}5193        score: {type: number}5194    SearchResults:5195      type: object5196      required: [query, items]5197      properties:5198        query: {type: string}5199        items: {type: array, items: {$ref: '#/components/schemas/SearchResult'}}5200    HealthStatus:5201      type: object5202      required: [status]5203      properties:5204        status: {type: string, enum: [ok]}5205    VersionInfo:5206      type: object5207      required: [version, api_version]5208      properties:5209        version: {type: string, description: Server version (semver).}5210        api_version: {type: string, description: Always `v1` for this contract.}5211        commit: {type: string}5212        built_at: {type: string, format: date-time}5213        min_app_version: {type: string, description: Oldest native app version the server accepts.}5214
Files main
Menu

Theme