5  Glossary

Bearer token. A credential sent in the Authorization header, used by non-browser callers — the AI engines, kavai api, an integration. Contrast cookie session.

Cookie session. The credential a signed-in browser holds. Sent automatically with same-site requests, which is why browser-facing operations need no explicit token.

Family. A group of operations over one kind of thing — datasets, images, organisation membership. One chapter each in this document.

Handler. The code that runs when a request arrives. In KAP, a route.ts file under web/app/api/, exporting one function per method.

Method. The verb of a request: GET reads, POST creates or submits, PUT replaces, PATCH changes part, DELETE removes. Method and path together name an operation.

OpenAPI. The standard format for describing an HTTP surface. KAP’s is web/public/api-docs/swagger.yaml, hand-maintained and checked against the handlers by scripts/check_swagger_drift.py.

Operation. One request the platform accepts — a method and a path taken together. The unit of measurement throughout this document.

operationId. An operation’s stable name, independent of its path. What kavai api takes as an argument and what the agent tool surface refers to. The operation index lists every one.

Row-level security (RLS). Postgres rules that decide which rows a query may return, enforced by the database rather than by application code. KAP scopes most tables through dataset and organisation membership.

Service-role client. A database connection that bypasses row-level security entirely. Necessary for some work; it moves the tenancy boundary from the database into the handler.

Verified caller. A handler containing a call that resolves the requesting user. Its absence is reported in this document as an absence, not as a verdict: a handler may delegate the check to a helper this analysis does not follow.

† — a why it exists line assembled mechanically rather than written by the operation’s author. Accurate about behaviour; unproven about purpose.