{ "openapi": "3.1.0", "info": { "title": "Shadow Warden AI — Gateway", "description": "9-layer AI security gateway. All payloads must pass through **POST /filter** before reaching any model or downstream service.\n\n**Pipeline:** TopologicalGatekeeper → ObfuscationDecoder → SecretRedactor → SemanticGuard → HyperbolicBrain → CausalArbiter → PhishGuard → ERS → Decision\n\nBlocked HIGH/BLOCK attacks trigger the **Evolution Loop**: Claude Opus analyses the attack and auto-generates a new detection rule (hot-reload, no restart).\n\n**Auth:** `X-API-Key` header required (except dev mode). Enterprise supports OIDC Bearer tokens on `/ext/*` routes.\n\n**Rate limiting:** Per-tenant sliding window (default 60 req/min) plus a monthly request quota set by the plan. Shadow-ban at ERS score ≥ 0.75.\n\nEvery response advertises the throttling contract, so a client can pace itself instead of discovering a limit by being refused:\n\n- `RateLimit-Policy` / `RateLimit` — structured fields from draft-ietf-httpapi-ratelimit-headers-09, e.g. `RateLimit-Policy: \"requests-per-minute\";q=60;w=60` and `RateLimit: \"requests-per-minute\";r=59;t=41` — `q` quota, `w` window seconds, `r` remaining, `t` seconds to reset.\n- `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` — the earlier draft spelling, mirrored as `X-RateLimit-*`.\n- `Retry-After` — delta-seconds, on 429 only, naming the same instant as the reset parameter.\n\nLive counters accompany the policy on routes that consume the window; a route that consumes nothing publishes the policy alone. Full conventions: https://shadow-warden-ai.com/doc/rate-limits", "contact": { "name": "Shadow Warden AI", "url": "https://shadow-warden-ai.com/", "email": "security@shadow-warden-ai.com" }, "license": { "name": "Proprietary", "url": "https://shadow-warden-ai.com/terms" }, "version": "7.9.0" }, "servers": [ { "url": "https://api.shadow-warden-ai.com", "description": "Production" }, { "url": "http://localhost:8001", "description": "Local development" } ], "paths": { "/auth/login": { "post": { "tags": [ "auth" ], "summary": "Issue session cookie (HttpOnly, Secure)", "operationId": "login_auth_login_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/auth/signup": { "post": { "tags": [ "auth" ], "summary": "Register new account and auto-login (HttpOnly cookie)", "operationId": "signup_auth_signup_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Clear session cookie", "operationId": "logout_auth_logout_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/auth/me": { "get": { "tags": [ "auth" ], "summary": "Return current session user (credential-aware CORS)", "operationId": "me_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "openai-proxy" ], "summary": "Proxy Chat", "description": "OpenAI /v1/chat/completions proxy with Warden security gates.\n\nTwo ToolCallGuard interception points:\n [A] Incoming tool results (role=tool in request messages)\n — blocks prompt injection / secret exfil before it reaches the model\n [B] Outgoing tool calls (tool_calls in upstream response)\n — blocks dangerous commands before the client executes them", "operationId": "proxy_chat_v1_chat_completions_post", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Payload" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/v1/models": { "get": { "tags": [ "openai-proxy" ], "summary": "List Models", "description": "Proxy GET /v1/models to the upstream transparently.", "operationId": "list_models_v1_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/v1/embeddings": { "post": { "tags": [ "openai-proxy" ], "summary": "Proxy Embeddings", "description": "OpenAI /v1/embeddings proxy with Warden input filtering.\n\nSupported providers (via model name prefix):\n vertex/ → Vertex AI embeddings endpoint\n azure/ → Azure OpenAI embeddings endpoint\n everything else → OPENAI_UPSTREAM /v1/embeddings", "operationId": "proxy_embeddings_v1_embeddings_post", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Payload" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/portal/auth/register": { "post": { "tags": [ "portal" ], "summary": "Register", "description": "Create a new customer account + tenant.", "operationId": "register_portal_auth_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_RegisterIn" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/portal/auth/login": { "post": { "tags": [ "portal" ], "summary": "Login", "operationId": "login_portal_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_LoginIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/portal/auth/totp/complete": { "post": { "tags": [ "portal" ], "summary": "Totp Complete", "description": "Step 2 of login when TOTP is enabled: verify 6-digit code and issue full JWT.", "operationId": "totp_complete_portal_auth_totp_complete_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_TotpCompleteIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/portal/auth/totp/setup": { "post": { "tags": [ "portal" ], "summary": "Totp Setup", "description": "Generate a new TOTP secret and return otpauth:// URI for QR code rendering.", "operationId": "totp_setup_portal_auth_totp_setup_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/auth/totp/confirm": { "post": { "tags": [ "portal" ], "summary": "Totp Confirm", "description": "Confirm the first TOTP code to activate 2FA on the account.", "operationId": "totp_confirm_portal_auth_totp_confirm_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_TotpConfirmIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/auth/totp/disable": { "post": { "tags": [ "portal" ], "summary": "Totp Disable", "description": "Disable TOTP — requires current authenticator code.", "operationId": "totp_disable_portal_auth_totp_disable_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_TotpDisableIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/auth/totp/status": { "get": { "tags": [ "portal" ], "summary": "Totp Status", "description": "Return whether TOTP is enabled for the current user.", "operationId": "totp_status_portal_auth_totp_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/auth/refresh": { "post": { "tags": [ "portal" ], "summary": "Refresh Token", "operationId": "refresh_token_portal_auth_refresh_post", "parameters": [ { "name": "warden_refresh", "in": "cookie", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Warden Refresh" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_TokenOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/portal/auth/logout": { "post": { "tags": [ "portal" ], "summary": "Logout", "operationId": "logout_portal_auth_logout_post", "responses": { "204": { "description": "Successful Response" } } } }, "/portal/auth/forgot-password": { "post": { "tags": [ "portal" ], "summary": "Forgot Password", "description": "Generate a reset token (email delivery is out-of-scope for v1 — token returned in response).", "operationId": "forgot_password_portal_auth_forgot_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ForgotPasswordIn" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/portal/auth/reset-password": { "post": { "tags": [ "portal" ], "summary": "Reset Password", "operationId": "reset_password_portal_auth_reset_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ResetPasswordIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/portal/me": { "get": { "tags": [ "portal" ], "summary": "Get Me", "operationId": "get_me_portal_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] }, "patch": { "tags": [ "portal" ], "summary": "Patch Me", "operationId": "patch_me_portal_me_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_PatchMeIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/me/change-password": { "post": { "tags": [ "portal" ], "summary": "Change Password", "operationId": "change_password_portal_me_change_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_ChangePasswordIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/keys": { "get": { "tags": [ "portal" ], "summary": "List Keys", "operationId": "list_keys_portal_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] }, "post": { "tags": [ "portal" ], "summary": "Create Key", "operationId": "create_key_portal_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_CreateKeyIn" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/keys/{key_id}": { "patch": { "tags": [ "portal" ], "summary": "Patch Key", "operationId": "patch_key_portal_keys__key_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_PatchKeyIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "portal" ], "summary": "Revoke Key", "operationId": "revoke_key_portal_keys__key_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/portal/stats/summary": { "get": { "tags": [ "portal" ], "summary": "Stats Summary", "operationId": "stats_summary_portal_stats_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/stats/daily": { "get": { "tags": [ "portal" ], "summary": "Stats Daily", "operationId": "stats_daily_portal_stats_daily_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/portal/stats/flags": { "get": { "tags": [ "portal" ], "summary": "Stats Flags", "operationId": "stats_flags_portal_stats_flags_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/billing": { "get": { "tags": [ "portal" ], "summary": "Billing", "operationId": "billing_portal_billing_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/portal/waitlist": { "post": { "tags": [ "portal" ], "summary": "Waitlist Signup", "description": "Public endpoint — no auth required. Stores early-access signups.", "operationId": "waitlist_signup_portal_waitlist_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_WaitlistIn" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents": { "get": { "tags": [ "Agentic Payment Protocol" ], "summary": "List registered agents for a tenant", "operationId": "list_agents_agents_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response List Agents Agents Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Agentic Payment Protocol" ], "summary": "Register a new AI agent", "operationId": "register_agent_agents_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/warden__agentic__router__AgentRegisterRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Register Agent Agents Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/activity": { "get": { "tags": [ "Agentic Payment Protocol" ], "summary": "Agentic activity audit log for a tenant", "operationId": "get_activity_agents_activity_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Tenant Id" } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response Get Activity Agents Activity Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/revoke-all": { "post": { "tags": [ "Agentic Payment Protocol" ], "summary": "Revoke all active agents for a tenant", "operationId": "revoke_all_agents_agents_revoke_all_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Revoke All Agents Agents Revoke All Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}": { "put": { "tags": [ "Agentic Payment Protocol" ], "summary": "Update agent limits", "operationId": "update_agent_agents__agent_id__put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Agent Agents Agent Id Put" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Agentic Payment Protocol" ], "summary": "Revoke an agent", "operationId": "revoke_agent_agents__agent_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Revoke Agent Agents Agent Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/mcp/quote": { "post": { "tags": [ "Agentic Payment Protocol" ], "summary": "Create a one-time invoice hash for an agent transaction", "operationId": "mcp_quote_mcp_quote_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Mcp Quote Mcp Quote Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/mcp/mandate/execute": { "post": { "tags": [ "Agentic Payment Protocol" ], "summary": "Validate and execute an AP2 payment mandate", "operationId": "mcp_mandate_execute_mcp_mandate_execute_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateExecuteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Mcp Mandate Execute Mcp Mandate Execute Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/threat/neutralizer/sectors": { "get": { "tags": [ "threat-neutralizer" ], "summary": "List available sectors with threat counts", "operationId": "sectors_endpoint_threat_neutralizer_sectors_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Response Sectors Endpoint Threat Neutralizer Sectors Get" } } } } } } }, "/threat/neutralizer/matrix": { "get": { "tags": [ "threat-neutralizer" ], "summary": "Full threat family matrix, optionally filtered by sector", "operationId": "threat_matrix_threat_neutralizer_matrix_get", "parameters": [ { "name": "sector", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "B2B", "B2C", "E-Commerce" ], "type": "string" }, { "type": "null" } ], "description": "Filter by sector: B2B | B2C | E-Commerce", "title": "Sector" }, "description": "Filter by sector: B2B | B2C | E-Commerce" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response Threat Matrix Threat Neutralizer Matrix Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/threat/neutralizer/families/{threat_id}": { "get": { "tags": [ "threat-neutralizer" ], "summary": "Get a single threat family by ID", "operationId": "threat_family_threat_neutralizer_families__threat_id__get", "parameters": [ { "name": "threat_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Threat Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Threat Family Threat Neutralizer Families Threat Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/threat/neutralizer/assess": { "post": { "tags": [ "threat-neutralizer" ], "summary": "Standalone business threat assessment — returns neutralizer report", "operationId": "assess_threat_neutralizer_assess_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/warden__threat_neutralizer_router__AssessRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Assess Threat Neutralizer Assess Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/threat/neutralizer/hierarchy": { "get": { "tags": [ "threat-neutralizer" ], "summary": "Risk control hierarchy — effectiveness levels and guidance", "operationId": "control_hierarchy_threat_neutralizer_hierarchy_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Control Hierarchy Threat Neutralizer Hierarchy Get" } } } } } } }, "/financial/impact": { "get": { "tags": [ "Financial Impact" ], "summary": "Get Impact", "description": "Full dollar impact report — monthly breakdown, 3-year projection, ROI by tier.", "operationId": "get_impact_financial_impact_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "industry", "in": "query", "required": false, "schema": { "type": "string", "description": "Industry sector (fintech, healthcare, ecommerce, saas, government, education, legal)", "default": "saas", "title": "Industry" }, "description": "Industry sector (fintech, healthcare, ecommerce, saas, government, education, legal)" }, { "name": "requests", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Monthly request volume (auto-detected from logs if omitted)", "title": "Requests" }, "description": "Monthly request volume (auto-detected from logs if omitted)" }, { "name": "cost_per_req", "in": "query", "required": false, "schema": { "type": "number", "description": "Average LLM cost per request (USD)", "default": 0.002, "title": "Cost Per Req" }, "description": "Average LLM cost per request (USD)" }, { "name": "live", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Use live data from logs/Redis (false = traffic estimate only)", "default": true, "title": "Live" }, "description": "Use live data from logs/Redis (false = traffic estimate only)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/financial/cost-saved": { "get": { "tags": [ "Financial Impact" ], "summary": "Get Cost Saved", "description": "Quick read of cumulative LLM inference cost saved via shadow banning.\nReads directly from Prometheus counter — no calculation needed.", "operationId": "get_cost_saved_financial_cost_saved_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/financial/roi": { "get": { "tags": [ "Financial Impact" ], "summary": "Get Roi", "description": "Quick ROI summary for a single pricing tier.", "operationId": "get_roi_financial_roi_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "industry", "in": "query", "required": false, "schema": { "type": "string", "default": "saas", "title": "Industry" } }, { "name": "tier", "in": "query", "required": false, "schema": { "type": "string", "description": "Pricing tier: startup, professional, enterprise", "default": "professional", "title": "Tier" }, "description": "Pricing tier: startup, professional, enterprise" }, { "name": "requests", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Requests" } }, { "name": "cost_per_req", "in": "query", "required": false, "schema": { "type": "number", "default": 0.002, "title": "Cost Per Req" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/financial/generate-proposal": { "post": { "tags": [ "Financial Impact" ], "summary": "Generate Proposal", "description": "Generate a customer-facing ROI proposal with full impact breakdown,\nrecommended pricing tier, and headline numbers suitable for a sales deck.", "operationId": "generate_proposal_financial_generate_proposal_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/tenant/impact": { "get": { "tags": [ "Tenant Impact" ], "summary": "Tenant Impact", "description": "Dollar Impact Calculator — filtered to the authenticated tenant.\n\nReturns live ROI metrics: blocks, PII intercepts, dollar value saved,\nthreat breakdown, daily sparkline, and subscription quota status.\n\nDesigned to be polled by the browser extension popup (every 5 minutes)\nand embedded in customer-facing portals without a separate BI tool.", "operationId": "tenant_impact_tenant_impact_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Lookback window in days (1–90)", "default": 30, "title": "Period" }, "description": "Lookback window in days (1–90)" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Tenant Impact Tenant Impact Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/syndicates/register": { "post": { "tags": [ "Syndicates" ], "summary": "Register Syndicate", "description": "Register this gateway as a named Syndicate node.\n\nGenerates a long-term X25519 identity key pair for the tenant.\nThe public key is stored in Postgres; the private key is stored in Redis\nunder warden:syndicate:identity:priv:{tenant_id} (persistent, no TTL).\n\nOne syndicate per tenant — calling again updates display_name only.", "operationId": "register_syndicate_syndicates_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterSyndicateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterSyndicateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tunnels/handshake/init": { "post": { "tags": [ "Syndicates" ], "summary": "Handshake Init", "description": "Platform A initiates a tunnel handshake.\n\nGenerates an ephemeral X25519 key pair. The private key is stored in\nRedis for 10 minutes — if Platform B doesn't respond within that window,\nthe handshake expires and a new one must be initiated.\n\nReturns a HandshakeManifest that the admin sends to Platform B out-of-band\n(email, Slack, etc.). Platform B feeds it into POST /tunnels/handshake/accept.", "operationId": "handshake_init_tunnels_handshake_init_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandshakeInitRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandshakeManifest" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tunnels/handshake/accept": { "post": { "tags": [ "Syndicates" ], "summary": "Handshake Accept", "description": "Platform B accepts the manifest and completes its side of the ECDH exchange.\n\nGenerates Platform B's ephemeral key pair, derives the shared AES-256 key,\nand stores it in Redis with the tunnel TTL. Returns Platform B's public key\nand the Safety Number to the admin, who relays both to Platform A's admin.", "operationId": "handshake_accept_tunnels_handshake_accept_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandshakeAcceptRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandshakeAcceptResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tunnels/handshake/complete": { "post": { "tags": [ "Syndicates" ], "summary": "Handshake Complete", "description": "Platform A finalises the tunnel.\n\nRetrieves Platform A's ephemeral private key from Redis, performs ECDH\nwith Platform B's public key, derives the same shared AES-256 key,\nverifies the Safety Number, and marks the tunnel ACTIVE.", "operationId": "handshake_complete_tunnels_handshake_complete_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandshakeCompleteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandshakeCompleteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tunnels/{tunnel_id}": { "delete": { "tags": [ "Syndicates" ], "summary": "Revoke Tunnel", "description": "Instantly revoke a tunnel (crypto-shredding).\n\nDeletes the AES key from Redis — all in-flight packets become undecipherable.\nMarks the link REVOKED in Postgres for audit trail.", "operationId": "revoke_tunnel_tunnels__tunnel_id__delete", "parameters": [ { "name": "tunnel_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Tunnel Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tunnels": { "get": { "tags": [ "Syndicates" ], "summary": "List Tunnels", "description": "List all tunnel links for the calling tenant's syndicate.", "operationId": "list_tunnels_tunnels_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/tunnels/transmit": { "post": { "tags": [ "Syndicates" ], "summary": "Transmit Document", "description": "Sanitise, mask, encrypt, and transmit a document through an active tunnel.\n\nSecurity pipeline (Sanitize-at-Source):\n 1. Quota check — rejects if monthly bandwidth exceeded (hard block mode)\n 2. WormGuard — blocks AI-worm / RAG-poisoning payloads before they leave\n 3. PII Masking — replaces PII tokens; original values stay on this gateway\n 4. AES-256-GCM — encrypts masked text with the tunnel's shared key\n 5. Delivery — auto-POSTs to peer_endpoint if provided\n\nThe returned session_id must be kept by the caller to unmask the response\nfrom Platform B via POST /tunnels/unmask.", "operationId": "transmit_document_tunnels_transmit_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransmitRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransmitResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tunnels/receive": { "post": { "tags": [ "Syndicates" ], "summary": "Receive Document", "description": "Receive, decrypt, and WormGuard-scan an incoming tunnel payload.\n\nCalled by the peer gateway (or directly by Platform A in loopback tests).\nApplies the receiver-side WormGuard scan — if a worm is detected the tunnel\nis immediately revoked (crypto-shredded) and HTTP 403 is returned.", "operationId": "receive_document_tunnels_receive_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiveRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiveResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tunnels/{tunnel_id}/unmask": { "post": { "tags": [ "Syndicates" ], "summary": "Unmask Tunnel Response", "description": "Reverse PII tokens in a response received from the peer gateway.\n\nBody: {\"session_id\": \"...\", \"response_text\": \"...\"}\nReturns: {\"unmasked_text\": \"...\"}\n\nThe session_id was returned by POST /tunnels/transmit.", "operationId": "unmask_tunnel_response_tunnels__tunnel_id__unmask_post", "parameters": [ { "name": "tunnel_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Tunnel Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/invites/user/generate": { "post": { "tags": [ "Syndicates" ], "summary": "Generate User Invite", "description": "Generate a Magic Link JWT for a single external user or consultant.\n\nThe link has the form:\n {PORTAL_URL}/syndicate/join?token=\n\nThe JWT payload contains:\n sub : invite_code (UUID)\n type : \"user_invite\"\n creator : syndicate_id of this gateway\n role : access role on this syndicate\n group : optional access group\n exp : Unix timestamp\n\nThe invited person opens the link, authenticates with OIDC (Google / MS),\nand their email + Warden ID are registered via POST /invites/user/accept.", "operationId": "generate_user_invite_invites_user_generate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInviteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/invites/user/accept": { "post": { "tags": [ "Syndicates" ], "summary": "Accept User Invite", "description": "Accept a Magic Link and register the user as a Syndicate member.\n\nThe caller must have already verified the user's identity via OIDC\nand supply their email. This endpoint:\n 1. Validates the invite JWT (signature + expiry)\n 2. Marks the invite as used (one-time enforcement)\n 3. Checks email restriction if set\n 4. Creates a WID (Warden ID) — anonymous external identifier\n 5. Inserts the syndicate_members row\n\nThe WID is returned so the frontend can display it and the user\ncan share it with the syndicate admin for group assignments.", "operationId": "accept_user_invite_invites_user_accept_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAcceptRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAcceptResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/invites/platform/init": { "post": { "tags": [ "Syndicates" ], "summary": "Platform Invite Init", "description": "Generate a Warden Platform Manifest for B2B gateway federation.\n\nThe manifest is a signed JSON document containing:\n - This gateway's SID and ephemeral X25519 public key\n - A one-time HMAC challenge (prevents replay)\n - The nexus_endpoint URL for Platform B to POST back to\n - TTL and permission grants\n\nAdmin workflow:\n 1. Platform A admin calls this endpoint\n 2. Downloads the manifest JSON\n 3. Sends it to Platform B admin (email / Slack / secure channel)\n 4. Platform B admin imports it via POST /invites/platform/join\n 5. Tunnel activates automatically — both admins verify Safety Numbers\n\nThe ephemeral private key is stored in Redis for 10 minutes (handshake window).\nIf Platform B doesn't respond within that window, a new manifest must be generated.", "operationId": "platform_invite_init_invites_platform_init_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformManifest" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/invites/platform/join": { "post": { "tags": [ "Syndicates" ], "summary": "Platform Invite Join", "description": "Platform B imports a Warden Manifest and activates the tunnel automatically.\n\nSteps performed:\n 1. Verify HMAC one-time code (replay prevention)\n 2. Mark invite as used\n 3. Auto-register Platform B as a Syndicate node if needed\n 4. Generate Platform B's ephemeral X25519 key pair\n 5. ECDH: derive shared AES-256 key from B's private + A's public key\n 6. Store AES key in Redis with TTL\n 7. POST responder_pub_key back to A's nexus_endpoint\n 8. A derives the same key and marks tunnel ACTIVE\n 9. Return Safety Number — both admins verify out-of-band\n\nBoth admins must confirm the Safety Number matches before trusting the tunnel.", "operationId": "platform_invite_join_invites_platform_join_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformJoinRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformJoinResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/invites": { "get": { "tags": [ "Syndicates" ], "summary": "List Invites", "description": "List all invites created by the calling tenant's syndicate.", "operationId": "list_invites_invites_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/communities": { "get": { "tags": [ "Communities" ], "summary": "List Communities Endpoint", "description": "List all communities for the authenticated tenant.", "operationId": "list_communities_endpoint_communities_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CommunityResponse" }, "type": "array", "title": "Response List Communities Endpoint Communities Get" } } } } } }, "post": { "tags": [ "Communities" ], "summary": "Create Community Endpoint", "description": "Create a new community (Business+ tier required).\n\nStep 3 security.post_quantum_cryptography=true requires Enterprise tier\nand pqc_enabled feature gate — backend enforces this regardless of frontend state.", "operationId": "create_community_endpoint_communities_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommunityRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}": { "get": { "tags": [ "Communities" ], "summary": "Get Community Endpoint", "description": "Retrieve community profile with member count and active kid.", "operationId": "get_community_endpoint_communities__community_id__get", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Community Endpoint Communities Community Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Community Hub" ], "summary": "Patch community name / description", "operationId": "patch_community_communities__community_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchCommunityIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Community Hub" ], "summary": "Delete community", "operationId": "delete_community_communities__community_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}/members": { "post": { "tags": [ "Communities" ], "summary": "Invite Member Endpoint", "description": "Invite a member to a community (generates scoped Member_ID).", "operationId": "invite_member_endpoint_communities__community_id__members_post", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Communities" ], "summary": "List Members Endpoint", "description": "List active members of a community.", "operationId": "list_members_endpoint_communities__community_id__members_get", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MemberResponse" }, "title": "Response List Members Endpoint Communities Community Id Members Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}/members/{member_id}/clearance": { "patch": { "tags": [ "Communities" ], "summary": "Update Clearance Endpoint", "description": "Update a member's clearance level.\n\nReturns {member, rotation_required}. When rotation_required=true the\ncaller should POST /communities/{id}/rotate to prevent the demoted member\nfrom using cached Clearance Level Keys.", "operationId": "update_clearance_endpoint_communities__community_id__members__member_id__clearance_patch", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Member Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClearanceRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Clearance Endpoint Communities Community Id Members Member Id Clearance Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}/members/{member_id}": { "delete": { "tags": [ "Communities" ], "summary": "Remove Member Endpoint", "description": "Soft-remove a member from the community.", "operationId": "remove_member_endpoint_communities__community_id__members__member_id__delete", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Member Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Community Hub" ], "summary": "Update member role", "operationId": "update_member_role_communities__community_id__members__member_id__put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Member Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}/rotate": { "post": { "tags": [ "Communities" ], "summary": "Initiate Rotation Endpoint", "description": "Initiate Root Key Rollover for this community.\n\nGenerates a new keypair (kid increments), demotes the current ACTIVE key\nto ROTATION_ONLY, and enqueues the ARQ background worker to re-wrap all\nentity CEKs.\n\nReturns {old_kid, new_kid, status}.", "operationId": "initiate_rotation_endpoint_communities__community_id__rotate_post", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Initiate Rotation Endpoint Communities Community Id Rotate Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}/entities": { "post": { "tags": [ "Communities" ], "summary": "Upload Entity Endpoint", "description": "Encrypt and store an entity in the community vault.", "operationId": "upload_entity_endpoint_communities__community_id__entities_post", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadEntityRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityMetaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Communities" ], "summary": "List Entities Endpoint", "description": "List encrypted entities in a community (metadata only, no payload).", "operationId": "list_entities_endpoint_communities__community_id__entities_get", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } }, { "name": "clearance_filter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clearance Filter" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityMetaResponse" }, "title": "Response List Entities Endpoint Communities Community Id Entities Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}/entities/{entity_id}": { "get": { "tags": [ "Communities" ], "summary": "Get Entity Endpoint", "description": "Get entity metadata and a 1-hour pre-signed download URL.", "operationId": "get_entity_endpoint_communities__community_id__entities__entity_id__get", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Entity Endpoint Communities Community Id Entities Entity Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Communities" ], "summary": "Delete Entity Endpoint", "description": "Crypto-shred and permanently delete an entity.", "operationId": "delete_entity_endpoint_communities__community_id__entities__entity_id__delete", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}/break-glass": { "post": { "tags": [ "Communities" ], "summary": "Initiate Break Glass Endpoint", "description": "Initiate a Break Glass emergency access procedure (MCP tier only).\n\nReturns a BreakGlassRequest dict with request_id for co-signers.\nRequires M-of-N signatures (default 3) before activation.", "operationId": "initiate_break_glass_endpoint_communities__community_id__break_glass_post", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateBreakGlassRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Initiate Break Glass Endpoint Communities Community Id Break Glass Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/break-glass/{request_id}/sign": { "post": { "tags": [ "Communities" ], "summary": "Sign Break Glass Endpoint", "description": "Add a co-signer's approval to a Break Glass request.\n\nReturns {status, sigs, required}.", "operationId": "sign_break_glass_endpoint_communities_break_glass__request_id__sign_post", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignBreakGlassRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Sign Break Glass Endpoint Communities Break Glass Request Id Sign Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/break-glass/{request_id}/activate": { "post": { "tags": [ "Communities" ], "summary": "Activate Break Glass Endpoint", "description": "Activate the Break Glass session after M signatures are collected.\n\nReturns {status, kid, community_id}. The keypair is accessible\nfor BREAK_GLASS_TTL_S seconds (default 3600); it is auto-closed after.", "operationId": "activate_break_glass_endpoint_communities_break_glass__request_id__activate_post", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Activate Break Glass Endpoint Communities Break Glass Request Id Activate Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/break-glass/{request_id}": { "delete": { "tags": [ "Communities" ], "summary": "Close Break Glass Endpoint", "description": "Manually close a Break Glass session before TTL expires.", "operationId": "close_break_glass_endpoint_communities_break_glass__request_id__delete", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}/upgrade-pqc": { "post": { "tags": [ "Communities" ], "summary": "Upgrade Pqc Endpoint", "description": "Upgrade the active community keypair to hybrid Post-Quantum Cryptography.\n\nGenerates fresh ML-DSA-65 (FIPS 204) + ML-KEM-768 (FIPS 203) keys\nalongside the existing Ed25519/X25519 keys and stores the new hybrid\nkeypair as the active entry. The kid gains the suffix \"-hybrid\"\n(e.g. \"v1\" → \"v1-hybrid\").\n\nEnterprise tier only. Requires liboqs-python on the server.\n\nReturns:\n kid New hybrid kid\n algorithm \"Ed25519+ML-DSA-65 / X25519+ML-KEM-768\"\n mldsa_pub_b64 ML-DSA-65 public key (Base64)\n mlkem_pub_b64 ML-KEM-768 public key (Base64)\n hybrid_safety_number 20-hex-char fingerprint over all 4 public keys", "operationId": "upgrade_pqc_endpoint_communities__community_id__upgrade_pqc_post", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Upgrade Pqc Endpoint Communities Community Id Upgrade Pqc Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/communities/{community_id}/rotation": { "get": { "tags": [ "Communities" ], "summary": "Rotation Progress Endpoint", "description": "Query the current Root Key Rollover progress (if any).", "operationId": "rotation_progress_endpoint_communities__community_id__rotation_get", "parameters": [ { "name": "community_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Community Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Rotation Progress Endpoint Communities Community Id Rotation Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/tiers": { "get": { "tags": [ "billing" ], "summary": "Tier catalog — all plans with features and pricing", "description": "Returns the full feature matrix for all 4 plan tiers.\nNo authentication required — used by the landing page pricing section.", "operationId": "get_billing_tiers_billing_tiers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/billing/status": { "get": { "tags": [ "billing" ], "summary": "Current subscription plan and billing details for a tenant", "operationId": "get_billing_status_billing_status_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/quota": { "get": { "tags": [ "billing" ], "summary": "Current monthly request usage for a tenant", "operationId": "get_billing_quota_billing_quota_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/margin": { "get": { "tags": [ "billing" ], "summary": "Revenue vs. LLM cost for a tenant this month", "description": "Gross margin of one tenant: plan price minus month-to-date inference spend,\nplus how much of the tier's LLM allowance is left. Answers \"is this customer\nprofitable?\" — the question no endpoint could answer before FM-7.\n\nInfrastructure is deliberately excluded: it is a shared fixed cost, not a\nper-tenant COGS, and mixing the two hides which customers are actually\nexpensive to serve.", "operationId": "get_billing_margin_billing_margin_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/enterprise/quote": { "post": { "tags": [ "billing" ], "summary": "[Admin] Quote — and optionally invoice — an Enterprise agreement", "description": "Price an Enterprise deal from the canonical list, and optionally raise a\nStripe invoice for it.\n\nEnterprise has no self-serve checkout by design: it is a procurement\nprocess — company-addressed invoice, PO number, net terms, bank transfer —\nwhich a merchant-of-record checkout structurally cannot produce. This\nendpoint is the sales-side equivalent, so the number in a quote comes from\n`warden.billing.pricing` rather than from whatever was typed into an email.\n\nAdmin-gated: it prices a deal and can create a real invoice.\n`raise_invoice=false` (the default) quotes only.", "operationId": "enterprise_quote_billing_enterprise_quote_post", "parameters": [ { "name": "x-admin-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Admin-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseQuoteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/upgrade": { "get": { "tags": [ "billing" ], "summary": "Redirect to Lemon Squeezy checkout for plan upgrade", "operationId": "billing_upgrade_billing_upgrade_get", "parameters": [ { "name": "plan", "in": "query", "required": true, "schema": { "type": "string", "description": "Target plan: trial|individual|community_business|pro|enterprise", "title": "Plan" }, "description": "Target plan: trial|individual|community_business|pro|enterprise" }, { "name": "customer_email", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Email" } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Marketplace DID — bound to subscription for M2M billing", "title": "Agent Id" }, "description": "Marketplace DID — bound to subscription for M2M billing" }, { "name": "success_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Success Url" } }, { "name": "cancel_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancel Url" } }, { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "303": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/addons": { "get": { "tags": [ "billing" ], "summary": "Add-on SKU catalog", "description": "Return all purchasable add-on SKUs with display names, prices, and minimum tiers.\nNo authentication required — used by pricing pages and upgrade flows.", "operationId": "list_addons_billing_addons_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/billing/addons/tenant": { "get": { "tags": [ "billing" ], "summary": "List add-ons purchased by a tenant", "description": "Return the set of active add-on keys for the requesting tenant.", "operationId": "get_tenant_addons_billing_addons_tenant_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/addons/{addon_key}/checkout": { "get": { "tags": [ "billing" ], "summary": "Redirect to Lemon Squeezy checkout for an add-on", "operationId": "addon_checkout_billing_addons__addon_key__checkout_get", "parameters": [ { "name": "addon_key", "in": "path", "required": true, "schema": { "type": "string", "title": "Addon Key" } }, { "name": "success_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Success Url" } }, { "name": "cancel_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancel Url" } }, { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "303": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/addons/grant": { "post": { "tags": [ "billing" ], "summary": "[Admin] Grant an add-on to a tenant", "description": "Called by the Lemon Squeezy subscription webhook on successful payment.\nRequires X-Admin-Key header.", "operationId": "admin_grant_addon_billing_addons_grant_post", "parameters": [ { "name": "x-admin-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Admin-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddonGrantRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/addons/revoke": { "delete": { "tags": [ "billing" ], "summary": "[Admin] Revoke an add-on from a tenant", "description": "Called by the Lemon Squeezy subscription webhook on cancellation.\nRequires X-Admin-Key header.", "operationId": "admin_revoke_addon_billing_addons_revoke_delete", "parameters": [ { "name": "x-admin-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Admin-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddonGrantRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/trial/start": { "post": { "tags": [ "billing" ], "summary": "Activate 14-day Pro trial (Individual+ tenants only, one-time)", "description": "Activates a 14-day Pro trial capped at 10 000 requests.\nMasterAgent is excluded from the trial.\nOne-time per tenant — raises 409 if already used.", "operationId": "start_trial_billing_trial_start_post", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialStartRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/trial/status": { "get": { "tags": [ "billing" ], "summary": "Get current trial status for a tenant", "operationId": "trial_status_billing_trial_status_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/addons/bundles": { "get": { "tags": [ "billing" ], "summary": "Bundle catalog — discounted add-on packs", "description": "Return all available bundle SKUs with savings information.", "operationId": "list_bundles_billing_addons_bundles_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/billing/addons/bundle/{bundle_key}/checkout": { "get": { "tags": [ "billing" ], "summary": "Redirect to Lemon Squeezy checkout for a bundle", "operationId": "bundle_checkout_billing_addons_bundle__bundle_key__checkout_get", "parameters": [ { "name": "bundle_key", "in": "path", "required": true, "schema": { "type": "string", "title": "Bundle Key" } }, { "name": "success_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Success Url" } }, { "name": "cancel_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancel Url" } }, { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "303": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/community-seats/add": { "post": { "tags": [ "billing" ], "summary": "[Admin] Add community seat expansion units to a tenant", "description": "Called by Lemon Squeezy webhook on community_seats purchase.\nEach unit adds 5 member slots. Stackable — purchase multiple times.", "operationId": "add_community_seats_billing_community_seats_add_post", "parameters": [ { "name": "x-admin-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Admin-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatGrantRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/community-seats": { "get": { "tags": [ "billing" ], "summary": "Get extra community member seats for a tenant", "operationId": "get_community_seats_billing_community_seats_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/referral/generate": { "post": { "tags": [ "billing" ], "summary": "Generate a referral code for the requesting tenant", "operationId": "generate_referral_billing_referral_generate_post", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/referral/redeem": { "post": { "tags": [ "billing" ], "summary": "Redeem a referral code for a new tenant", "operationId": "redeem_referral_billing_referral_redeem_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemReferralRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/referral/stats": { "get": { "tags": [ "billing" ], "summary": "Referral statistics for a tenant", "operationId": "get_referral_stats_billing_referral_stats_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/overage/preview": { "get": { "tags": [ "billing" ], "summary": "Preview overage charges for the current billing period (BL-19)", "description": "Returns the projected overage charge for the current period.\nUsed by the dashboard billing widget and the ARQ overage cron.", "operationId": "overage_preview_billing_overage_preview_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Overage Preview Billing Overage Preview Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/overage/record": { "post": { "tags": [ "billing" ], "summary": "[Admin] Record and charge overage for a tenant (BL-19)", "description": "Called by the ARQ overage cron `sova_overage_billing` at month end.", "operationId": "record_overage_billing_overage_record_post", "parameters": [ { "name": "x-admin-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Admin-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Record Overage Billing Overage Record Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/monitors/": { "get": { "tags": [ "uptime" ], "summary": "List Monitors", "operationId": "list_monitors_monitors__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Response List Monitors Monitors Get" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "uptime" ], "summary": "Create Monitor", "operationId": "create_monitor_monitors__post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Create Monitor Monitors Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/monitors/error-budget": { "get": { "tags": [ "uptime" ], "summary": "Error Budget Report", "description": "SLA error-budget report across all of the tenant's monitors (FM-5).\n\nUptime comes from the ``probe_hourly`` continuous aggregate over\n``window_days``; each monitor's budget is scored against the ``tier`` SLA\ntarget (docs/sla.md §2). ``burn_1h`` is the instantaneous burn rate over the\nlast hour — >1 means the budget is draining faster than sustainable. All\nscoring is delegated to the pure ``warden.reliability`` math.\n\nRegistered before ``/{monitor_id}`` so the literal path isn't captured as an id.", "operationId": "error_budget_report_monitors_error_budget_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "window_days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "title": "Window Days" } }, { "name": "tier", "in": "query", "required": false, "schema": { "type": "string", "default": "pro", "title": "Tier" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Error Budget Report Monitors Error Budget Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/monitors/{monitor_id}": { "get": { "tags": [ "uptime" ], "summary": "Get Monitor", "operationId": "get_monitor_monitors__monitor_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Monitor Monitors Monitor Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "uptime" ], "summary": "Patch Monitor", "operationId": "patch_monitor_monitors__monitor_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorPatch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Patch Monitor Monitors Monitor Id Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "uptime" ], "summary": "Delete Monitor", "operationId": "delete_monitor_monitors__monitor_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/monitors/{monitor_id}/status": { "get": { "tags": [ "uptime" ], "summary": "Monitor Status", "description": "Latest probe result.", "operationId": "monitor_status_monitors__monitor_id__status_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Monitor Status Monitors Monitor Id Status Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/monitors/{monitor_id}/uptime": { "get": { "tags": [ "uptime" ], "summary": "Monitor Uptime", "description": "Uptime % and average latency from continuous aggregate.", "operationId": "monitor_uptime_monitors__monitor_id__uptime_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "default": 24, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Monitor Uptime Monitors Monitor Id Uptime Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/monitors/{monitor_id}/history": { "get": { "tags": [ "uptime" ], "summary": "Monitor History", "description": "Recent probe results (raw, newest first).", "operationId": "monitor_history_monitors__monitor_id__history_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response Monitor History Monitors Monitor Id History Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/sova": { "post": { "tags": [ "SOVA Agent" ], "summary": "Query SOVA agent", "description": "Send a natural-language query or command to SOVA.\n\nSOVA will use its tool suite (27 Shadow Warden API calls) to gather\ndata, reason over it, and return an actionable response.\n\nSupports multi-turn conversations via `session_id`.\n\nExample queries:\n- \"Which communities need key rotation?\"\n- \"What's our ROI for the default tenant this month?\"\n- \"Are there any new critical CVEs affecting our dependencies?\"\n- \"Give me a morning brief\"\n- \"Check SLA compliance for all monitors\"", "operationId": "query_sova_agent_sova_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SovaRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SovaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/agent/sova/stream": { "post": { "tags": [ "SOVA Agent" ], "summary": "Query SOVA agent (streaming SSE)", "description": "Streaming variant of ``POST /agent/sova``. Returns a Server-Sent Events\nstream of the agent loop: routing status, live answer tokens, tool-use /\ntool-result events, and a final ``done`` event carrying the same metadata\n(tokens, cost, latency, tools_used) that the non-streaming endpoint returns.\n\nEach SSE frame is ``data: \\n\\n`` where ```` is one event dict.", "operationId": "query_sova_stream_agent_sova_stream_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SovaRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/agent/sova/{session_id}": { "delete": { "tags": [ "SOVA Agent" ], "summary": "Clear SOVA conversation history", "operationId": "clear_session_agent_sova__session_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/sova/task/{job}": { "post": { "tags": [ "SOVA Agent" ], "summary": "Manually trigger a SOVA scheduled task", "description": "Manually trigger one of SOVA's scheduled tasks without waiting for cron.\n\nAvailable jobs:\n- `morning-brief` — full daily operations brief → Slack\n- `threat-sync` — refresh CVE + ArXiv, alert on critical findings\n- `rotation-check` — audit all community key ages, auto-rotate if overdue\n- `sla-report` — 7-day SLA compliance report → Slack\n- `upgrade-scan` — identify tenants near quota limit\n- `corpus-watchdog` — check circuit breaker + bypass rate", "operationId": "trigger_task_agent_sova_task__job__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "job", "in": "path", "required": true, "schema": { "type": "string", "title": "Job" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/master": { "post": { "tags": [ "SOVA Agent" ], "summary": "Run MasterAgent (multi-agent SOC coordination)", "description": "Dispatch a high-level task to MasterAgent.\n\nMasterAgent decomposes the task, spawns specialist sub-agents in parallel\n(SOVAOperator, ThreatHunter, ForensicsAgent, ComplianceAgent), then\nsynthesizes a unified executive report.\n\nHigh-impact actions (key rotation, agent revocation, config changes) are\npaused for human approval — `approval_tokens` lists pending tokens.\nResolve them via `POST /agent/approve/{token}?action=approve|reject`.\n\nExample tasks:\n- \"Full SOC morning brief — health, threats, SLA, and rotation status\"\n- \"Investigate why tenant acme-corp had 400% request spike at 03:00 UTC\"\n- \"Check compliance posture for our Q2 SOC 2 audit\"", "operationId": "run_master_agent_agent_master_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasterRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasterResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/agent/approve/{token}": { "post": { "tags": [ "SOVA Agent" ], "summary": "Approve or reject a pending MasterAgent high-impact action", "description": "Resolve a human-in-the-loop approval gate.\n\nThe token is issued by MasterAgent when a sub-agent requests a\nhigh-impact operation (key rotation, agent revocation, etc.).\nValid for 1 hour from issuance.\n\n`action=approve` — allows the operation to proceed.\n`action=reject` — cancels the operation and logs the refusal.", "operationId": "approve_action_agent_approve__token__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "title": "Token" } }, { "name": "action", "in": "query", "required": true, "schema": { "enum": [ "approve", "reject" ], "type": "string", "description": "approve or reject", "title": "Action" }, "description": "approve or reject" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "SOVA Agent" ], "summary": "Check pending approval status", "description": "Return the current state of a pending approval token.", "operationId": "get_approval_agent_approve__token__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/sova/community/lookup": { "post": { "tags": [ "SOVA Agent" ], "summary": "Search community threat feed and get mitigation recommendations", "description": "Search the SEP community feed for threat signatures and retrieve\nactionable recommendations from the community knowledge base.\n\nOptionally publishes the lookup as a new community entry so other\ntenants benefit from the intelligence (`auto_publish=true`).\n\nExample:\n```json\n{ \"query\": \"new jailbreak\", \"auto_publish\": false }\n```", "operationId": "community_lookup_agent_sova_community_lookup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityLookupRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityLookupResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/agent/sova/community/apply/{ueciid}": { "post": { "tags": [ "SOVA Agent" ], "summary": "Apply a community recommendation to local filter corpus", "description": "Fetch a published community UECIID and synthesise its indicator into the\nlocal SemanticGuard corpus via EvolutionEngine.add_examples().\n\nHigh-impact: the call is wrapped in a human-in-the-loop gate — an approval\ntoken is returned. Resolve it via `POST /agent/approve/{token}?action=approve`\nbefore the examples are actually committed.\n\nReturns immediately with `status=pending` if approval required, or\n`status=applied` if `auto_approve=true` env is set (admin use only).", "operationId": "apply_community_recommendation_agent_sova_community_apply__ueciid__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "ueciid", "in": "path", "required": true, "schema": { "type": "string", "title": "Ueciid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyRecommendationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/misp/sync": { "post": { "tags": [ "SOVA Agent" ], "summary": "Trigger MISP threat feed sync", "description": "Pull events from the configured MISP instance and synthesise them into the\nlocal SemanticGuard corpus via EvolutionEngine.\n\nRequires `MISP_URL` and `MISP_API_KEY` env vars.", "operationId": "misp_sync_agent_misp_sync_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Misp Sync Agent Misp Sync Post" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/shadow-ai/scan": { "post": { "tags": [ "Shadow AI Governance" ], "summary": "Scan subnet for Shadow AI endpoints", "description": "Probe a subnet (CIDR /24 or smaller) for unauthorized AI API endpoints.\n\nSends async HTTP probes to all hosts on common AI ports (80, 443, 8080,\n11434, 5000, 7860 …) and fingerprints responses against the AI provider\ndatabase (OpenAI, Ollama, Gradio, LocalAI, etc.).\n\nOmit `subnet` to get a report of DNS-telemetry findings only (no probing).", "operationId": "scan_subnet_shadow_ai_scan_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/shadow-ai/dns-event": { "post": { "tags": [ "Shadow AI Governance" ], "summary": "Ingest a DNS telemetry event", "description": "Classify a single DNS query against the AI provider domain list.\n\nIntegrate with your DNS RPZ, Zeek, Suricata, or syslog forwarder to\nstream DNS events into the Shadow AI Governance engine.\n\nReturns:\n `{\"match\": true, ...finding}` — recognized AI provider domain.\n `{\"match\": false, \"domain\": \"...\"}` — not an AI domain.", "operationId": "ingest_dns_event_shadow_ai_dns_event_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsEventRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Ingest Dns Event Shadow Ai Dns Event Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/shadow-ai/findings": { "get": { "tags": [ "Shadow AI Governance" ], "summary": "List Shadow AI findings", "description": "Return stored Shadow AI findings (most recent first).\n\nIncludes findings from both network probes and DNS telemetry.\nCapped at 1 000 per tenant; use `limit` to reduce the response size.", "operationId": "list_findings_shadow_ai_findings_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Tenant Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "title": "Response List Findings Shadow Ai Findings Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Shadow AI Governance" ], "summary": "Clear all findings for a tenant", "description": "Permanently delete all stored Shadow AI findings for this tenant.", "operationId": "clear_findings_endpoint_shadow_ai_findings_delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Tenant Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shadow-ai/report": { "get": { "tags": [ "Shadow AI Governance" ], "summary": "Shadow AI governance summary report", "description": "Generate a Shadow AI Governance summary for a tenant.\n\nAggregates findings to produce risk distribution, verdict breakdown,\nand top-5 most-frequently detected providers.\n\nUse this endpoint for dashboard widgets, compliance reports, or\nSOVA's morning brief query.", "operationId": "governance_report_shadow_ai_report_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Tenant Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 1000, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovernanceReport" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shadow-ai/policy": { "get": { "tags": [ "Shadow AI Governance" ], "summary": "Get Shadow AI governance policy", "description": "Return the current governance policy for a tenant.", "operationId": "get_policy_endpoint_shadow_ai_policy_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Policy Endpoint Shadow Ai Policy Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Shadow AI Governance" ], "summary": "Update Shadow AI governance policy", "description": "Update the governance policy for a tenant.\n\nUnset fields are left unchanged (partial update / patch semantics).\n\nMode options:\n- `MONITOR` — report only, no enforcement\n- `BLOCK_DENYLIST` — block providers on the denylist\n- `ALLOWLIST_ONLY` — flag anything not explicitly on the allowlist", "operationId": "update_policy_endpoint_shadow_ai_policy_put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Tenant Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/warden__api__shadow_ai__PolicyRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Policy Endpoint Shadow Ai Policy Put" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shadow-ai/providers": { "get": { "tags": [ "Shadow AI Governance" ], "summary": "List all known AI provider signatures", "description": "Return the full AI provider signature database.\n\nUseful for building allowlist/denylist pickers in the governance UI\nand for verifying which providers Shadow Warden can detect.", "operationId": "list_providers_shadow_ai_providers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Response List Providers Shadow Ai Providers Get" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/gsam/lease": { "post": { "tags": [ "GSAM" ], "summary": "Issue", "operationId": "issue_gsam_lease_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Issue Gsam Lease Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/gsam/lease/{lease_id}/redeem": { "post": { "tags": [ "GSAM" ], "summary": "Redeem", "operationId": "redeem_gsam_lease__lease_id__redeem_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "lease_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Lease Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Redeem Gsam Lease Lease Id Redeem Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/gsam/lease/{lease_id}": { "delete": { "tags": [ "GSAM" ], "summary": "Revoke", "operationId": "revoke_gsam_lease__lease_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "lease_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Lease Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Revoke Gsam Lease Lease Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "GSAM" ], "summary": "Get", "operationId": "get_gsam_lease__lease_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "lease_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Lease Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Gsam Lease Lease Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/gsam/heatmap": { "get": { "tags": [ "GSAM" ], "summary": "Heatmap", "operationId": "heatmap_gsam_heatmap_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "default": 24, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Heatmap Gsam Heatmap Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/gsam/agents/{agent_id}/stats": { "get": { "tags": [ "GSAM" ], "summary": "Agent Stats", "operationId": "agent_stats_gsam_agents__agent_id__stats_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "default": 24, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Agent Stats Gsam Agents Agent Id Stats Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/gsam/compliance/score": { "get": { "tags": [ "GSAM" ], "summary": "Compliance", "operationId": "compliance_gsam_compliance_score_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "default": 168, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Compliance Gsam Compliance Score Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/gsam/health": { "get": { "tags": [ "GSAM" ], "summary": "Health", "description": "GSAM ingest health — the operator signal for the ClickHouse write path.\n\nThe collector never blocks a request when ClickHouse is down: it spools\nobservations to NDJSON and replays them on recovery. That is correct, but it\nmeans a broken OLAP store degrades *quietly*. This endpoint surfaces the signals\nthat distinguish \"healthy and draining\" from \"quietly spooling forever\":\n\n clickhouse_enabled — GSAM_CLICKHOUSE_ENABLED\n clickhouse_reachable — live ping\n spool_bytes — backlog on disk; grows while ClickHouse is unreachable\n queue_depth/dropped — in-memory backpressure\n\n``degraded`` is True when ClickHouse is enabled but unreachable, when the spool\nhas a backlog, or when observations were dropped — the condition worth alerting on.", "operationId": "health_gsam_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Health Gsam Health Get" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/wallet": { "get": { "tags": [ "SAC Wallet" ], "summary": "Wallet", "operationId": "wallet_wallet_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Wallet Wallet Get" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/wallet/deposit": { "post": { "tags": [ "SAC Wallet" ], "summary": "Deposit", "operationId": "deposit_wallet_deposit_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "x-admin-key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Admin-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Deposit Wallet Deposit Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/wallet/reserve": { "post": { "tags": [ "SAC Wallet" ], "summary": "Reserve", "operationId": "reserve_wallet_reserve_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReserveRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Reserve Wallet Reserve Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/wallet/commit": { "post": { "tags": [ "SAC Wallet" ], "summary": "Commit", "operationId": "commit_wallet_commit_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Commit Wallet Commit Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/wallet/release": { "post": { "tags": [ "SAC Wallet" ], "summary": "Release", "operationId": "release_wallet_release_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Release Wallet Release Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/misp/status": { "get": { "tags": [ "MISP" ], "summary": "MISP bridge config and live stats", "operationId": "misp_status_misp_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Misp Status Misp Status Get" } } } } } } }, "/misp/stats": { "get": { "tags": [ "MISP" ], "summary": "MISP bridge ingestion counters", "operationId": "misp_stats_misp_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Misp Stats Misp Stats Get" } } } } } } }, "/misp/sync": { "post": { "tags": [ "MISP" ], "summary": "Trigger one-shot MISP HTTP pull", "description": "Fetch recent MISP events via REST API and ingest into the threat pipeline.\nRequires MISP_API_URL and MISP_API_KEY to be configured.", "operationId": "misp_sync_misp_sync_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Misp Sync Misp Sync Post" } } } } } } }, "/sdk/status": { "get": { "tags": [ "SDK" ], "summary": "OTel SDK version and aggregate processor stats", "operationId": "sdk_status_sdk_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Sdk Status Sdk Status Get" } } } } } } }, "/sdk/stats": { "get": { "tags": [ "SDK" ], "summary": "Aggregate ingestion counters across all processors", "operationId": "sdk_stats_sdk_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Sdk Stats Sdk Stats Get" } } } } } } }, "/sdk/ping": { "post": { "tags": [ "SDK" ], "summary": "Test-fire a synthetic span through the Warden /filter endpoint", "description": "Constructs a synthetic span from the provided name + attributes and\nruns it through the Warden /filter endpoint, returning the result.\nUseful for smoke-testing SDK connectivity without a real OTel pipeline.", "operationId": "sdk_ping_sdk_ping_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Sdk Ping Sdk Ping Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/xai/explain/{request_id}": { "get": { "tags": [ "Explainable AI" ], "summary": "Get structured causal chain for a filter decision", "description": "Return the full causal chain for a specific filter decision.\n\nThe chain includes:\n- One node per pipeline stage (topology → obfuscation → secrets → semantic\n → brain → causal → phish → ERS → decision)\n- Per-stage verdict (PASS / FLAG / BLOCK / SKIP) and numeric score\n- Primary cause attribution (which stage triggered the block)\n- Counterfactual remediation suggestions\n- Plain-English rationale\n\nUse the `nodes[].color` and `nodes[].verdict` fields to drive your\nReact Flow / D3 pipeline visualizer.", "operationId": "explain_xai_explain__request_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Request Id" } }, { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "default": "default", "title": "Tenant Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Explain Xai Explain Request Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/xai/explain/batch": { "post": { "tags": [ "Explainable AI" ], "summary": "Explain multiple filter decisions", "description": "Explain up to 20 filter decisions in one call.\n\nReturns a list in the same order as `request_ids`.\nMissing / not-found IDs return `{\"found\": false, \"request_id\": \"...\"}`.", "operationId": "explain_batch_xai_explain_batch_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchExplainRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Response Explain Batch Xai Explain Batch Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/xai/report/{request_id}": { "get": { "tags": [ "Explainable AI" ], "summary": "HTML causal chain report (inline)", "description": "Render a self-contained HTML report for a filter decision.\n\nThe report includes:\n- Risk gauge and verdict banner\n- Interactive pipeline diagram (collapsible stage cards)\n- Counterfactual remediation table\n- Raw JSON payload (collapsible)\n\nOpen directly in a browser or embed in an `