{ "openapi": "3.1.0", "servers": [ { "url": "https://{host}{basePath}", "description": "Your own Hub. HTTPS only: the credentials below are bearer secrets.", "variables": { "host": { "default": "egressview.example", "description": "The host you run the Hub on" }, "basePath": { "default": "", "description": "Set when the Hub is served under a subpath" } } } ], "security": [ { "sessionCookie": [] }, { "apiToken": [] } ], "info": { "title": "EgressView Hub HTTP API", "version": "1.10.0", "description": "Generated from src/permission-matrix.js, the same object the server enforces, so this cannot describe a route the server does not have or miss one it does.\n\nRequest bodies are described for the routes the test suite exercises, captured from the schema the server actually validated rather than written by hand -- a hand-written list would go stale the first time a route changed. Operations without one say so in their description.\n\nResponses come in two kinds and the difference matters. A schema marked `x-observed` describes what a route was **seen to return under test** -- documentation of behaviour, not a promise, and only as complete as the paths the tests happened to walk. A schema without that marking is **declared by the server** and is what the route promises, and CI refuses to ship a build that breaks it. A schema marked `x-enforced` is refused by the running Hub as well: those are responses that project a credential down to a fact about it, where an extra field would be a leak rather than a mismatch. `x-array-elements-observed` marks a declaration that covers the envelope but not every element of an array.\n\nRegenerate with `npm run docs:openapi`, which re-captures first.", "license": { "name": "AGPL-3.0-only" } }, "components": { "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "egressview_session", "description": "Browser session. HttpOnly, and state-changing requests additionally require the CSRF token issued with it." }, "apiToken": { "type": "http", "scheme": "bearer", "description": "An API identity token. Stored only as a hash, so a copy of the database does not yield a usable credential." }, "agentToken": { "type": "http", "scheme": "bearer", "description": "An enrolled agent, prefixed egva_. A separate access class: an agent token cannot reach a route in any other class, and a session cannot reach an agent route." } }, "x-permissions": [ "agent.ingest", "ai.run", "audit.read", "auth.admin", "backup.restore", "network.read", "notes.write", "settings.write" ], "x-mcpTools": { "get_alerts": "network.read", "get_device_notes": "network.read", "get_device_traffic": "network.read", "get_devices": "network.read", "get_new_nodes": "network.read", "get_threat_connections": "network.read", "get_threat_summary": "network.read", "get_top_destinations": "network.read", "get_traffic_summary": "network.read", "query_connections": "network.read", "set_device_note": "notes.write" } }, "paths": { "/api/admin/regenerate-token": { "post": { "summary": "POST /api/admin/regenerate-token", "description": "Requires `auth.admin`.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "currentPassword": { "type": "string", "maxLength": 256 } }, "required": [ "currentPassword" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "token": { "type": "string" } }, "required": [ "success", "token" ], "x-observed": true } } } }, "401": { "description": "No usable credential. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/admin/verify": { "post": { "summary": "POST /api/admin/verify", "description": "No authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string", "maxLength": 4096 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "ok" ], "x-observed": true } } } }, "401": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "ok" ], "x-observed": true } } } }, "503": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "ok" ], "x-observed": true } } } } } } }, "/api/agent/capabilities": { "get": { "summary": "GET /api/agent/capabilities", "description": "Requires an enrolled agent token. The request body is not described here.", "security": [ { "agentToken": [] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersions": { "maxItems": 500, "type": "array", "items": { "type": "number" } }, "maxObservationsPerBatch": { "type": "number" }, "maxBodyBytes": { "type": "number" }, "requestsPerMinute": { "type": "number" }, "compression": { "maxItems": 500, "type": "array", "items": { "type": "string" } } }, "required": [ "schemaVersions", "maxObservationsPerBatch", "maxBodyBytes", "requestsPerMinute", "compression" ], "additionalProperties": {} } } } }, "401": { "description": "No usable credential. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agent/enrollment-requests": { "post": { "summary": "POST /api/agent/enrollment-requests", "description": "No authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^[0-9A-Za-z]{6}$" }, "agent": { "type": "object", "properties": { "hostName": { "type": "string", "minLength": 1, "maxLength": 255 }, "platform": { "type": "string", "enum": [ "macos", "windows", "linux" ] }, "osVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "agentVersion": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "hostName", "platform", "osVersion", "agentVersion" ], "additionalProperties": false } }, "required": [ "code", "agent" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "202": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "claimSecret": { "type": "string" }, "expiresAt": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "claimSecret", "expiresAt", "requestId", "status" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "429": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/agent/enrollment-requests/claim": { "post": { "summary": "POST /api/agent/enrollment-requests/claim", "description": "No authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "claimSecret": { "type": "string", "pattern": "^egvc_[0-9a-f]{64}$" } }, "required": [ "requestId", "claimSecret" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "x-observed": true } } } }, "201": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "token": { "type": "string" }, "agentId": { "type": "string" } }, "required": [ "agentId", "status", "token" ], "x-observed": true } } } } } } }, "/api/agent/geo-cache": { "get": { "summary": "GET /api/agent/geo-cache", "description": "Requires an enrolled agent token. The request body is not described here.", "security": [ { "agentToken": [] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string" }, "entries": { "type": "array", "items": { "type": "array", "items": { "type": [ "number", "string" ] } } } }, "required": [ "entries", "generatedAt", "schemaVersion" ], "x-observed": true } } } }, "401": { "description": "No usable credential. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agent/ingest": { "post": { "summary": "POST /api/agent/ingest", "description": "Requires an enrolled agent token.", "security": [ { "agentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sentAt": { "type": "string", "maxLength": 32, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "agent": { "type": "object", "properties": { "hostName": { "type": "string", "minLength": 1, "maxLength": 255 }, "platform": { "type": "string", "enum": [ "macos", "windows", "linux" ] }, "osVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "agentVersion": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "hostName", "platform", "osVersion", "agentVersion" ], "additionalProperties": false }, "observations": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "observationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkProtocol": { "type": "string", "enum": [ "tcp", "udp" ] }, "localAddress": { "type": "string", "maxLength": 45 }, "localPort": { "type": "integer", "minimum": 0, "maximum": 65535 }, "remoteAddress": { "type": "string", "maxLength": 45 }, "remotePort": { "type": "integer", "minimum": 1, "maximum": 65535 }, "processID": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "processName": { "type": "string", "minLength": 1, "maxLength": 256 }, "bundleID": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "firstObservedAt": { "type": "string", "maxLength": 32, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "lastObservedAt": { "type": "string", "maxLength": 32, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "bytesIn": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9]\\d{0,19})$" }, { "type": "null" } ] }, "bytesOut": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9]\\d{0,19})$" }, { "type": "null" } ] }, "collector": { "type": "string", "enum": [ "network-extension", "libproc", "etw" ] }, "confidence": { "type": "string", "enum": [ "exact", "sampled" ] }, "remoteHostname": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 253 }, { "type": "null" } ] } }, "required": [ "observationId", "networkProtocol", "localAddress", "localPort", "remoteAddress", "remotePort", "processID", "processName", "bundleID", "firstObservedAt", "lastObservedAt", "bytesIn", "bytesOut", "collector", "confidence" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "batchId", "sentAt", "agent", "observations" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "string" }, "accepted": { "type": "number" }, "duplicate": { "type": "number" }, "rejected": { "type": "number" }, "receivedAt": { "type": "number" }, "replayed": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "batchId", "accepted", "duplicate", "rejected", "receivedAt", "replayed" ], "additionalProperties": {} } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "requested": { "type": "integer" }, "supported": { "type": "array", "items": { "type": "integer" } }, "hint": { "type": "string" }, "requestId": {} }, "required": [ "error", "hint", "requestId", "requested", "supported" ], "x-observed": true } } } }, "401": { "description": "No usable credential. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "403": { "description": "Authenticated, but not permitted." }, "422": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "index", "reason" ] } }, "requestId": {} }, "required": [ "error", "rejected", "requestId" ], "x-observed": true } } } }, "429": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/agent/registration/revoke": { "post": { "summary": "POST /api/agent/registration/revoke", "description": "Requires an enrolled agent token. The request body is not described here.", "security": [ { "agentToken": [] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agent/threat-intel": { "get": { "summary": "GET /api/agent/threat-intel", "description": "Requires an enrolled agent token. The request body is not described here.", "security": [ { "agentToken": [] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI. The envelope is declared; the array elements are observed, not checked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "generatedAt": { "type": "string" }, "available": { "type": "boolean" }, "fetchedAt": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": {} }, "domains": { "type": "array", "items": {} }, "cidrs": { "type": "array", "items": {} } }, "required": [ "schemaVersion", "generatedAt", "available", "ips", "domains", "cidrs" ], "additionalProperties": {} } } }, "x-array-elements-observed": true }, "401": { "description": "No usable credential. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agent/token/rotate": { "post": { "summary": "POST /api/agent/token/rotate", "description": "Requires an enrolled agent token. The request body is not described here.", "security": [ { "agentToken": [] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agents": { "get": { "summary": "GET /api/agents", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "platform": { "type": "string" }, "hostName": { "type": "string" }, "osVersion": { "type": "string" }, "agentVersion": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "lastSeenAt": { "type": [ "number", "null" ] }, "revokedAt": { "type": [ "number", "null" ] } }, "required": [ "agentId", "platform", "hostName", "osVersion", "agentVersion", "createdAt", "updatedAt", "lastSeenAt", "revokedAt" ], "additionalProperties": false } } }, "required": [ "agents" ], "additionalProperties": {} } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agents/:agentId/revoke": { "post": { "summary": "POST /api/agents/:agentId/revoke", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agents/enrollment-requests": { "get": { "summary": "GET /api/agents/enrollment-requests", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "requestId": { "type": "string" }, "platform": { "type": "string" }, "hostName": { "type": "string" }, "osVersion": { "type": "string" }, "agentVersion": { "type": "string" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "duplicateHostName": { "type": "boolean" } }, "required": [ "agentVersion", "createdAt", "duplicateHostName", "expiresAt", "hostName", "osVersion", "platform", "requestId" ] } } }, "required": [ "requests" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agents/enrollment-requests/:requestId/approve": { "post": { "summary": "POST /api/agents/enrollment-requests/:requestId/approve", "description": "Requires `auth.admin`.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "replaceExisting": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "agentId": { "type": "string" }, "platform": { "type": "string" }, "hostName": { "type": "string" }, "osVersion": { "type": "string" }, "agentVersion": { "type": "string" }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" }, "lastSeenAt": { "type": "null" }, "revokedAt": { "type": "null" } }, "required": [ "agentId", "agentVersion", "createdAt", "hostName", "lastSeenAt", "osVersion", "platform", "revokedAt", "updatedAt" ] } }, "required": [ "agent" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agents/enrollment-requests/:requestId/reject": { "post": { "summary": "POST /api/agents/enrollment-requests/:requestId/reject", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rejected": { "type": "boolean" } }, "required": [ "rejected" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agents/enrollment-tokens": { "post": { "summary": "POST /api/agents/enrollment-tokens", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled." }, "201": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "expiresAt": { "type": "integer" } }, "required": [ "code", "expiresAt" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agents/ingest-metrics": { "get": { "summary": "GET /api/agents/ingest-metrics", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "integer" }, "accepted": { "type": "integer" }, "duplicate": { "type": "integer" }, "rejected": { "type": "integer" }, "failures": { "type": "integer" }, "rateLimited": { "type": "integer" }, "maxInFlight": { "type": "integer" }, "lastDurationMs": { "type": "integer" }, "inFlight": { "type": "integer" }, "eventLoopDelayMs": { "type": "object", "properties": { "p50": { "type": "integer" }, "p95": { "type": "integer" }, "max": { "type": "integer" } }, "required": [ "max", "p50", "p95" ] }, "limits": { "type": "object", "properties": { "requestsPerMinutePerAgent": { "type": "integer" }, "maxConcurrent": { "type": "integer" } }, "required": [ "maxConcurrent", "requestsPerMinutePerAgent" ] } }, "required": [ "accepted", "duplicate", "eventLoopDelayMs", "failures", "inFlight", "lastDurationMs", "limits", "maxInFlight", "rateLimited", "rejected", "requests" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/agents/transport": { "get": { "summary": "GET /api/agents/transport", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/agents/transport", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/analyze": { "post": { "summary": "POST /api/ai/analyze", "description": "Requires `ai.run`.", "security": [ { "sessionCookie": [ "ai.run" ] }, { "apiToken": [ "ai.run" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "to": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sourceKind": { "type": "string", "enum": [ "router", "agent" ] }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "cloudConsentConfirmed": { "type": "boolean" }, "language": { "type": "string", "enum": [ "ja", "en" ] } }, "required": [ "from" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "range": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" } }, "required": [ "from", "to" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "text": { "type": "string" }, "generatedAt": { "type": "integer" }, "usage": { "type": [ "null", "object" ] }, "pricing": { "type": [ "null", "object" ] }, "estimatedCostUsd": { "type": [ "integer", "null" ] } }, "required": [ "estimatedCostUsd", "generatedAt", "model", "pricing", "provider", "range", "success", "text", "usage" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "success" ], "x-observed": true } } } }, "429": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "code", "error", "success" ], "x-observed": true } } } } } } }, "/api/ai/chat": { "post": { "summary": "POST /api/ai/chat", "description": "Requires `ai.run`.", "security": [ { "sessionCookie": [ "ai.run" ] }, { "apiToken": [ "ai.run" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "to": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sourceKind": { "type": "string", "enum": [ "router", "agent" ] }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "cloudConsentConfirmed": { "type": "boolean" }, "language": { "type": "string", "enum": [ "ja", "en" ] }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "message": { "type": "string", "minLength": 1, "maxLength": 4000 }, "priorAnalysis": { "type": "string", "maxLength": 8000 } }, "required": [ "from", "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "conversationId": { "type": "string" }, "requestId": { "type": "string" }, "startedNewConversation": { "type": "boolean" }, "message": { "type": "object", "properties": { "messageId": { "type": "string" }, "conversationId": { "type": "string" }, "requestId": { "type": "string" }, "role": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "integer" }, "provider": { "type": "string" }, "model": { "type": "string" }, "rangeFrom": { "type": "integer" }, "rangeTo": { "type": "integer" }, "status": { "type": "string" }, "errorCode": { "type": "null" }, "sourceKind": { "type": [ "null", "string" ] }, "sourceId": { "type": [ "null", "string" ] }, "usageInputTokens": { "type": "integer" }, "usageOutputTokens": { "type": "integer" }, "usageTotalTokens": { "type": "integer" }, "estimatedCostUsd": { "type": "null" }, "pricingVersion": { "type": "null" } }, "required": [ "body", "conversationId", "createdAt", "errorCode", "messageId", "model", "provider", "rangeFrom", "rangeTo", "requestId", "role", "sourceId", "sourceKind", "status" ] }, "usage": { "type": "null" }, "estimatedCostUsd": { "type": "null" } }, "required": [ "conversationId", "message", "requestId", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/conversations": { "get": { "summary": "GET /api/ai/conversations", "description": "Requires `ai.run`. The request body is not described here.", "security": [ { "sessionCookie": [ "ai.run" ] }, { "apiToken": [ "ai.run" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI. The envelope is declared; the array elements are observed, not checked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": {} }, "storage": {} }, "required": [ "conversations", "storage" ], "additionalProperties": {} } } }, "x-array-elements-observed": true }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/conversations/:id": { "delete": { "summary": "DELETE /api/ai/conversations/:id", "description": "Requires `ai.run`. The request body is not described here.", "security": [ { "sessionCookie": [ "ai.run" ] }, { "apiToken": [ "ai.run" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "get": { "summary": "GET /api/ai/conversations/:id", "description": "Requires `ai.run`. The request body is not described here.", "security": [ { "sessionCookie": [ "ai.run" ] }, { "apiToken": [ "ai.run" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI. The envelope is declared; the array elements are observed, not checked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "conversationId": { "type": "string" } }, "required": [ "conversationId" ], "additionalProperties": {} }, "messages": { "type": "array", "items": {} } }, "required": [ "conversation", "messages" ], "additionalProperties": {} } } }, "x-array-elements-observed": true }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "404": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/ai/facts": { "get": { "summary": "GET /api/ai/facts", "description": "Requires `ai.run`. The request body is not described here.", "security": [ { "sessionCookie": [ "ai.run" ] }, { "apiToken": [ "ai.run" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI. The envelope is declared; the array elements are observed, not checked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "serverTime": { "type": "number" }, "range": { "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" }, "durationMs": { "type": "number" } }, "required": [ "from", "to", "durationMs" ], "additionalProperties": {} }, "previousRange": { "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" }, "durationMs": { "type": "number" } }, "required": [ "from", "to", "durationMs" ], "additionalProperties": {} }, "collection": { "type": "object", "properties": { "health": { "type": "string" }, "enabledCount": { "type": "number" }, "readyCount": { "type": "number" }, "reportedSessions": { "type": "number" }, "lastUpdatedAt": { "type": [ "number", "null" ] }, "routers": { "type": "array", "items": {} } }, "required": [ "health", "enabledCount", "readyCount", "reportedSessions", "lastUpdatedAt", "routers" ], "additionalProperties": {} }, "sourceScope": { "anyOf": [ {}, { "type": "null" } ] }, "current": { "type": "object", "properties": { "connections": { "type": "number" }, "devices": { "type": "number" }, "destinations": { "type": "number" }, "safe": { "type": "number" }, "warn": { "type": "number" }, "danger": { "type": "number" } }, "required": [ "connections", "devices", "destinations", "safe", "warn", "danger" ], "additionalProperties": {} }, "previous": { "type": "object", "properties": { "connections": { "type": "number" }, "devices": { "type": "number" }, "destinations": { "type": "number" }, "safe": { "type": "number" }, "warn": { "type": "number" }, "danger": { "type": "number" } }, "required": [ "connections", "devices", "destinations", "safe", "warn", "danger" ], "additionalProperties": {} } }, "required": [ "serverTime", "range", "previousRange", "collection", "sourceScope", "current", "previous" ], "additionalProperties": {} } } }, "x-array-elements-observed": true }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/guardrails": { "post": { "summary": "POST /api/ai/guardrails", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "region": { "type": "string", "maxLength": 64 } }, "required": [ "region" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "provider": { "type": "string" }, "guardrails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "arn": { "type": "string" }, "name": { "type": "string" }, "versions": { "type": "array", "items": { "type": "string" } } }, "required": [ "arn", "id", "name", "versions" ] } } }, "required": [ "guardrails", "provider", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/models": { "post": { "summary": "POST /api/ai/models", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "region": { "type": "string", "maxLength": 64 } }, "required": [ "region" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "provider": { "type": "string" }, "models": { "type": "array", "items": { "type": "string" } }, "modelPricing": { "type": "object", "properties": { "catalogVersion": { "type": "string" }, "priced": { "type": "integer" }, "unpriced": { "type": "integer" }, "models": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "priced": { "type": "boolean" }, "pricing": { "type": "null" } }, "required": [ "model", "priced", "pricing", "provider" ] } } }, "required": [ "catalogVersion", "models", "priced", "unpriced" ] } }, "required": [ "modelPricing", "models", "provider", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/notification-config": { "get": { "summary": "GET /api/ai/notification-config", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "frequency": { "type": "string" }, "destinations": { "type": "object", "properties": {}, "additionalProperties": {} }, "rules": { "type": "object", "properties": {}, "additionalProperties": {} }, "threat": { "type": "object", "properties": {}, "additionalProperties": {} }, "automationConsent": { "type": "boolean" }, "automationProvider": { "not": {} } }, "required": [ "frequency", "destinations", "rules", "threat", "automationConsent" ], "additionalProperties": {} }, "status": { "type": "object", "properties": { "running": { "type": "boolean" }, "provider": { "type": "string" }, "automationReady": { "type": "boolean" }, "slackReady": { "type": "boolean" } }, "required": [ "running", "provider", "automationReady", "slackReady" ], "additionalProperties": false } }, "required": [ "config", "status" ], "additionalProperties": {} } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/ai/notification-config", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "weekday": { "type": "integer", "minimum": 0, "maximum": 6 }, "time": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100 }, "rangeHours": { "type": "integer", "minimum": 1, "maximum": 336 }, "destinations": { "type": "object", "properties": { "ui": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "ui", "slack" ], "additionalProperties": false }, "rules": { "type": "object", "properties": { "scheduled": { "type": "boolean" }, "danger": { "type": "boolean" }, "newDestination": { "type": "boolean" }, "increase": { "type": "boolean" } }, "required": [ "scheduled", "danger", "newDestination", "increase" ], "additionalProperties": false }, "threat": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "dangerThreshold": { "type": "integer", "minimum": 1, "maximum": 1000 }, "newDestinationsThreshold": { "type": "integer", "minimum": 1, "maximum": 1000 }, "increaseThreshold": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "enabled", "dangerThreshold", "newDestinationsThreshold", "increaseThreshold" ], "additionalProperties": false }, "dailyLimit": { "type": "integer", "minimum": 1, "maximum": 6 }, "cooldownMinutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "automationConsent": { "type": "boolean" } }, "required": [ "frequency", "weekday", "time", "timezone", "rangeHours", "destinations", "threat", "dailyLimit", "cooldownMinutes", "automationConsent" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "config": { "type": "object", "properties": { "frequency": { "type": "string" }, "weekday": { "type": "integer" }, "time": { "type": "string" }, "timezone": { "type": "string" }, "rangeHours": { "type": "integer" }, "destinations": { "type": "object", "properties": { "ui": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "slack", "ui" ] }, "rules": { "type": "object", "properties": { "scheduled": { "type": "boolean" }, "danger": { "type": "boolean" }, "newDestination": { "type": "boolean" }, "increase": { "type": "boolean" } }, "required": [ "danger", "increase", "newDestination", "scheduled" ] }, "threat": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "dangerThreshold": { "type": "integer" }, "newDestinationsThreshold": { "type": "integer" }, "increaseThreshold": { "type": "integer" } }, "required": [ "dangerThreshold", "enabled", "increaseThreshold", "newDestinationsThreshold" ] }, "dailyLimit": { "type": "integer" }, "cooldownMinutes": { "type": "integer" }, "automationConsent": { "type": "boolean" } }, "required": [ "automationConsent", "cooldownMinutes", "dailyLimit", "destinations", "frequency", "rangeHours", "rules", "threat", "time", "timezone", "weekday" ] }, "status": { "type": "object", "properties": { "running": { "type": "boolean" }, "provider": { "type": "string" }, "automationReady": { "type": "boolean" }, "slackReady": { "type": "boolean" } }, "required": [ "automationReady", "provider", "running", "slackReady" ] } }, "required": [ "config", "status", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/ai/notification-events": { "get": { "summary": "GET /api/ai/notification-events", "description": "Requires `audit.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "audit.read" ] }, { "apiToken": [ "audit.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI. The envelope is declared; the array elements are observed, not checked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": {} } }, "required": [ "events" ], "additionalProperties": {} } } }, "x-array-elements-observed": true }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/notification-run-now": { "post": { "summary": "POST /api/ai/notification-run-now", "description": "Requires `ai.run`. The request body is not described here.", "security": [ { "sessionCookie": [ "ai.run" ] }, { "apiToken": [ "ai.run" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/notification-test": { "post": { "summary": "POST /api/ai/notification-test", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/pricing/check": { "post": { "summary": "POST /api/ai/pricing/check", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "provider": { "type": "string", "enum": [ "ollama", "anthropic", "openai", "bedrock" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 400 } }, "required": [ "provider", "model" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "provider": { "type": "string" }, "model": { "type": "string" }, "priced": { "type": "boolean" }, "pricing": { "type": [ "null", "object" ] } }, "required": [ "model", "priced", "pricing", "provider", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/pricing/diagnostics": { "get": { "summary": "GET /api/ai/pricing/diagnostics", "description": "Requires `ai.run`. The request body is not described here.", "security": [ { "sessionCookie": [ "ai.run" ] }, { "apiToken": [ "ai.run" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pricing": { "type": "object", "properties": { "catalogVersion": { "type": "string" }, "currency": { "type": "string" }, "effectiveFrom": { "type": "string" }, "sourceUrls": { "type": "array", "items": { "type": "string" } } }, "required": [ "catalogVersion", "currency", "effectiveFrom", "sourceUrls" ] }, "selectedModel": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "priced": { "type": "boolean" }, "pricing": { "type": "object", "properties": { "pricingVersion": { "type": "string" }, "priceId": { "type": "string" }, "effectiveFrom": { "type": "string" }, "sourceUrl": { "type": "string" }, "routing": { "type": "string" }, "inputUsdPerMillion": { "type": "integer" }, "outputUsdPerMillion": { "type": "integer" } }, "required": [ "effectiveFrom", "inputUsdPerMillion", "outputUsdPerMillion", "priceId", "pricingVersion", "routing", "sourceUrl" ] } }, "required": [ "model", "priced", "pricing", "provider" ] }, "currentUnpricedModels": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "requests": { "type": "integer" }, "totalTokens": { "type": "integer" } }, "required": [ "model", "provider", "requests", "totalTokens" ] } }, "previousUnpricedModels": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "requests": { "type": "integer" }, "totalTokens": { "type": "integer" } }, "required": [ "model", "provider", "requests", "totalTokens" ] } } }, "required": [ "currentUnpricedModels", "previousUnpricedModels", "pricing", "selectedModel" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/test": { "post": { "summary": "POST /api/ai/test", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "provider": { "type": "string" }, "models": { "type": "array", "items": { "type": "string" } }, "modelPricing": { "type": "object", "properties": { "catalogVersion": { "type": "string" }, "priced": { "type": "integer" }, "unpriced": { "type": "integer" }, "models": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "priced": { "type": "boolean" }, "pricing": { "type": "object", "properties": { "pricingVersion": { "type": "string" }, "priceId": { "type": "string" }, "effectiveFrom": { "type": "string" }, "sourceUrl": { "type": "string" }, "routing": { "type": "string" }, "inputUsdPerMillion": { "type": "integer" }, "outputUsdPerMillion": { "type": "integer" } }, "required": [ "effectiveFrom", "inputUsdPerMillion", "outputUsdPerMillion", "priceId", "pricingVersion", "routing", "sourceUrl" ] } }, "required": [ "model", "priced", "pricing", "provider" ] } } }, "required": [ "catalogVersion", "models", "priced", "unpriced" ] } }, "required": [ "modelPricing", "models", "provider", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "success": { "type": "boolean" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/ai/usage/monthly": { "get": { "summary": "GET /api/ai/usage/monthly", "description": "Requires `ai.run`. The request body is not described here.", "security": [ { "sessionCookie": [ "ai.run" ] }, { "apiToken": [ "ai.run" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pricing": { "type": "object", "properties": { "approximate": { "type": "boolean" } }, "required": [ "approximate" ], "additionalProperties": {} }, "current": {}, "previous": {} }, "required": [ "pricing", "current", "previous" ], "additionalProperties": {} } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/auth/api-identities": { "get": { "summary": "GET /api/auth/api-identities", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "identities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "permissionsValid": { "type": "boolean" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "lastUsedAt": { "type": "null" }, "revokedAt": { "type": "null" } }, "required": [ "createdAt", "expiresAt", "id", "label", "lastUsedAt", "permissions", "permissionsValid", "revokedAt" ] } }, "availablePermissions": { "type": "array", "items": { "type": "string" } } }, "required": [ "availablePermissions", "identities" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/auth/api-identities", "description": "Requires `auth.admin`.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "permissions": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "network.read", "notes.write", "ai.run", "settings.write", "backup.restore", "auth.admin", "audit.read" ] } }, "expiresInMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "permissions", "expiresInMs" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "201": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "identity": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "permissionsValid": { "type": "boolean" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "lastUsedAt": { "type": "null" }, "revokedAt": { "type": "null" } }, "required": [ "createdAt", "expiresAt", "id", "label", "lastUsedAt", "permissions", "permissionsValid", "revokedAt" ] } }, "required": [ "identity", "token" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/auth/api-identities/:id/revoke": { "post": { "summary": "POST /api/auth/api-identities/:id/revoke", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/auth/api-identities/self": { "get": { "summary": "GET /api/auth/api-identities/self", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "integer" } }, "required": [ "expiresAt", "id", "label", "permissions" ] } }, "required": [ "identity" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/auth/audit-events": { "get": { "summary": "GET /api/auth/audit-events", "description": "Requires `audit.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "audit.read" ] }, { "apiToken": [ "audit.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string" }, "createdAt": { "type": "number" }, "eventType": { "type": "string" }, "outcome": { "type": "string" }, "authMethod": { "type": [ "string", "null" ] }, "actorHash": { "type": [ "string", "null" ] }, "principalHash": { "type": [ "string", "null" ] }, "requestId": { "type": [ "string", "null" ] }, "clientIpHash": { "type": [ "string", "null" ] }, "httpMethod": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] }, "metadata": { "type": [ "string", "null" ] } }, "required": [ "eventId", "createdAt", "eventType", "outcome" ], "additionalProperties": false } } }, "required": [ "events" ], "additionalProperties": {} } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/auth/change-password": { "post": { "summary": "POST /api/auth/change-password", "description": "Requires `auth.admin`.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "currentPassword": { "type": "string", "maxLength": 256 }, "newPassword": { "type": "string", "minLength": 14, "maxLength": 256 }, "revokeOtherSessions": { "type": "boolean" } }, "required": [ "currentPassword", "newPassword" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "revoked": { "type": "integer" } }, "required": [ "revoked", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/auth/login": { "post": { "summary": "POST /api/auth/login", "description": "No authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "password": { "type": "string", "minLength": 1, "maxLength": 256 }, "deviceLabel": { "type": "string", "maxLength": 200 } }, "required": [ "password" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "expiresAt": { "type": "integer" } }, "required": [ "expiresAt", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "429": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "503": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/auth/logout": { "post": { "summary": "POST /api/auth/logout", "description": "Requires any authenticated identity. The request body is not described here.", "security": [ { "sessionCookie": [] }, { "apiToken": [] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/auth/methods": { "get": { "summary": "GET /api/auth/methods", "description": "No authentication. The request body is not described here.", "security": [], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "local": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "google": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } }, "required": [ "google", "local" ], "x-observed": true } } } } } } }, "/api/auth/oidc/callback": { "get": { "summary": "GET /api/auth/oidc/callback", "description": "No authentication. The request body is not described here.", "security": [], "responses": { "200": { "description": "Handled." } } } }, "/api/auth/oidc/start": { "get": { "summary": "GET /api/auth/oidc/start", "description": "No authentication. The request body is not described here.", "security": [], "responses": { "200": { "description": "Handled." } } } }, "/api/auth/oidc/test": { "post": { "summary": "POST /api/auth/oidc/test", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "issuer": { "type": "string" } }, "required": [ "issuer", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "502": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/auth/security-config": { "get": { "summary": "GET /api/auth/security-config", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Declared by the server, and refused at runtime if it does not hold.", "content": { "application/json": { "schema": { "type": "object", "properties": { "oidc": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "provider": { "type": "string" }, "clientId": { "type": "string" }, "clientSecretSet": { "type": "boolean" }, "allowedEmails": { "maxItems": 500, "type": "array", "items": { "type": "string" } }, "allowedDomains": { "maxItems": 500, "type": "array", "items": { "type": "string" } } }, "required": [ "enabled", "provider", "clientId", "clientSecretSet", "allowedEmails", "allowedDomains" ], "additionalProperties": false }, "sessionTtlDays": { "type": "number" }, "trustedProxyConfigured": { "type": "boolean" }, "warnings": { "maxItems": 500, "type": "array", "items": { "type": "string" } } }, "required": [ "oidc", "sessionTtlDays", "trustedProxyConfigured", "warnings" ], "additionalProperties": false } } }, "x-enforced": true }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/auth/security-config", "description": "Requires `auth.admin`.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "clientId": { "type": "string", "maxLength": 500 }, "clientSecret": { "type": "string", "maxLength": 2000 }, "allowedEmails": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "allowedDomains": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 } } }, "required": [ "enabled", "clientId", "allowedEmails", "allowedDomains" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "clientSecretSet": { "type": "boolean" }, "warnings": { "type": "array" } }, "required": [ "clientSecretSet", "success", "warnings" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/auth/sessions": { "get": { "summary": "GET /api/auth/sessions", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} } } }, "required": [ "sessions" ], "additionalProperties": {} } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/auth/sessions/:id/revoke": { "post": { "summary": "POST /api/auth/sessions/:id/revoke", "description": "Requires `auth.admin`. The request body is not described here.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "404": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/auth/sessions/revoke-all": { "post": { "summary": "POST /api/auth/sessions/revoke-all", "description": "Requires `auth.admin`.", "security": [ { "sessionCookie": [ "auth.admin" ] }, { "apiToken": [ "auth.admin" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "includeSelf": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "revoked": { "type": "integer" } }, "required": [ "revoked", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/auth/status": { "get": { "summary": "GET /api/auth/status", "description": "No authentication. The request body is not described here.", "security": [], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "authMethod": { "type": [ "null", "string" ] }, "oidcEnabled": { "type": "boolean" }, "localLoginEnabled": { "type": "boolean" } }, "required": [ "authMethod", "authenticated", "localLoginEnabled", "oidcEnabled" ], "x-observed": true } } } } } } }, "/api/backup/config": { "post": { "summary": "POST /api/backup/config", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "intervalHours": { "type": "integer", "exclusiveMinimum": 0, "maximum": 596 }, "maxGenerations": { "type": "integer", "minimum": 2, "maximum": 9007199254740991 }, "maxBackupBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "autoPrune": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "config": { "type": "object", "properties": { "intervalHours": { "type": "integer" }, "maxGenerations": { "type": "integer" }, "maxBackupBytes": { "type": "integer" }, "autoPrune": { "type": "boolean" } }, "required": [ "intervalHours", "maxGenerations" ] } }, "required": [ "config", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/backup/create": { "post": { "summary": "POST /api/backup/create", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/backup/download/:name": { "get": { "summary": "GET /api/backup/download/:name", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/backup/list": { "get": { "summary": "GET /api/backup/list", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/backup/prune": { "post": { "summary": "POST /api/backup/prune", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "execute": { "default": false, "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "202": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "job": { "type": "object", "properties": { "id": { "type": "string" }, "operation": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "operation", "status" ] } }, "required": [ "job", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "409": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "job": { "type": "object", "properties": { "id": { "type": "string" }, "operation": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "operation", "status" ] } }, "required": [ "error", "job" ], "x-observed": true } } } } } } }, "/api/backup/prune/:jobId": { "delete": { "summary": "DELETE /api/backup/prune/:jobId", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "job": { "type": "object", "properties": { "id": { "type": "string" }, "operation": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "operation", "status" ] } }, "required": [ "job", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "409": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "job": { "type": "object", "properties": { "id": { "type": "string" }, "operation": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "operation", "status" ] } }, "required": [ "error", "job" ], "x-observed": true } } } } } }, "get": { "summary": "GET /api/backup/prune/:jobId", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "job": { "type": "object", "properties": { "id": { "type": "string" }, "operation": { "type": "string" }, "status": { "type": "string" }, "result": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "name", "size" ] } }, "candidateBytes": { "type": "integer" }, "deleted": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "name", "size" ] } }, "deletedBytes": { "type": "integer" } } } }, "required": [ "id", "operation", "result", "status" ] } }, "required": [ "job", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/backup/restore": { "post": { "summary": "POST /api/backup/restore", "description": "Requires `backup.restore`.", "security": [ { "sessionCookie": [ "backup.restore" ] }, { "apiToken": [ "backup.restore" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "message", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/backup/upload": { "post": { "summary": "POST /api/backup/upload", "description": "Requires `backup.restore`. The request body is not described here.", "security": [ { "sessionCookie": [ "backup.restore" ] }, { "apiToken": [ "backup.restore" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "message", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "409": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "413": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/beacons": { "get": { "summary": "GET /api/beacons", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI. The envelope is declared; the array elements are observed, not checked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "beacons": { "type": "array", "items": {} } }, "required": [ "beacons" ], "additionalProperties": {} } } }, "x-array-elements-observed": true }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/beacons/:id/dismiss": { "post": { "summary": "POST /api/beacons/:id/dismiss", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/beacons/config": { "get": { "summary": "GET /api/beacons/config", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/beacons/config", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "minObs": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 32 } ] }, "maxCov": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 32 } ] }, "minIntervalMs": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 32 } ] }, "maxIntervalMs": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 32 } ] }, "scanIntervalMs": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 32 } ] }, "whitelistDomains": { "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 253 } }, "orgAllowlist": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 100 } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/cisco/detect": { "post": { "summary": "POST /api/cisco/detect", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ciscoIp": { "type": "string", "maxLength": 45 }, "ciscoUser": { "type": "string", "maxLength": 64 }, "ciscoPass": { "type": "string", "maxLength": 256 }, "ciscoEnablePass": { "type": "string", "maxLength": 256 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "502": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "code": { "type": "string" }, "error": { "type": "string" }, "diag": { "type": "object", "properties": { "phase": { "type": "string" } }, "required": [ "phase" ] } }, "required": [ "code", "diag", "error", "success" ], "x-observed": true } } } } } } }, "/api/config/ai": { "get": { "summary": "GET /api/config/ai", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Declared by the server, and refused at runtime if it does not hold.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "models": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "ollamaEndpoint": { "type": "string" }, "region": { "type": "string" }, "guardrail": { "type": "object", "properties": {}, "additionalProperties": {} }, "providers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "keySet": { "type": "boolean" }, "consented": { "type": "boolean" } }, "required": [ "keySet" ], "additionalProperties": false } }, "selectedModelPricing": {} }, "required": [ "provider", "models", "ollamaEndpoint", "region", "guardrail", "providers" ], "additionalProperties": false } } }, "x-enforced": true }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/config/ai", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "provider": { "type": "string", "enum": [ "disabled", "ollama", "anthropic", "openai", "bedrock" ] }, "models": { "type": "object", "properties": { "ollama": { "type": "string", "maxLength": 200 }, "anthropic": { "type": "string", "maxLength": 200 }, "openai": { "type": "string", "maxLength": 200 }, "bedrock": { "type": "string", "maxLength": 400 } }, "additionalProperties": false }, "keys": { "type": "object", "properties": { "anthropic": { "type": "string", "maxLength": 4096 }, "openai": { "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "clearKeys": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "anthropic", "openai" ] } }, "cloudConsent": { "type": "object", "properties": { "anthropic": { "type": "boolean" }, "openai": { "type": "boolean" }, "bedrock": { "type": "boolean" } }, "additionalProperties": false }, "ollamaEndpoint": { "type": "string", "maxLength": 2048 }, "region": { "type": "string", "maxLength": 64 }, "guardrail": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "id": { "type": "string", "maxLength": 2048 }, "version": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "provider": { "type": "string" }, "models": { "type": "object", "properties": { "ollama": { "type": "string" }, "anthropic": { "type": "string" }, "openai": { "type": "string" }, "bedrock": { "type": "string" } }, "required": [ "anthropic", "bedrock", "ollama", "openai" ] }, "ollamaEndpoint": { "type": "string" }, "region": { "type": "string" }, "guardrail": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "id": { "type": "string" }, "version": { "type": "string" } }, "required": [ "enabled", "id", "version" ] }, "providers": { "type": "object", "properties": { "ollama": { "type": "object", "properties": { "keySet": { "type": "boolean" } }, "required": [ "keySet" ] }, "anthropic": { "type": "object", "properties": { "keySet": { "type": "boolean" }, "consented": { "type": "boolean" } }, "required": [ "consented", "keySet" ] }, "openai": { "type": "object", "properties": { "keySet": { "type": "boolean" }, "consented": { "type": "boolean" } }, "required": [ "consented", "keySet" ] }, "bedrock": { "type": "object", "properties": { "keySet": { "type": "boolean" }, "consented": { "type": "boolean" } }, "required": [ "consented", "keySet" ] } }, "required": [ "anthropic", "bedrock", "ollama", "openai" ] }, "selectedModelPricing": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "priced": { "type": "boolean" }, "pricing": { "type": "null" } }, "required": [ "model", "priced", "pricing", "provider" ] } }, "required": [ "guardrail", "models", "ollamaEndpoint", "provider", "providers", "region", "selectedModelPricing", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/config/datasources": { "get": { "summary": "GET /api/config/datasources", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/config/datasources", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dnsmasq": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "logFile": { "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "inspect": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "logFile": { "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "dhcpd": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "logFile": { "type": "string", "maxLength": 4096 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/config/detection-notifications": { "get": { "summary": "GET /api/config/detection-notifications", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "threat": { "type": "object", "properties": { "slack": { "type": "boolean" }, "history": { "type": "boolean" } }, "additionalProperties": false }, "newDevice": { "type": "object", "properties": { "slack": { "type": "boolean" }, "history": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "threat", "newDevice" ], "additionalProperties": false } }, "required": [ "config" ], "additionalProperties": {} } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/config/detection-notifications", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threat": { "type": "object", "properties": { "slack": { "type": "boolean" }, "history": { "type": "boolean" } }, "additionalProperties": false }, "newDevice": { "type": "object", "properties": { "slack": { "type": "boolean" }, "history": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "config": { "type": "object", "properties": { "threat": { "type": "object", "properties": { "slack": { "type": "boolean" }, "history": { "type": "boolean" } }, "required": [ "history", "slack" ] }, "newDevice": { "type": "object", "properties": { "slack": { "type": "boolean" }, "history": { "type": "boolean" } }, "required": [ "history", "slack" ] } }, "required": [ "newDevice", "threat" ] } }, "required": [ "config", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/config/general": { "post": { "summary": "POST /api/config/general", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "homeCountry": { "type": "string" }, "language": { "type": "string", "enum": [ "ja", "en" ] }, "autoInvestigate": { "type": "boolean" }, "retentionDays": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timelineSource": { "type": "string", "enum": [ "observed", "lastSeen" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/config/manual-threat": { "get": { "summary": "GET /api/config/manual-threat", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/config/manual-threat", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "keys": { "type": "object", "properties": { "abuseipdb": { "type": "string", "maxLength": 4096 }, "virustotal": { "type": "string", "maxLength": 4096 }, "otx": { "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "clearKeys": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "abuseipdb", "virustotal", "otx" ] } }, "cacheTtlMinutes": { "type": "integer", "minimum": 5, "maximum": 1440 }, "minIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "providers": { "type": "object", "properties": { "abuseipdb": { "type": "object", "properties": { "keySet": { "type": "boolean" } }, "required": [ "keySet" ] }, "virustotal": { "type": "object", "properties": { "keySet": { "type": "boolean" } }, "required": [ "keySet" ] }, "otx": { "type": "object", "properties": { "keySet": { "type": "boolean" } }, "required": [ "keySet" ] } }, "required": [ "abuseipdb", "otx", "virustotal" ] }, "cacheTtlMinutes": { "type": "integer" }, "minIntervalSeconds": { "type": "integer" } }, "required": [ "cacheTtlMinutes", "minIntervalSeconds", "providers", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/config/slack": { "get": { "summary": "GET /api/config/slack", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "cooldownMinutes": { "type": "number" }, "tokenSet": { "type": "boolean" } }, "required": [ "enabled", "userId", "displayName", "cooldownMinutes", "tokenSet" ], "additionalProperties": false } }, "required": [ "config" ], "additionalProperties": false } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/config/slack", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "token": { "type": "string", "maxLength": 512 }, "userId": { "type": "string", "maxLength": 256 }, "cooldownMinutes": { "type": "number", "exclusiveMinimum": 0, "maximum": 1440 }, "displayName": { "type": "string", "maxLength": 256 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "userId": { "type": "string" }, "displayName": { "type": "string" }, "cooldownMinutes": { "type": "integer" }, "tokenSet": { "type": "boolean" } }, "required": [ "cooldownMinutes", "displayName", "enabled", "tokenSet", "userId" ] } }, "required": [ "config", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/connections": { "get": { "summary": "GET /api/connections", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI. The envelope is declared; the array elements are observed, not checked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": {} }, "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" }, "serverTime": { "type": "number" } }, "required": [ "connections", "total", "limit", "offset", "serverTime" ], "additionalProperties": {} } } }, "x-array-elements-observed": true }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/connections/export": { "get": { "summary": "GET /api/connections/export", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/connections/memory": { "get": { "summary": "GET /api/connections/memory", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/connections/new-nodes": { "get": { "summary": "GET /api/connections/new-nodes", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/connections/summary": { "get": { "summary": "GET /api/connections/summary", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI. The envelope is declared; the array elements are observed, not checked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "byDst": { "type": "array", "items": {} }, "byDevice": { "type": "array", "items": {} }, "total": { "type": "number" }, "timelineBasis": { "type": "string", "enum": [ "observed", "lastSeen" ] }, "timelineBucketMs": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "timelineScopeFallback": { "type": "boolean" }, "serverTime": { "type": "number" }, "cached": { "type": "boolean" } }, "required": [ "byDst", "byDevice", "total", "timelineBasis", "timelineBucketMs", "timelineScopeFallback", "serverTime", "cached" ], "additionalProperties": {} } } }, "x-array-elements-observed": true }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/connections/threat-connections": { "get": { "summary": "GET /api/connections/threat-connections", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/connections/threat-counts": { "get": { "summary": "GET /api/connections/threat-counts", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "safe": { "type": "number" }, "warn": { "type": "number" }, "danger": { "type": "number" }, "serverTime": { "type": "number" } }, "required": [ "safe", "warn", "danger", "serverTime" ], "additionalProperties": {} } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/devices": { "get": { "summary": "GET /api/devices", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI. The envelope is declared; the array elements are observed, not checked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "array", "items": {} } }, "required": [ "devices" ], "additionalProperties": {} } } }, "x-array-elements-observed": true }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/devices/archive": { "post": { "summary": "POST /api/devices/archive", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "deviceId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/devices/merge": { "post": { "summary": "POST /api/devices/merge", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "keepId": { "type": "string", "minLength": 1, "maxLength": 128 }, "dropId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "keepId", "dropId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/devices/merge-candidates": { "get": { "summary": "GET /api/devices/merge-candidates", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/devices/reject": { "post": { "summary": "POST /api/devices/reject", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "maxLength": 16, "pattern": "^\\d+$" } ] } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/devices/unarchive": { "post": { "summary": "POST /api/devices/unarchive", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "deviceId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/login": { "post": { "summary": "POST /api/login", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "username": { "type": "string", "maxLength": 64 }, "password": { "type": "string", "maxLength": 256 }, "routerIp": { "type": "string", "maxLength": 45 }, "yamahaIp": { "type": "string", "maxLength": 45 }, "yamahaUser": { "type": "string", "maxLength": 64 }, "yamahaPass": { "type": "string", "maxLength": 256 }, "yamahaNat": { "anyOf": [ { "type": "string", "maxLength": 6 }, { "type": "integer", "minimum": 0, "maximum": 999999 } ] }, "ciscoIp": { "type": "string", "maxLength": 45 }, "ciscoUser": { "type": "string", "maxLength": 64 }, "ciscoPass": { "type": "string", "maxLength": 256 }, "ciscoEnablePass": { "type": "string", "maxLength": 256 }, "doAsus": { "type": "boolean" }, "doYamaha": { "type": "boolean" }, "doCisco": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "routerIp": {} }, "required": [ "routerIp", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "success" ], "x-observed": true } } } }, "502": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "success" ], "x-observed": true } } } } } } }, "/api/nonce": { "post": { "summary": "POST /api/nonce", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/notes": { "get": { "summary": "GET /api/notes", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "anyOf": [ { "maxItems": 500, "type": "array", "items": {} }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } ] } }, "required": [ "notes" ], "additionalProperties": {} } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/notes", "description": "Requires `notes.write`.", "security": [ { "sessionCookie": [ "notes.write" ] }, { "apiToken": [ "notes.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ip": { "type": "string", "maxLength": 45 }, "mac": { "type": "string", "maxLength": 64 }, "note": { "type": "string", "maxLength": 500 }, "deviceId": { "type": "string", "maxLength": 128 }, "key": { "type": "string", "maxLength": 256 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } } }, "/api/notes/draft": { "post": { "summary": "POST /api/notes/draft", "description": "Requires `notes.write`.", "security": [ { "sessionCookie": [ "notes.write" ] }, { "apiToken": [ "notes.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ip": { "type": "string", "minLength": 1, "maxLength": 45 } }, "required": [ "ip" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string" } }, "required": [ "ip" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/notification-log": { "get": { "summary": "GET /api/notification-log", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "src": { "type": "string" }, "ts": { "type": "integer" } }, "required": [ "id", "src", "ts", "type" ] } }, "serverTime": { "type": "integer" } }, "required": [ "logs", "serverTime" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/routers": { "get": { "summary": "GET /api/routers", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "routers": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "displayName": { "type": "string" }, "hostName": { "type": "string" }, "ip": { "type": "string" }, "user": { "type": "string" }, "nat": { "type": [ "string", "number" ] }, "enabled": { "type": "boolean" }, "passSet": { "type": "boolean" }, "enablePassSet": { "type": "boolean" }, "ready": { "type": "boolean" }, "state": { "type": "string" }, "message": { "type": "string" }, "lastSuccessAt": { "type": [ "number", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "sessionCount": { "type": "number" } }, "required": [ "id", "kind", "displayName", "hostName", "ip", "user", "enabled", "passSet", "enablePassSet", "ready", "state", "message", "lastSuccessAt", "lastError", "sessionCount" ], "additionalProperties": false } }, "maxRouters": { "type": "number" }, "serverTime": { "type": "number" }, "processStartedAt": { "type": "number" } }, "required": [ "routers", "maxRouters", "serverTime", "processStartedAt" ], "additionalProperties": {} } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } }, "post": { "summary": "POST /api/routers", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "yamaha", "cisco", "conntrack" ] }, "displayName": { "type": "string", "maxLength": 80 }, "ip": { "type": "string", "maxLength": 255 }, "user": { "type": "string", "maxLength": 255 }, "pass": { "type": "string", "maxLength": 4096 }, "enablePass": { "type": "string", "maxLength": 4096 }, "nat": { "type": [ "string", "number" ] }, "enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "201": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "router": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "kind" ] } }, "required": [ "router", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "success": { "type": "boolean" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/routers/:id": { "delete": { "summary": "DELETE /api/routers/:id", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "404": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } } } }, "put": { "summary": "PUT /api/routers/:id", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "yamaha", "cisco", "conntrack" ] }, "displayName": { "type": "string", "maxLength": 80 }, "ip": { "type": "string", "maxLength": 255 }, "user": { "type": "string", "maxLength": 255 }, "pass": { "type": "string", "maxLength": 4096 }, "enablePass": { "type": "string", "maxLength": 4096 }, "nat": { "type": [ "string", "number" ] }, "enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "router": { "type": "object", "properties": { "displayName": { "type": "string" }, "id": { "type": "string" } }, "required": [ "displayName", "id" ] } }, "required": [ "router", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/routers/detect": { "post": { "summary": "POST /api/routers/detect", "description": "Requires `settings.write`. The request body is not described here.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "responses": { "200": { "description": "Handled." }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/slack/lookup-user": { "post": { "summary": "POST /api/slack/lookup-user", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "token": { "type": "string", "maxLength": 512 } }, "required": [ "username" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "ok" ], "x-observed": true } } } } } } }, "/api/slack/test": { "post": { "summary": "POST /api/slack/test", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "success" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "success" ], "x-observed": true } } } } } } }, "/api/slack/verify": { "post": { "summary": "POST /api/slack/verify", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string", "maxLength": 512 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "500": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error", "ok" ], "x-observed": true } } } } } } }, "/api/status": { "get": { "summary": "GET /api/status", "description": "Requires `network.read`. The request body is not described here.", "security": [ { "sessionCookie": [ "network.read" ] }, { "apiToken": [ "network.read" ] } ], "responses": { "200": { "description": "Declared by the server, and checked in CI.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "routerIp": { "type": [ "string", "null" ] }, "enrichment": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "authenticated", "routerIp", "enrichment" ], "additionalProperties": {} } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/threat/manual-lookup": { "post": { "summary": "POST /api/threat/manual-lookup", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ip": { "type": "string", "minLength": 3, "maxLength": 45 }, "providers": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "abuseipdb", "virustotal", "otx" ] } } }, "required": [ "ip", "providers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "ip": { "type": "string" }, "checkedAt": { "type": "integer" }, "results": { "type": "object", "properties": { "abuseipdb": { "type": "object", "properties": { "ok": { "type": "boolean" }, "summary": { "type": "object", "properties": { "abuseConfidenceScore": { "type": "integer" }, "totalReports": { "type": "integer" }, "lastReportedAt": { "type": "null" }, "countryCode": { "type": "null" }, "isp": { "type": "null" }, "domain": { "type": "null" }, "usageType": { "type": "null" } }, "required": [ "abuseConfidenceScore", "countryCode", "domain", "isp", "lastReportedAt", "totalReports", "usageType" ] }, "checkedAt": { "type": "integer" }, "cached": { "type": "boolean" } }, "required": [ "cached", "checkedAt", "ok", "summary" ] } }, "required": [ "abuseipdb" ] } }, "required": [ "checkedAt", "ip", "results", "success" ], "x-observed": true } } } }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." } } } }, "/api/yamaha/detect": { "post": { "summary": "POST /api/yamaha/detect", "description": "Requires `settings.write`.", "security": [ { "sessionCookie": [ "settings.write" ] }, { "apiToken": [ "settings.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "yamahaIp": { "type": "string", "maxLength": 45 }, "yamahaUser": { "type": "string", "maxLength": 64 }, "yamahaPass": { "type": "string", "maxLength": 256 }, "yamahaNat": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,6}$" }, { "type": "integer", "minimum": 0, "maximum": 999999 } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Handled." }, "400": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "x-observed": true } } } }, "401": { "description": "No usable credential." }, "403": { "description": "Authenticated, but not permitted." }, "502": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "code": { "type": "string" }, "error": { "type": "string" }, "diag": { "type": "object", "properties": { "phase": { "type": "string" } }, "required": [ "phase" ] } }, "required": [ "code", "diag", "error", "success" ], "x-observed": true } } } } } } }, "/healthz": { "get": { "summary": "GET /healthz", "description": "No authentication. The request body is not described here.", "security": [], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "x-observed": true } } } } } } }, "/readyz": { "get": { "summary": "GET /readyz", "description": "No authentication. The request body is not described here.", "security": [], "responses": { "200": { "description": "Handled. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "x-observed": true } } } }, "503": { "description": "Observed under test. Shape observed under test, not a guarantee: responses are not validated on the way out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "components": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "component", "reason" ] } } }, "required": [ "status" ], "x-observed": true } } } } } } } }, "x-response-contract-coverage": { "declared": [ "GET /api/agent/capabilities", "GET /api/agent/threat-intel", "GET /api/agents", "GET /api/ai/conversations", "GET /api/ai/conversations/:id", "GET /api/ai/facts", "GET /api/ai/notification-config", "GET /api/ai/notification-events", "GET /api/ai/usage/monthly", "GET /api/auth/audit-events", "GET /api/auth/security-config", "GET /api/auth/sessions", "GET /api/beacons", "GET /api/config/ai", "GET /api/config/detection-notifications", "GET /api/config/slack", "GET /api/connections", "GET /api/connections/summary", "GET /api/connections/threat-counts", "GET /api/devices", "GET /api/notes", "GET /api/routers", "GET /api/status", "POST /api/agent/ingest" ], "observedOnly": [ "DELETE /api/ai/conversations/:id", "DELETE /api/backup/prune/:jobId", "DELETE /api/routers/:id", "GET /api/agent/geo-cache", "GET /api/agents/enrollment-requests", "GET /api/agents/ingest-metrics", "GET /api/ai/pricing/diagnostics", "GET /api/auth/api-identities", "GET /api/auth/api-identities/self", "GET /api/auth/methods", "GET /api/auth/status", "GET /api/backup/prune/:jobId", "GET /api/beacons/config", "GET /api/devices/merge-candidates", "GET /api/notification-log", "POST /api/admin/regenerate-token", "POST /api/admin/verify", "POST /api/agent/enrollment-requests", "POST /api/agent/enrollment-requests/claim", "POST /api/agent/registration/revoke", "POST /api/agent/token/rotate", "POST /api/agents/:agentId/revoke", "POST /api/agents/enrollment-requests/:requestId/approve", "POST /api/agents/enrollment-requests/:requestId/reject", "POST /api/agents/enrollment-tokens", "POST /api/ai/analyze", "POST /api/ai/chat", "POST /api/ai/guardrails", "POST /api/ai/models", "POST /api/ai/notification-config", "POST /api/ai/pricing/check", "POST /api/ai/test", "POST /api/auth/api-identities", "POST /api/auth/change-password", "POST /api/auth/login", "POST /api/auth/logout", "POST /api/auth/oidc/test", "POST /api/auth/security-config", "POST /api/auth/sessions/:id/revoke", "POST /api/auth/sessions/revoke-all", "POST /api/backup/config", "POST /api/backup/prune", "POST /api/backup/restore", "POST /api/backup/upload", "POST /api/beacons/:id/dismiss", "POST /api/beacons/config", "POST /api/cisco/detect", "POST /api/config/ai", "POST /api/config/datasources", "POST /api/config/detection-notifications", "POST /api/config/general", "POST /api/config/manual-threat", "POST /api/config/slack", "POST /api/devices/archive", "POST /api/devices/merge", "POST /api/devices/reject", "POST /api/devices/unarchive", "POST /api/login", "POST /api/notes", "POST /api/notes/draft", "POST /api/routers", "POST /api/slack/lookup-user", "POST /api/slack/test", "POST /api/slack/verify", "POST /api/threat/manual-lookup", "POST /api/yamaha/detect", "PUT /api/routers/:id" ], "neverEnforced": [ "GET /api/auth/oidc/callback", "GET /api/auth/oidc/start", "GET /api/backup/download/:name", "GET /api/connections/export", "GET /healthz", "GET /readyz" ], "undescribed": [ "GET /api/agents/transport", "GET /api/backup/list", "GET /api/config/datasources", "GET /api/config/manual-threat", "GET /api/connections/memory", "GET /api/connections/new-nodes", "GET /api/connections/threat-connections", "POST /api/agents/transport", "POST /api/ai/notification-run-now", "POST /api/ai/notification-test", "POST /api/auth/api-identities/:id/revoke", "POST /api/backup/create", "POST /api/nonce", "POST /api/routers/detect" ] } }