API

The Kyvvu API is a FastAPI backend that sits at the centre of the platform. Every agent interaction, policy evaluation, incident, and audit report flows through it.

• Local: http://localhost:8000

• Production: Your installation.

• Interactive docs (Swagger): /docs

• OpenAPI spec: /openapi.json

---

Two types of callers

The API has two distinct audiences, each with different authentication and a different set of endpoints.

Agents — API key auth

Agents call exactly two endpoints, authenticated with an API key in the Authorization header:

Authorization: Bearer KvKey-your-api-key

Method	Endpoint	Purpose
POST	/api/v1/agents	Register or update the agent
POST	/api/v1/logs	Log one execution step

That's all an agent ever needs to do. Everything else — policy evaluation, incident creation, hash chaining — happens server-side in response to these two calls.

For Microsoft Copilot Studio agents, there is one additional endpoint that combines registration and logging in a single call:

Method	Endpoint	Purpose
POST	/api/v1/copilot/log	Log a Copilot Studio step (auto-registers agent on first call)

Humans & the dashboard — JWT auth

All other endpoints are for human operators and the dashboard. They require a JWT token obtained by logging in:

POST /api/v1/auth/login
{ "email": "...", "password": "..." }
# → { "access_token": "eyJ..." }

Authorization: Bearer eyJ...

These endpoints cover the full management surface of the platform:

Module	What it manages
auth/	User accounts, login, API key management
agents/	View, filter, and deactivate registered agents (GET, DELETE)
logs/	Browse execution logs, retrieve task chains, validate hash integrity (GET)
policies/	Create, update, enable/disable, and delete compliance policies
policy-templates/	Apply or remove pre-built policy frameworks in one operation
incidents/	Review, resolve, ignore, and reactivate policy violations
reports/	Generate PDF or XML audit reports for any date range
events/	Immutable platform audit trail (read-only)
actions/	Configure automated responses to incidents (webhooks, alerts)

---

Authentication summary

Caller	Auth method	Can call
AI agent	API key (KvKey-...)	POST /agents, POST /logs, POST /copilot/log
Human / dashboard	JWT token (email + password)	Everything else

API keys are scoped to a user account. An agent can only register itself and log its own steps — it cannot read other agents' data, access policies, or view incidents.

---

Health check

curl http://localhost:8000/health
# → { "status": "healthy", ... }

Returns overall status, uptime, system metrics, and database connectivity. No authentication required.

---

Further reading

For a full description of each module's data model and behaviour, see API Reference. For the interactive endpoint documentation, visit /docs on your running instance.