Repository Public
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