Overview

The kovac API lets your own code do what the platform UI does: create conversations, run agents against them, and stream the results back with citations to the documents the answer came from.

There is no SDK you have to adopt and no message broker to stand up. Two families of HTTP endpoints, one credential, and server-sent events for anything that streams.

Authentication

Every request carries a tenant API key as a bearer token:

curl -s "$KOVAC_BASE/api/manage/agents" \
  -H "Authorization: Bearer $KOVAC_API_KEY"

A key is scoped to exactly one tenant and carries the role it was created with — viewer, editor or admin. Nothing about a request can widen that: the tenant and the role come from the key itself, never from a header, a query parameter or a request body you send. That is what makes it safe to hand a key to a service and let it call the API directly.

Keys are created on the API Keys screen and shown once, at creation. The platform stores only a hash, so a lost key cannot be recovered — it can only be regenerated, which invalidates the old one.

The base URL

The API is served from the same origin as these docs. If you are reading this at https://kovac.example.com/docs/overview, then:

export KOVAC_BASE="https://kovac.example.com"

Both endpoint families live under that origin, so there is no second hostname to configure and no cross-origin setup to do.

What you can call

The Agent Protocol (/api/agent/*) is the runtime. You create a thread, start a run on it, and read the stream:

curl -s -X POST "$KOVAC_BASE/api/agent/threads" \
  -H "Authorization: Bearer $KOVAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

It is a published protocol rather than a bespoke API, so an existing client that speaks it will work against this platform unchanged.

Management (/api/manage/*) is everything around the runtime: the agents available to you, the collections your agents retrieve from, and the documents inside them.

The published reference documents the endpoints that are supported for external use. Endpoints that exist for the platform’s own screens are deliberately absent from it.

Where to go next

The Quickstart takes you from a fresh key to a streamed answer with citations in four steps.

The Concepts pages explain the pieces you will meet along the way — agents, threads and runs, collections — and the Guides turn them into tasks.

The API reference documents every supported endpoint and can send real requests against your own tenant with your own key.