KOS — FRD: Agent API¶

Parent: KOS PRD
Owner: Digital Office
Status: Phase 1b

Overview¶

FastAPI service exposing KOS knowledge to AI agents and programmatic consumers. Raw-mode only — no LLM synthesis — to prevent prompt injection.

Endpoints¶

Endpoint	Method	Auth	Purpose
/api/v1/query	POST	API Key	Query the knowledge graph
/api/v1/health	GET	None	Health check
/api/v1/metrics	GET	API Key	Operational metrics
/api/v1/audit/logs	GET	API Key	List audit log files
/api/v1/audit/logs/{date}	GET	API Key	Read audit entries
/api/v1/audit/purge	POST	API Key	Purge expired logs

Functional Requirements¶

FR-API-01: Authentication¶

All endpoints except /health require X-API-Key header. Keys configured via KOS_API_KEYS env var (list).

FR-API-02: Synthesis Block¶

If synthesise: true is sent to the Agent API, return HTTP 400. Agents receive raw chunks only. This is a security control against prompt injection via graph content.

FR-API-03: Request Validation¶

Field	Type	Constraint
question	string	1-2000 chars
synthesise	bool	forced false
jurisdiction_filter	list[str]	validated against catalogue
min_authority_score	float	0.0-1.0

FR-API-04: Response Format¶

{
  "answer": "string",
  "citations": [{"source_id": "...", "document_type": "...", "authority": 0.9, "excerpt": "..."}],
  "confidence": 0.85,
  "conflicts": [],
  "audit_id": "uuid",
  "mode": "raw",
  "query_time_ms": 142
}

FR-API-05: Metrics¶

The /metrics endpoint exposes: query count, avg latency, ingestion stats per source, PII detections by type, graph size (nodes/edges), uptime.

FR-API-06: Audit Access¶

The audit log API provides paginated access to JSONL audit entries. Purge respects the legal hold flag.

Security Requirements¶

Control	Implementation
API key auth	Header validation on all non-health routes
No synthesis	HTTP 400 on synthesise=true
Jurisdiction validation	400 on unknown codes
Audit trail	Every query logged, immutable
Legal hold	Purge blocked when KOS_AUDIT_LEGAL_HOLD=true