API Reference

Complete REST API documentation for AIIA backend.

Base URL

https://your-instance/api/v1

Authentication

Method	Header	Use Case
Bearer Token	Authorization: Bearer <jwt>	User sessions (Keycloak OIDC)
API Key	Authorization: Bearer <api_key>	System integrations
Guest Token	X-Guest-Token: <token>	PBC portal access
Debug Auth	Authorization: Bearer debug-<username>	Development only

Core Endpoints

Engagements

Method	Path	Description	Auth
GET	/engagements	List engagements (filtered by org)	Bearer
POST	/engagements	Create new engagement	Bearer
GET	/engagements/{id}	Get engagement details	Bearer
PUT	/engagements/{id}	Update engagement	Bearer
DELETE	/engagements/{id}	Delete draft engagement	Bearer
POST	/engagements/{id}/transition	Advance engagement state	Bearer

Findings

Method	Path	Description	Auth
GET	/findings	List findings	Bearer
POST	/findings	Create finding	Bearer
GET	/findings/{id}	Get finding details	Bearer
PUT	/findings/{id}	Update finding	Bearer
POST	/findings/{id}/transition	Advance finding state	Bearer

Workpapers

Method	Path	Description	Auth
GET	/workpapers	List workpapers	Bearer
POST	/workpapers	Create workpaper	Bearer
GET	/workpapers/{id}	Get workpaper details	Bearer
PUT	/workpapers/{id}	Update workpaper	Bearer

Planning

Method	Path	Description	Auth
GET	/planning/plans	List annual plans	Bearer
POST	/planning/plans	Create annual plan	Bearer
GET	/planning/plans/{id}	Get plan details	Bearer
GET	/planning/resources	Resource availability	Bearer

Universe & Library

Method	Path	Description	Auth
GET	/universe/items	List universe items	Bearer
POST	/universe/items	Create universe item	Bearer
GET	/library/risks	List risks	Bearer
GET	/library/controls	List controls	Bearer

Monitoring (KRI)

Method	Path	Description	Auth
GET	/monitoring/kris	List KRIs	Bearer
POST	/monitoring/kris	Create KRI	Bearer
POST	/kri-builder/test	Test KRI definition	Bearer
GET	/monitoring/alerts	List alerts	Bearer

Reports

Method	Path	Description	Auth
GET	/reports	List reports	Bearer
POST	/reports	Create report	Bearer
POST	/reports/{id}/export	Export as PDF	Bearer
GET	/executive/board-pack	Get board pack	Bearer

PBC / Portal

Method	Path	Description	Auth
GET	/pbc/requests	List PBC requests	Bearer
POST	/pbc/requests	Create PBC request	Bearer
GET	/portal/requests	Client: view requests	Guest
POST	/portal/upload	Client: upload evidence	Guest

AI Features

Method	Path	Description	Auth
POST	/chat	AI companion chat	Bearer
POST	/ai-assist/suggest	Generate AI suggestion	Bearer
POST	/ai-features/scope-memo	Generate scoping memo	Bearer
POST	/ai-features/cross-audit-summary	Cross-audit analysis	Bearer
POST	/doc-intelligence/analyze	Document intelligence	Bearer
POST	/agentic-ai/task	Agentic AI task	Bearer

Compliance

Method	Path	Description	Auth
GET	/compliance/frameworks	List frameworks	Bearer
GET	/nca/controls	NCA ECC controls	Bearer
GET	/pdpl/requirements	PDPL requirements	Bearer

Administration

Method	Path	Description	Auth
GET	/users	List users	Admin
POST	/users	Create user	Admin
GET	/rbac/roles	List roles	Admin
POST	/rbac/roles	Create role	Admin
GET	/audit-logs	Query audit logs	Admin
GET	/ai-model-configs	List AI models	Admin
POST	/ai-model-configs	Add AI model	Admin
GET	/system/status	System status	Bearer

Billing

Method	Path	Description	Auth
GET	/billing/tiers	List subscription tiers	Public
POST	/billing/subscribe	Create checkout session	Bearer
GET	/billing/usage	Current usage metrics	Bearer
POST	/billing/pay/moyasar	Moyasar payment	Bearer
POST	/billing/webhooks/stripe	Stripe webhook	Public
POST	/billing/webhooks/moyasar	Moyasar webhook	Public
POST	/signup	Register new org	Public
POST	/signup/verify-email	Verify email	Public

Response Format

All responses follow a consistent format:

{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

Error Format

{
  "detail": "Error description"
}

Common Status Codes

Code	Meaning
200	Success
201	Created
400	Bad request (validation error)
401	Unauthorized (missing/invalid token)
403	Forbidden (insufficient permissions)
404	Not found
409	Conflict (duplicate)
429	Rate limited
500	Internal server error

OpenAPI Spec

Interactive API documentation available at:

• Swagger UI: https://your-instance/api/v1/docs
• ReDoc: https://your-instance/api/v1/redoc