{ "openapi": "3.1.0", "info": { "title": "Sanctions Desk API", "version": "1.4.0", "description": "A review desk for sanctions-screening alerts. The desk recommends; a person makes the final call (automatic closing is off by default). Nothing here blocks an account, writes to a source system or contacts a customer.\n\n## Authentication and access\n\n**Get a token.** An administrator adds each person to the users file, which is kept outside the repository and named by `DESK_USERS_FILE`:\n\n```bash\nnpm run users:add -- --file ~/.sanctions-desk/users.json --id olga --role approver --by admin --expires 90d\n```\n\nThe token (`sd_` and 32 characters, 192 random bits) is printed once; the file keeps only its SHA-256. `npm run users:rotate` issues a new token and the old one stops working; `npm run users:revoke` stops a token at once; `--expires` (for example `90d` or an ISO time) makes a token stop working at that time. A running server reads the file again when it changes, so these take effect on the next request. Every change is logged in `users-audit.jsonl` beside the file (who, when, what; never a token). A token in any other form is refused, and with sign-in on the server will not start while the file holds a token that `users:add` did not make.\n\n**When sign-in is on.** The setting is the environment variable `AUTH_MODE` (`server.auth` in the configuration files), and it defaults to `auto`. `auto` means sign-in is on in live mode and demo users in sample mode. `on` works in both modes. `demo` and `off` are refused in live mode, and in live mode without a users file (`DESK_USERS_FILE`) the server refuses to start, so the API never runs live with sign-in off.\n\n**Runs without the API.** Two things do not go through the API's sign-in, because they open no port and whoever runs them already controls the process: `npm run case` (one review, in-process) and the evaluation tools (`npm run exam` and the study and guard tools), which call the review pipeline directly.\n\n**Send it.** `Authorization: Bearer ` on every request. Every route except `/health` needs it when sign-in is on (the default outside sample mode). No token, or an unknown, malformed, expired or revoked one: `401`. A role that may not do this: `403`.\n\n```bash\nexport DESK_TOKEN=... # your token, from users:add; never put it in a file in the repository\ncurl -s https://desk.example.com/run -H \"Authorization: Bearer $DESK_TOKEN\" -H 'content-type: application/json' -d '{\"alert_id\": \"ALR-0004\"}'\n```\n\n**Roles.**\n\n| Role | What it may do |\n| --- | --- |\n| `analyst` | read everything; start a review, replay a list change, check a draft for a customer, compare a policy draft; approve or override a recommendation, give a second approval, reopen an automatic close |\n| `approver` | read everything; start a review, replay a list change, check a draft for a customer, compare a policy draft; approve or override a recommendation, give a second approval, reopen an automatic close; give the second approval of a block or of an override to a close; override towards a less cautious outcome (it then waits for a second approver); propose, reload or roll back a policy draft; stop automatic closing |\n| `policy_admin` | read everything; start a review, replay a list change, check a draft for a customer, compare a policy draft; propose, reload or roll back a policy draft; publish a policy draft; stop automatic closing; switch automatic closing back on |\n| `viewer` | read everything (read only) |\n\n**Four-eyes.** A block (an approved block recommendation, or an override to a block), and an override to a close from any other recommendation, wait for a second, different approver. In sample mode `approver_demo` and `approver2_demo` can be the two approvers. A policy draft must be published by a different person from the one who proposed it; in sample mode `admin_demo` can propose it and `admin2_demo` publish it.\n\n**Rate limits.** Per caller (the signed-in user; without sign-in, the address), in a fixed window: by default 60 changes a minute, 10 reviews a minute, and 4 reviews running at once across all callers; above a limit the answer is `429` with `Retry-After`, and nothing is queued. Reads and `/health` are not limited. The counts are kept in the memory of one server process: they reset when it restarts and are not shared between processes. Set them in `config` (`server.rateLimit`) or with `RATE_LIMIT_WRITES`, `RATE_LIMIT_REVIEWS`, `RATE_LIMIT_REVIEWS_IN_FLIGHT` and `RATE_LIMIT_WINDOW_MS`. For limits shared across several processes or machines, put a gateway or proxy with its own limits in front (for example nginx `limit_req` or an API gateway).\n\n**TLS.** With `DESK_TLS_CERT_FILE` and `DESK_TLS_KEY_FILE` set, the server serves HTTPS only. Without them it serves plain HTTP and should stay on `127.0.0.1`, as by default; it logs a warning at start-up if it is bound to any other address without TLS. For a deployment, terminate TLS in a proxy in front, for example Caddy:\n\n```\ndesk.example.com {\n reverse_proxy 127.0.0.1:8000\n}\n```\n\n**Sample mode.** With `SAMPLE_MODE=true` and sign-in not on, the built-in demo users (`analyst_demo`, `approver_demo`, `approver2_demo`, `admin_demo`, `admin2_demo`) can be chosen with the `X-Demo-User` header, and reading and running a review need no token. The demo users are ignored when sign-in is on and never work in live mode.", "license": { "name": "Apache-2.0" } }, "servers": [ { "url": "http://localhost:8000" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A token issued with `npm run users:add` (sd_ and 32 characters, 192 random bits). Send it as `Authorization: Bearer `. Every route except /health needs one when sign-in is on." } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/health": { "get": { "tags": [ "System" ], "summary": "Liveness", "description": "Public: no token needed.", "x-required-roles": "public", "security": [], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "sample_mode": { "type": "boolean" } }, "required": [] } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/health/dependencies": { "get": { "tags": [ "System" ], "summary": "Readiness of Nightshift, Ollama and Zetaris", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/alerts": { "get": { "tags": [ "Review" ], "summary": "The alert queue, read through the semantic layer, with the latest recommendation of each alert", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/run": { "post": { "tags": [ "Review" ], "summary": "Review one alert and return a recommendation for a person to act on", "description": "Roles: analyst, approver, policy_admin.\n\nIdentify the alert by alert_id. The answer carries the recommendation (decision, confidence), rationale, cited facts, the checks that ran, the model ledger and the record hash, plus the steps that ran in order (agents), the trace id and the trace file (trace_id, log_file: logs/trace-.jsonl), the time taken (execution_time_seconds) and, in sample mode, sample_mode and sample_notice. A failure has status error and a structured error. Pass a run_id of your own to follow the run on /runs/{runId}/stream while it works. `npm run case -- ` runs the same route from the command line.", "x-required-roles": [ "analyst", "approver", "policy_admin" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "run_id": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._-]+$" }, "alert_type": { "default": "customer", "type": "string", "enum": [ "customer", "payment" ] }, "alert_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "alert": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "options": { "default": {}, "type": "object", "properties": { "sample_mode": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "alert_type": { "type": "string", "enum": [ "customer", "payment" ] }, "policy_version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "decision": { "type": "string", "enum": [ "CLOSE_FALSE_POSITIVE", "ESCALATE_L2", "RECOMMEND_BLOCK", "NEED_MORE_INFO" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "rationale": { "type": "string" }, "what_would_change": { "default": [], "type": "array", "items": { "type": "string" } }, "citations": { "default": [], "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "const": "zetaris" }, "query_id": { "type": "string", "minLength": 1 }, "table": { "type": "string", "minLength": 1 }, "row_keys": { "type": "array", "items": { "type": "string" } } }, "required": [ "source", "query_id", "table", "row_keys" ], "additionalProperties": false } }, "agents": { "default": [], "type": "array", "items": { "type": "string" } }, "trace_id": { "type": "string" }, "log_file": { "type": "string" }, "execution_time_seconds": { "type": "number", "minimum": 0 }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "recoverable": { "type": "boolean" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type", "message", "recoverable" ] }, "key_evidence": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "string" } }, "path": { "type": "string", "enum": [ "confirm", "reason" ] }, "first_finding": { "type": "string", "enum": [ "CLOSE_FALSE_POSITIVE", "ESCALATE_L2", "RECOMMEND_BLOCK", "NEED_MORE_INFO" ] }, "confidence_cap": { "type": "object", "properties": { "value": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "value", "reason" ], "additionalProperties": false }, "models": { "default": [], "type": "array", "items": { "type": "object", "properties": { "agent": { "type": "string", "enum": [ "system", "triage", "evidence", "screener", "matching", "ownership", "memory", "decision", "critic", "challenger", "policy_guard", "reporter", "human" ] }, "model_requested": { "type": "string", "minLength": 1 }, "model_routed": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "route_kind": { "anyOf": [ { "type": "string", "enum": [ "local", "cloud" ] }, { "type": "null" } ] }, "app": { "type": "string", "minLength": 1 }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "tokens_in": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tokens_out": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "latency_ms": { "type": "number", "minimum": 0 }, "served_mode": { "type": "string", "minLength": 1 }, "receipt": { "type": "object", "properties": { "receipt_id": { "type": "string", "minLength": 1 }, "decision_id": { "type": "string", "minLength": 1 }, "signer": { "type": "string", "minLength": 1 }, "ts_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pubkey_b64": { "type": "string", "pattern": "^[A-Za-z0-9+/]+={0,2}$" }, "sig_b64": { "type": "string", "pattern": "^[A-Za-z0-9+/]+={0,2}$" }, "body_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "verification": { "type": "string", "enum": [ "valid_pinned", "valid_unpinned", "invalid", "malformed" ] }, "manifest_hash": { "type": "string", "minLength": 1 }, "from_cache": { "type": "boolean" } }, "required": [ "receipt_id", "pubkey_b64", "sig_b64", "body_hash", "verification" ], "additionalProperties": false }, "receipt_rejected": { "type": "string", "minLength": 1 } }, "required": [ "agent", "model_requested", "model_routed", "provider", "route_kind" ], "additionalProperties": false } }, "guards": { "default": [], "type": "array", "items": { "type": "object", "properties": { "guard": { "type": "string", "minLength": 1 }, "verdict": { "type": "string", "enum": [ "pass", "flag", "block" ] }, "detail": { "type": "string" } }, "required": [ "guard", "verdict" ], "additionalProperties": false } }, "critic": { "type": "object", "properties": { "rounds": { "type": "integer", "minimum": 0, "maximum": 3 }, "final_verdict": { "type": "string", "enum": [ "approved", "rejected", "escalated", "not_run" ] }, "not_citable": { "type": "array", "items": { "type": "object", "properties": { "table": { "type": "string", "minLength": 1 }, "column": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 }, "round": { "type": "integer", "minimum": 1, "maximum": 3 } }, "required": [ "table", "column", "reason", "round" ], "additionalProperties": false } } }, "required": [ "rounds", "final_verdict" ], "additionalProperties": false }, "record_id": { "type": "string", "minLength": 1 }, "record_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "human_review_required": { "type": "boolean" }, "autonomy": { "type": "object", "properties": { "policy_level": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 } ] }, "level_in_force": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 } ] }, "outcome": { "type": "string", "enum": [ "human_review", "auto_closed", "qa_sample" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "met": { "type": "boolean" }, "detail": { "type": "string" } }, "required": [ "name", "met" ], "additionalProperties": false } }, "qa_draw": { "type": "number", "minimum": 0, "maximum": 1 }, "qa_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "statement": { "type": "string" } }, "required": [ "policy_level", "level_in_force", "outcome", "conditions", "qa_draw", "qa_rate" ], "additionalProperties": false }, "documentary": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "const": "date_of_birth" }, "value": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "check_reference": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 } }, "required": [ "field", "value", "source", "check_reference", "label" ], "additionalProperties": false } }, "approvals_required": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "decision_model": { "type": "string", "minLength": 1 }, "decision_route": { "type": "string", "enum": [ "own", "fast", "backup" ] }, "decided_by_fallback": { "type": "boolean" }, "model_last_recommendation": { "type": "string", "enum": [ "CLOSE_FALSE_POSITIVE", "ESCALATE_L2", "RECOMMEND_BLOCK", "NEED_MORE_INFO" ] }, "critic_unresolved": { "type": "boolean" }, "sample_mode": { "type": "boolean" }, "sample_notice": { "type": "string" }, "held_reason": { "type": "string", "enum": [ "data_service_unavailable" ] } }, "required": [ "run_id", "status", "trace_id", "execution_time_seconds" ] } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/runs/{runId}/events": { "get": { "tags": [ "Review" ], "summary": "The recorded events of a run", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._-]+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/runs/{runId}/stream": { "get": { "tags": [ "Review" ], "summary": "A run's events as server-sent events, live and then recorded", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._-]+$" } } ], "responses": { "200": { "description": "A stream of server-sent events", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/runs/{runId}/trace": { "get": { "tags": [ "Review" ], "summary": "The decision trace of a run's recommendation", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._-]+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/cases/{alertId}/record": { "get": { "tags": [ "Review" ], "summary": "The sealed decision record of the latest recommendation for an alert", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/cases/{alertId}/evidence": { "get": { "tags": [ "Review" ], "summary": "The facts a case rests on, read through the evidence role (identifier numbers masked)", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/cases/{alertId}/trace": { "get": { "tags": [ "Review" ], "summary": "The four-question decision trace: definitions, data, access and cost", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" } }, { "name": "audit", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Also match each query with Zetaris's own statement history" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/me": { "get": { "tags": [ "People" ], "summary": "Who you are, what you may do, and the demo users in sample mode", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/cases/{alertId}/human": { "get": { "tags": [ "People" ], "summary": "Where a recommendation stands after people acted on it, and the records prepared from their decision", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/cases/{alertId}/actions": { "get": { "tags": [ "People" ], "summary": "The records prepared after an approval (closure note, ticket, draft, hold instruction), with their seal check", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/cases/{alertId}/decision": { "post": { "tags": [ "People" ], "summary": "Approve or override a recommendation, with a reason. A block still needs a second approval", "description": "Roles: analyst, approver. An analyst or approver decides. Only an approver may override towards a less cautious outcome. Four-eyes: a block, and an override that lowers caution (a block or an escalation changed to a close), wait for a second, different approver.", "x-required-roles": [ "analyst", "approver" ], "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approve", "override" ] }, "outcome": { "type": "string", "enum": [ "CLOSE_FALSE_POSITIVE", "ESCALATE_L2", "RECOMMEND_BLOCK", "NEED_MORE_INFO" ], "description": "Required for an override" }, "reason": { "type": "string", "minLength": 10, "maxLength": 600 }, "record_hash": { "type": "string", "description": "The hash of the recommendation you were looking at" } }, "required": [ "action", "reason", "record_hash" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/cases/{alertId}/second-approval": { "post": { "tags": [ "People" ], "summary": "The second approver confirms or declines a block, or an override to a close (status override_pending). Must be an approver and a different person", "description": "Roles: analyst, approver. Four-eyes: the second approval must come from an approver who is not the person who made the first decision.", "x-required-roles": [ "analyst", "approver" ], "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approve": { "type": "boolean" }, "reason": { "type": "string", "minLength": 10, "maxLength": 600 }, "record_hash": { "type": "string" } }, "required": [ "approve", "reason", "record_hash" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/cases/{alertId}/reopen": { "post": { "tags": [ "People" ], "summary": "Reopen a close the desk made automatically; the case then waits for a person's decision", "description": "Roles: analyst, approver.", "x-required-roles": [ "analyst", "approver" ], "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 600 }, "record_hash": { "type": "string" } }, "required": [ "reason", "record_hash" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/autonomy": { "get": { "tags": [ "People" ], "summary": "The autonomy level in force, today's automatic closes against the cap, and the kill switch", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/autonomy/kill-switch": { "post": { "tags": [ "People" ], "summary": "Force autonomy level 0 at once (an approver or policy admin); only a policy admin can switch it back on", "description": "Roles: approver, policy_admin. An approver or a policy admin can stop automatic closing; only a policy admin can switch it back on.", "x-required-roles": [ "approver", "policy_admin" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" }, "reason": { "type": "string", "minLength": 10, "maxLength": 600 } }, "required": [ "active", "reason" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/auto-closed": { "get": { "tags": [ "People" ], "summary": "Closes made automatically, for a person to review and reopen", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/cases/{alertId}/file": { "get": { "tags": [ "People" ], "summary": "The case file as Markdown or PDF: recommendation, facts, what people did, what was prepared next, models and the record hash", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "md", "pdf" ] }, "description": "md (default) or pdf" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/receipts/{receiptId}/verify": { "get": { "tags": [ "Review" ], "summary": "Check a stored signed receipt: the signature, whether the key is pinned, the app, the modes and the model that served the call", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The receipt id from the model ledger" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/list-change/replay": { "post": { "tags": [ "Review" ], "summary": "Check every earlier decision against the list as it is now", "description": "Roles: analyst, approver, policy_admin.", "x-required-roles": [ "analyst", "approver", "policy_admin" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_size": { "type": "integer" }, "max_batches": { "type": "integer" }, "cursor": { "type": "integer" } }, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/guard/outbound": { "post": { "tags": [ "Review" ], "summary": "Check a draft message for a customer; refuses anything that reveals screening or an investigation", "description": "Roles: analyst, approver, policy_admin.", "x-required-roles": [ "analyst", "approver", "policy_admin" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/exam": { "get": { "tags": [ "Evaluation" ], "summary": "The saved exam results, the headline measure and the measured routing split", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/governance": { "get": { "tags": [ "Governance" ], "summary": "The governance view: inventory, risk materiality, oversight, testing, monitoring, change control and limits", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/policy": { "get": { "tags": [ "Policy" ], "summary": "The active policy", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/policy/versions": { "get": { "tags": [ "Policy" ], "summary": "Every policy version and its status", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/policy/versions/{version}": { "get": { "tags": [ "Policy" ], "summary": "One policy version", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/policy/audit": { "get": { "tags": [ "Policy" ], "summary": "The audit log of policy changes", "description": "Any signed-in role (viewer, analyst, approver, policy_admin).", "x-required-roles": "any", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } } } } }, "/policy/drafts": { "post": { "tags": [ "Policy" ], "summary": "Propose a policy change as a draft", "description": "Roles: approver, policy_admin.\n\nValidated against the policy schema, which fixes the hard limits: no automatic block, no customer messages, read-only data.", "x-required-roles": [ "approver", "policy_admin" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "lists": { "type": "object", "properties": { "enabled": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "OFAC", "UN", "EU", "UK" ] } }, "weights": { "type": "object", "properties": { "OFAC": { "type": "number", "minimum": 0, "maximum": 1 }, "UN": { "type": "number", "minimum": 0, "maximum": 1 }, "EU": { "type": "number", "minimum": 0, "maximum": 1 }, "UK": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "OFAC", "UN", "EU", "UK" ], "additionalProperties": false } }, "required": [ "enabled", "weights" ], "additionalProperties": false }, "matching": { "type": "object", "properties": { "nameSimilarityThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "autoCloseCeiling": { "type": "number", "minimum": 0, "maximum": 1 }, "strongIdentifierFields": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "dob", "nationality", "id_number", "passport_number" ] } }, "minStrongIdentifierMatches": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "nameSimilarityThreshold", "autoCloseCeiling", "strongIdentifierFields", "minStrongIdentifierMatches" ], "additionalProperties": false }, "ownership": { "type": "object", "properties": { "thresholdPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 }, "aggregate": { "type": "boolean" }, "maxChainDepth": { "type": "integer", "minimum": 1, "maximum": 10 }, "onLimitReached": { "type": "string", "const": "escalate" } }, "required": [ "thresholdPercent", "aggregate", "maxChainDepth", "onLimitReached" ], "additionalProperties": false }, "jurisdictions": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "action": { "type": "string", "enum": [ "review", "escalate", "recommend_block" ] }, "note": { "type": "string" }, "keywords": { "default": [], "type": "array", "items": { "type": "string", "minLength": 2 } } }, "required": [ "country", "action" ], "additionalProperties": false } }, "automation": { "type": "object", "properties": { "autoClose": { "type": "boolean" }, "autoEscalate": { "type": "boolean" }, "autoBlock": { "type": "boolean", "const": false }, "messageCustomers": { "type": "boolean", "const": false }, "dataAccess": { "type": "string", "const": "read_only" }, "blockApprovalsRequired": { "type": "number", "const": 2 } }, "required": [ "autoClose", "autoEscalate", "autoBlock", "messageCustomers", "dataAccess", "blockApprovalsRequired" ], "additionalProperties": false }, "critic": { "type": "object", "properties": { "maxRounds": { "type": "integer", "minimum": 1, "maximum": 3 }, "confidenceFloorForClose": { "type": "number", "minimum": 0, "maximum": 1 }, "abstainOnInvalidData": { "type": "boolean", "const": true } }, "required": [ "maxRounds", "confidenceFloorForClose", "abstainOnInvalidData" ], "additionalProperties": false }, "evidenceStandard": { "default": { "definition": "false_positive@2", "requireCheckReference": true, "requireDocumentNumber": true, "requireDate": true, "requireNamedCounterpartyForPayments": true }, "type": "object", "properties": { "definition": { "type": "string", "pattern": "^[a-z_]+@\\d+$" }, "requireCheckReference": { "type": "boolean" }, "requireDocumentNumber": { "type": "boolean" }, "requireDate": { "type": "boolean" }, "requireNamedCounterpartyForPayments": { "type": "boolean" } }, "required": [ "definition", "requireCheckReference", "requireDocumentNumber", "requireDate", "requireNamedCounterpartyForPayments" ], "additionalProperties": false }, "screener": { "default": { "enabled": true, "confidenceThreshold": 0.5, "otherConfidenceThreshold": 0.7, "signalTypes": [ "alias_or_former_name", "relationship_to_listed_party", "ownership_or_control_claim", "sanctioned_jurisdiction_link", "adverse_media", "instruction_to_reviewer", "other" ], "maxFieldChars": 4000, "grounding": { "enabled": false, "nameWindowChars": 80, "minNameTokenChars": 4, "genericNameWords": [], "terms": {}, "placeTypes": [] } }, "type": "object", "properties": { "enabled": { "default": true, "type": "boolean" }, "confidenceThreshold": { "type": "number", "minimum": 0, "maximum": 0.9 }, "otherConfidenceThreshold": { "default": 0.7, "type": "number", "minimum": 0, "maximum": 0.95 }, "signalTypes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "alias_or_former_name", "relationship_to_listed_party", "ownership_or_control_claim", "sanctioned_jurisdiction_link", "adverse_media", "instruction_to_reviewer", "other" ] } }, "maxFieldChars": { "type": "integer", "exclusiveMinimum": 0, "maximum": 20000 }, "grounding": { "default": { "enabled": false, "nameWindowChars": 80, "minNameTokenChars": 4, "genericNameWords": [], "terms": {}, "placeTypes": [] }, "type": "object", "properties": { "enabled": { "type": "boolean" }, "nameWindowChars": { "type": "integer", "minimum": 0, "maximum": 400 }, "minNameTokenChars": { "type": "integer", "minimum": 2, "maximum": 20 }, "genericNameWords": { "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "terms": { "type": "object", "propertyNames": { "type": "string", "enum": [ "alias_or_former_name", "relationship_to_listed_party", "ownership_or_control_claim", "sanctioned_jurisdiction_link", "adverse_media", "instruction_to_reviewer", "other" ] }, "additionalProperties": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "placeTypes": { "default": [], "type": "array", "items": { "type": "string", "enum": [ "alias_or_former_name", "relationship_to_listed_party", "ownership_or_control_claim", "sanctioned_jurisdiction_link", "adverse_media", "instruction_to_reviewer", "other" ] } } }, "required": [ "enabled", "nameWindowChars", "minNameTokenChars", "terms" ], "additionalProperties": false } }, "required": [ "confidenceThreshold", "signalTypes", "maxFieldChars" ], "additionalProperties": false }, "models": { "type": "object", "properties": { "triage": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false }, "evidence": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false }, "screener": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false }, "matching": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false }, "ownership": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false }, "decision": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false }, "critic": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false }, "challenger": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false }, "policy_guard": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false }, "reporter": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "fast", "deep", "judge" ] }, { "type": "string", "pattern": "^meterless\\/(?!auto$)[a-z][a-z0-9._-]*$" } ] }, "thinking": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "on" }, { "type": "object", "properties": { "budgetTokens": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "budgetTokens" ], "additionalProperties": false } ] }, "timeoutMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 600000 }, "identity": { "default": "default", "type": "string", "enum": [ "default", "reasoning", "guard" ] }, "retryIdentity": { "type": "string", "enum": [ "default", "reasoning", "guard" ] } }, "required": [ "model", "thinking", "timeoutMs" ], "additionalProperties": false } }, "required": [ "triage", "evidence", "screener", "matching", "ownership", "decision", "critic", "challenger", "policy_guard", "reporter" ], "additionalProperties": false }, "masking": { "type": "object", "properties": { "triage": { "type": "string", "minLength": 1 }, "evidence": { "type": "string", "minLength": 1 }, "screener": { "type": "string", "minLength": 1 }, "matching": { "type": "string", "minLength": 1 }, "ownership": { "type": "string", "minLength": 1 }, "decision": { "type": "string", "minLength": 1 }, "critic": { "type": "string", "minLength": 1 }, "challenger": { "type": "string", "minLength": 1 }, "policy_guard": { "type": "string", "minLength": 1 }, "reporter": { "type": "string", "minLength": 1 } }, "required": [ "triage", "evidence", "screener", "matching", "ownership", "decision", "critic", "challenger", "policy_guard", "reporter" ], "additionalProperties": false }, "challenger": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "confidenceBelow": { "type": "number", "minimum": 0, "maximum": 1 }, "nameScoreAtLeast": { "type": "number", "minimum": 0, "maximum": 1 }, "onDataQualityIssue": { "type": "boolean" } }, "required": [ "enabled", "confidenceBelow", "nameScoreAtLeast", "onDataQualityIssue" ], "additionalProperties": false }, "autonomy": { "default": { "level": 0, "autoClose": { "confidenceAtLeast": 0.9, "qaSampleRate": 0.1, "dailyCap": 50 }, "escalationsAlwaysToPerson": true, "moreInfoAlwaysToPerson": true, "blockNeedsTwoApprovers": true }, "type": "object", "properties": { "level": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 } ] }, "autoClose": { "type": "object", "properties": { "confidenceAtLeast": { "type": "number", "minimum": 0, "maximum": 1 }, "qaSampleRate": { "type": "number", "minimum": 0.05, "maximum": 1 }, "dailyCap": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000 } }, "required": [ "confidenceAtLeast", "qaSampleRate", "dailyCap" ], "additionalProperties": false }, "escalationsAlwaysToPerson": { "type": "boolean", "const": true }, "moreInfoAlwaysToPerson": { "type": "boolean", "const": true }, "blockNeedsTwoApprovers": { "type": "boolean", "const": true } }, "required": [ "level", "autoClose", "escalationsAlwaysToPerson", "moreInfoAlwaysToPerson", "blockNeedsTwoApprovers" ], "additionalProperties": false }, "structuredOutput": { "default": true, "type": "boolean" }, "agentAccess": { "type": "object", "properties": { "triage": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false }, "evidence": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false }, "screener": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false }, "matching": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false }, "ownership": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false }, "decision": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false }, "critic": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false }, "challenger": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false }, "policy_guard": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false }, "reporter": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "denyColumns": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tables", "denyColumns" ], "additionalProperties": false } }, "required": [ "triage", "evidence", "screener", "matching", "ownership", "decision", "critic", "challenger", "policy_guard", "reporter" ], "additionalProperties": false }, "guards": { "type": "object", "properties": { "tippingOffPolicy": { "type": "string", "minLength": 20 }, "injectionPatterns": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tippingOffPatterns": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "tippingOffPolicy", "injectionPatterns", "tippingOffPatterns" ], "additionalProperties": false } }, "required": [ "version", "name", "lists", "matching", "ownership", "jurisdictions", "automation", "critic", "models", "masking", "challenger", "agentAccess", "guards" ], "additionalProperties": false }, "proposed_by": { "type": "string", "minLength": 1, "maxLength": 100 }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "policy", "proposed_by" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/policy/reload": { "post": { "tags": [ "Policy" ], "summary": "Propose the policy file as a draft", "description": "Roles: approver, policy_admin.", "x-required-roles": [ "approver", "policy_admin" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proposed_by": { "type": "string", "minLength": 1, "maxLength": 100 }, "reason": { "type": "string" } }, "required": [ "proposed_by" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/policy/rollback": { "post": { "tags": [ "Policy" ], "summary": "Propose an earlier version as a new draft", "description": "Roles: approver, policy_admin.", "x-required-roles": [ "approver", "policy_admin" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_version": { "type": "integer", "minimum": 1 }, "proposed_by": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "to_version", "proposed_by" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/policy/drafts/{version}/publish": { "post": { "tags": [ "Policy" ], "summary": "Publish a draft; the approver must differ from the proposer (four-eyes)", "description": "Roles: policy_admin. Four-eyes: the policy admin who publishes must not be the person who proposed the draft.", "x-required-roles": [ "policy_admin" ], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approved_by": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "approved_by" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/policy/drafts/{version}/discard": { "post": { "tags": [ "Policy" ], "summary": "Discard a draft", "description": "Roles: approver, policy_admin.", "x-required-roles": [ "approver", "policy_admin" ], "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actor": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "actor" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } }, "/policy/whatif": { "post": { "tags": [ "Policy" ], "summary": "Review exam cases under the active policy and under a draft, and list what changes. Saves nothing", "description": "Roles: analyst, approver, policy_admin.", "x-required-roles": [ "analyst", "approver", "policy_admin" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "cases": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The request is not valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "401": { "description": "No token, or a token that is unknown, malformed, expired or revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "unauthorized", "message": "a valid token is required", "recoverable": false } } } } }, "403": { "description": "Signed in, but this role may not do this", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "forbidden", "message": "viewer may not do this", "recoverable": false } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] } } } }, "429": { "description": "Too many requests from this caller, or too many reviews running; see Retry-After", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "error" }, "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "description": "validation, not_found, guard_blocked, query_failed, bad_response, rate_limited, ..." }, "message": { "type": "string" }, "recoverable": { "type": "boolean" } }, "required": [ "type", "message", "recoverable" ] } }, "required": [ "status", "request_id", "error" ] }, "example": { "status": "error", "request_id": "3f1c2a9e-5d7b-4c1e-9a2f-0b6d8e4c7a11", "error": { "type": "rate_limited", "message": "too many requests (writes); try again in 42 s", "recoverable": true } } } } } } } } } }