{ "openapi": "3.1.0", "info": { "title": "AWatch-rus DetMir Portal API", "version": "2026-06-06.pilot-v1", "description": "Stable additive API contract for the Rust server-rendered HTML portal and HTMX-compatible role slices. Dioxus, React, Tauri and Electron are not part of this Pilot v1 contract. Clients must ignore unknown fields and tolerate missing optional fields." }, "servers": [ { "url": "/api", "description": "Gateway-relative API base" } ], "tags": [ { "name": "contracts" }, { "name": "portal" }, { "name": "reports" }, { "name": "roles" }, { "name": "workforce" }, { "name": "security" }, { "name": "forensics" }, { "name": "ueba" }, { "name": "risk" }, { "name": "actions" }, { "name": "pfsense" }, { "name": "incidents" }, { "name": "cases" }, { "name": "readiness" }, { "name": "telemetry" } ], "paths": { "/contracts": { "get": { "tags": [ "contracts" ], "summary": "Contract index", "responses": { "200": { "description": "Contract index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractIndex" } } } } } } }, "/contracts/openapi.json": { "get": { "tags": [ "contracts" ], "summary": "OpenAPI document", "responses": { "200": { "description": "OpenAPI 3.1 document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/contracts/typescript.d.ts": { "get": { "tags": [ "contracts" ], "summary": "TypeScript declarations", "responses": { "200": { "description": "TypeScript declaration file", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/health": { "get": { "tags": [ "portal" ], "summary": "Light service health", "responses": { "200": { "description": "Health payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/operator": { "get": { "tags": [ "portal" ], "summary": "Operator overview payload", "responses": { "200": { "description": "Operator payload used by the HTML portal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/manager": { "get": { "tags": [ "portal" ], "summary": "Manager payload", "responses": { "200": { "description": "Manager payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/owner": { "get": { "tags": [ "portal" ], "summary": "Owner/security payload", "responses": { "200": { "description": "Owner payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/reports": { "get": { "tags": [ "reports" ], "summary": "Management report payload", "parameters": [ { "name": "anonymize", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return anonymized values when supported" }, { "name": "role", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PortalRole" }, "description": "Role slice. The X-AWatch-Role header is also accepted and is preferred by the portal UI." } ], "responses": { "200": { "description": "Report payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPayload" } } } } } } }, "/executive": { "get": { "tags": [ "roles" ], "summary": "Executive role slice", "responses": { "200": { "description": "Executive dashboard and Workforce summary without security detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPayload" } } } }, "403": { "description": "Role is not allowed to access executive scope" } } } }, "/workforce": { "get": { "tags": [ "workforce" ], "summary": "Workforce role slice", "responses": { "200": { "description": "Workforce analytics, department comparison, owners, trends and markdown report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPayload" } } } }, "403": { "description": "Role is not allowed to access workforce scope" } } } }, "/security": { "get": { "tags": [ "security" ], "summary": "Security role slice", "responses": { "200": { "description": "Security risks, events, candidates and UEBA score without Workforce dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPayload" } } } }, "403": { "description": "Role is not allowed to access security scope" } } } }, "/forensics": { "get": { "tags": [ "forensics" ], "summary": "Forensics role slice", "responses": { "200": { "description": "Investigations, timeline contract and export links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPayload" } } } }, "403": { "description": "Role is not allowed to access forensics scope" } } } }, "/ueba": { "get": { "tags": [ "ueba" ], "summary": "UEBA score v1 rule-based contract", "responses": { "200": { "description": "Transparent rule-based UEBA score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UebaPayload" } } } }, "403": { "description": "Role is not allowed to access UEBA scope" } } } }, "/pfsense": { "get": { "tags": [ "pfsense" ], "summary": "pfSense integration readiness contract", "responses": { "200": { "description": "Contract-only pfSense readiness payload with demo fixtures", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PfsenseReadiness" } } } }, "403": { "description": "Role is not allowed to access pfSense scope" } } } }, "/workforce/policy/explain": { "get": { "tags": [ "reports" ], "summary": "Workforce scoring policy explanation", "parameters": [ { "name": "anonymize", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Policy explanation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/incidents": { "get": { "tags": [ "incidents" ], "summary": "Incident list and current state", "responses": { "200": { "description": "Incident payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/incident-review": { "post": { "tags": [ "incidents" ], "summary": "Set manual review status for an incident candidate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentReviewRequest" } } } }, "responses": { "200": { "description": "Updated review state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/investigation-pack/{candidate_id}": { "get": { "tags": [ "incidents" ], "summary": "Export investigation pack for a candidate", "parameters": [ { "name": "candidate_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "markdown" ] } } ], "responses": { "200": { "description": "Investigation pack", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } }, "text/markdown": { "schema": { "type": "string" } } } } } } }, "/cases": { "get": { "tags": [ "cases" ], "summary": "Case list", "responses": { "200": { "description": "Case list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseListResponse" } } } } } }, "post": { "tags": [ "cases" ], "summary": "Create a manual case from a confirmed candidate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCaseRequest" } } } }, "responses": { "200": { "description": "Created case", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/cases/{case_id}": { "get": { "tags": [ "cases" ], "summary": "Case details", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "markdown" ] } } ], "responses": { "200": { "description": "Case details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } }, "text/markdown": { "schema": { "type": "string" } } } } } } }, "/cases/{case_id}/status": { "post": { "tags": [ "cases" ], "summary": "Set manual case status", "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseStatusRequest" } } } }, "responses": { "200": { "description": "Updated case", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/dlp/evidence": { "get": { "tags": [ "incidents" ], "summary": "DLP evidence list", "responses": { "200": { "description": "Evidence list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/readiness/latest": { "get": { "tags": [ "readiness" ], "summary": "Latest readiness bundle status", "responses": { "200": { "description": "Readiness status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/readiness/bundle": { "get": { "tags": [ "readiness" ], "summary": "Readiness bundle artifact list", "responses": { "200": { "description": "Readiness bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/readiness/verify": { "get": { "tags": [ "readiness" ], "summary": "Verify readiness checksums and signature", "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/links": { "get": { "tags": [ "portal" ], "summary": "Gateway-relative portal links", "responses": { "200": { "description": "Link map", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } } } } }, "/telemetry": { "post": { "tags": [ "telemetry" ], "summary": "Agent telemetry ingest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "responses": { "200": { "description": "Accepted telemetry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "401": { "description": "Missing or invalid telemetry API key" } } } }, "/workforce/kpi/explain": { "get": { "tags": [ "workforce" ], "summary": "Rule-based Workforce KPI explanation", "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "department", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PortalRole" } } ], "responses": { "200": { "description": "Explainable Workforce KPI payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkforceKpiExplain" } } } }, "400": { "description": "Query limits rejected" }, "403": { "description": "Role denied" } } } }, "/risk/narrative": { "get": { "tags": [ "risk" ], "summary": "Rule-based executive risk narrative", "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "department", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "module", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PortalRole" } } ], "responses": { "200": { "description": "Risk narrative payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskNarrative" } } } }, "400": { "description": "Query limits rejected" }, "403": { "description": "Role denied" } } } }, "/actions": { "get": { "tags": [ "actions" ], "summary": "Rule-based executive action center", "parameters": [ { "name": "role", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PortalRole" } } ], "responses": { "200": { "description": "Recommended actions payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionCenterResponse" } } } }, "400": { "description": "Query limits rejected" }, "403": { "description": "Role denied" } } } } }, "components": { "schemas": { "PortalRole": { "type": "string", "enum": [ "executive", "manager", "security", "forensics", "admin" ] }, "RoleContext": { "type": "object", "required": [ "role", "scope", "server_enforced" ], "properties": { "role": { "$ref": "#/components/schemas/PortalRole" }, "role_label": { "type": "string" }, "scope": { "type": "string" }, "allowed_scopes": { "type": "array", "items": { "type": "string" } }, "server_enforced": { "type": "boolean" } }, "additionalProperties": true }, "JsonObject": { "type": "object", "additionalProperties": true }, "ContractIndex": { "type": "object", "required": [ "ok", "contract_version", "api_base", "artifacts", "stable_endpoints" ], "properties": { "ok": { "type": "boolean" }, "contract_version": { "type": "string" }, "generated_by": { "type": "string" }, "api_base": { "type": "string" }, "compatibility": { "$ref": "#/components/schemas/JsonObject" }, "targets": { "type": "array", "items": { "type": "string" } }, "artifacts": { "$ref": "#/components/schemas/JsonObject" }, "stable_endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointDescriptor" } } }, "additionalProperties": true }, "EndpointDescriptor": { "type": "object", "required": [ "method", "path" ], "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "purpose": { "type": "string" } }, "additionalProperties": true }, "ReportPayload": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "generated_at_utc": { "type": "string" }, "executive_points": { "type": "array", "items": { "type": "string" } }, "executive_dashboard": { "$ref": "#/components/schemas/JsonObject" }, "risk_narrative": { "$ref": "#/components/schemas/RiskNarrative" }, "recommended_actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionItem" } }, "agent_quality": { "$ref": "#/components/schemas/JsonObject" }, "agent_coverage_sla": { "$ref": "#/components/schemas/JsonObject" }, "business_risk": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } }, "risk_incident_candidates": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } }, "role_context": { "$ref": "#/components/schemas/RoleContext" }, "cases": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } } }, "additionalProperties": true }, "ActionItem": { "type": "object", "required": [ "priority", "title", "summary", "owner_role", "recommended_deadline", "reason_codes", "evidence" ], "properties": { "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "owner_role": { "type": "string", "enum": [ "executive", "manager", "security", "forensics", "admin" ] }, "recommended_deadline": { "type": "string" }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "ActionCenterResponse": { "type": "object", "required": [ "ok", "actions", "model" ], "properties": { "ok": { "type": "boolean" }, "role_context": { "$ref": "#/components/schemas/RoleContext" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionItem" } }, "model": { "$ref": "#/components/schemas/JsonObject" }, "generated_at_utc": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "RiskNarrativeEvidence": { "type": "object", "required": [ "source", "label", "value", "severity" ], "properties": { "source": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, "additionalProperties": true }, "RiskNarrative": { "type": "object", "required": [ "ok", "risk_level", "risk_score", "title", "summary", "why", "evidence", "recommended_actions", "limitations", "model" ], "properties": { "ok": { "type": "boolean" }, "role_context": { "$ref": "#/components/schemas/RoleContext" }, "scope": { "type": "string", "enum": [ "aggregate", "department" ] }, "query": { "$ref": "#/components/schemas/JsonObject" }, "risk_level": { "type": "string", "enum": [ "low", "guarded", "medium", "high", "critical" ] }, "risk_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "confidence": { "type": "string", "enum": [ "high", "medium", "low", "unknown" ] }, "classification": { "type": "string", "enum": [ "confirmed_risk", "likely_risk", "needs_investigation", "insufficient_data" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "why": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/RiskNarrativeEvidence" } }, "recommended_actions": { "type": "array", "items": { "type": "string" } }, "limitations": { "type": "array", "items": { "type": "string" } }, "model": { "$ref": "#/components/schemas/JsonObject" }, "generated_at_utc": { "type": "string" } }, "additionalProperties": true }, "UebaPayload": { "type": "object", "required": [ "ok", "score", "severity", "confidence", "classification", "score_components", "reason_codes", "model" ], "properties": { "ok": { "type": "boolean" }, "role_context": { "$ref": "#/components/schemas/RoleContext" }, "score": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "severity": { "type": "string", "enum": [ "normal", "low", "medium", "high", "critical" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low", "unknown" ] }, "confidence_score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "classification": { "type": "string", "enum": [ "confirmed_risk", "likely_risk", "needs_investigation", "insufficient_data" ] }, "classification_reason": { "type": "string" }, "confidence_reasons": { "type": "array", "items": { "type": "string" } }, "confidence_contributors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } }, "evidence_status": { "type": "string", "enum": [ "available", "not_available" ] }, "score_components": { "type": "object", "required": [ "activity_anomaly", "time_anomaly", "application_anomaly", "network_anomaly", "history_anomaly" ], "properties": { "activity_anomaly": { "type": "integer", "minimum": 0, "maximum": 100 }, "time_anomaly": { "type": "integer", "minimum": 0, "maximum": 100 }, "application_anomaly": { "type": "integer", "minimum": 0, "maximum": 100 }, "network_anomaly": { "type": "integer", "minimum": 0, "maximum": 100 }, "history_anomaly": { "type": "integer", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "explanation": { "type": "string" }, "model": { "$ref": "#/components/schemas/JsonObject" }, "risk": { "$ref": "#/components/schemas/JsonObject" } }, "additionalProperties": true }, "PfsenseReadiness": { "type": "object", "required": [ "ok", "contract_version", "status", "ingestion_available", "firewall_events", "vpn_events", "traffic_summary", "top_destinations" ], "properties": { "ok": { "type": "boolean" }, "role_context": { "$ref": "#/components/schemas/RoleContext" }, "contract_version": { "type": "string" }, "status": { "type": "string", "enum": [ "contract_only", "available" ] }, "siem": { "type": "boolean" }, "ingestion_available": { "type": "boolean" }, "firewall_events": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } }, "vpn_events": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } }, "traffic_summary": { "$ref": "#/components/schemas/JsonObject" }, "top_destinations": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } } }, "additionalProperties": true }, "IncidentReviewRequest": { "type": "object", "required": [ "candidate_id", "status" ], "properties": { "candidate_id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEW", "IN_REVIEW", "CONFIRMED", "FALSE_POSITIVE", "POSTPONED" ] }, "reviewer": { "type": "string" }, "comment": { "type": "string" } }, "additionalProperties": true }, "CreateCaseRequest": { "type": "object", "required": [ "candidate_id" ], "properties": { "candidate_id": { "type": "string" }, "title": { "type": "string" }, "owner": { "type": "string" }, "summary": { "type": "string" }, "decision": { "type": "string" } }, "additionalProperties": true }, "CaseStatusRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "OPEN", "IN_PROGRESS", "RESOLVED", "REJECTED", "ARCHIVED" ] }, "decision": { "type": "string" } }, "additionalProperties": true }, "CaseListResponse": { "type": "object", "required": [ "ok", "cases" ], "properties": { "ok": { "type": "boolean" }, "cases": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } } }, "additionalProperties": true }, "WorkforceKpiExplainFactor": { "type": "object", "required": [ "name", "label", "impact", "explanation" ], "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "impact": { "type": "string" }, "explanation": { "type": "string" } }, "additionalProperties": true }, "WorkforceKpiExplain": { "type": "object", "required": [ "ok", "kpi_score", "confidence", "coverage", "factors", "top_applications", "warnings", "recommendations" ], "properties": { "ok": { "type": "boolean" }, "role_context": { "$ref": "#/components/schemas/RoleContext" }, "scope": { "type": "string" }, "kpi_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "kpi_status": { "type": "string" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "coverage": { "type": "object", "properties": { "agent_coverage_percent": { "type": "integer", "minimum": 0, "maximum": 100 }, "data_freshness": { "type": "string" }, "missing_sources": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "factors": { "type": "array", "items": { "$ref": "#/components/schemas/WorkforceKpiExplainFactor" } }, "top_applications": { "type": "array", "items": { "$ref": "#/components/schemas/JsonObject" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "model": { "$ref": "#/components/schemas/JsonObject" } }, "additionalProperties": true } } } }