API Overview

The Koveria REST API provides programmatic access to every platform capability — agents, teams, knowledge, compliance, MCPs, and more. Every action available in the GUI Portal is backed by an API endpoint.

Base URL

All endpoints are prefixed with /api/v1. Throughout this documentation, examples use the development base URL.

Development:  http://localhost:8000/api/v1
Staging:      https://staging-api.koveria.ai/api/v1
Production:   https://api.koveria.ai/api/v1

---

Request Lifecycle

Every API request flows through a deterministic middleware chain before reaching the route handler:

Middleware execution order: CORS → Auth → Rate Limit → Tenant Context → Route Handler

---

Authentication

The API supports four authentication methods. The right choice depends on your use case:

Method	Header	Use Case	Details
JWT Token	Bearer <jwt>	GUI Portal, browser apps	Keycloak-issued, short-lived
API Key	Bearer kov_...	Agents, CI/CD, scripts	Long-lived, team-scoped
Portal JWT	Bearer <portal-jwt>	SDK → Backend calls	Internally signed, short-lived
Dev Token	Bearer dev-token	Local development only	DEBUG mode only

# Example: API Key authentication
curl -H "Authorization: Bearer kov_live_abc123..." \
     https://api.koveria.ai/api/v1/agents

→ Full guide: Authentication

---

Response Format

All responses use a consistent JSON envelope.

Success Response:

{
  "agents": [...],
  "total": 42
}

Error Response:

{
  "error": "RESOURCE_NOT_FOUND",
  "message": "Agent 550e8400-... not found",
  "details": {
    "resource_type": "Agent",
    "resource_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

→ Full reference: Error Handling

---

Endpoint Catalog

All endpoints live under /api/v1. They are organized into logical groups:

Platform Services

Endpoint	Methods	Description
/auth/login	POST	Login via username/password (ROPC → Keycloak)
/auth/register	POST	Register new user + create/join organization
/auth/refresh	POST	Exchange refresh token for new access token
/auth/validate-key	POST	Introspect API key (internal, SDK use)
/health	GET	Basic health check
/health/detailed	GET	Infrastructure service statuses
/me	GET	Current user profile

Agents

Endpoint	Methods	Description
/agents	GET, POST	List / create agents
/agents/{id}	GET, PATCH, DELETE	Read / update / delete agent
/agents/{id}/invalidate-cache	POST	Clear portal schema cache
/agents/{id}/metrics	GET	Agent usage metrics
/agents/{id}/personas	GET, POST	Manage agent personas

Teams & Workspaces

Endpoint	Methods	Description
/teams	GET, POST	List / create teams
/teams/{id}	GET, PATCH, DELETE	Read / update / delete team
/teams/{id}/agents	GET, POST	Team agent assignments
/workspaces	GET, POST	List / create workspaces
/orgs/{org_id}/team-api-keys	GET, POST	Manage team API keys

Knowledge & RAG

Endpoint	Methods	Description
/rag/query	POST	Query knowledge collections
/rag/collections	GET, POST	List / create collections
/rag/collections/{id}	GET, PATCH, DELETE	Manage collection
/rag/collections/{id}/chunks	GET	Browse indexed chunks
/portal/knowledge	GET	Portal knowledge endpoints
/local-indexer	POST	Local indexer sync API

LLM & AI Services

Endpoint	Methods	Description
/llm/complete	POST	LLM completion (with tool calling)
/llm/models	GET	Available models
/llm-providers	GET, POST	Manage LLM provider configs
/llm-contracts	GET, POST	LLM usage contracts
/memory	GET, POST	Agent memory store

MCPs (Model Context Protocol)

Endpoint	Methods	Description
/mcps	GET, POST	List / register MCPs
/mcps/{id}	GET, PATCH, DELETE	Manage MCP service
/mcp	(SDK mount)	SDK dual-mount for MCP clients
/sdk/mcp	(SDK mount)	SDK MCP endpoints

Compliance & Governance

Endpoint	Methods	Description
/assessments	GET, POST	Risk assessments
/compliance	GET	Compliance status
/controls	GET, POST	Compliance controls
/evidences	GET, POST	Evidence management
/evidence-types	GET	Evidence type catalog
/questionnaires	GET, POST	Assessment questionnaires

Operations

Endpoint	Methods	Description
/deployments	GET, POST	Agent deployments
/costs	GET	Cost tracking & budgets
/audit	GET	Audit trail
/logs	GET	Agent runtime logs
/secrets	GET, POST	Secrets management
/circuit-breakers	GET, POST	Circuit breaker states
/runtime	GET	Agent runtime status

Admin & Portal

Endpoint	Methods	Description
/admin/*	Various	Organization admin endpoints
/portal/teams	GET	List published teams (marketplace catalog)
/portal/discover	POST	AI-powered team recommendations (LLM)
/portal/teams/{id}/chat	POST	Chat with team orchestrator
/portal/teams/{id}/schema	GET	Agent UI schema (RJSF)
/public/*	Various	Public endpoints (no auth)
/discover/teams	GET	List published teams (M17 service registry)
/discover/teams/{slug}	GET	Deterministic team resolution by slug (M17)

→ Full reference with request/response examples: API Reference

---

Versioning

The API is versioned via the URL path (/api/v1). Breaking changes will introduce a new version (/api/v2), with a deprecation period for the previous version.

Current version: v1

---

Rate Limiting

Requests are rate-limited based on your tier:

Tier	Requests/min	Burst
Free	60	10
Standard	300	50
Premium	1,000	100
Enterprise	5,000	500

Rate limit exceeded returns 429 Too Many Requests with a Retry-After header.

→ Full details: Rate Limits

---

Interactive Documentation

The API ships with built-in interactive documentation:

Tool	URL	Description
Swagger UI	/docs	Interactive endpoint explorer
ReDoc	/redoc	Alternative reference view
OpenAPI spec	/openapi.json	Machine-readable schema

---

Next Steps

• Authentication — Set up your first API key
• Quickstart — Make your first API call in 5 minutes
• Error Handling — Understand error codes and responses
• API Reference — Complete endpoint documentation
• Webhooks — Real-time event notifications