One governed surface, for people and agents.

Overview

The API is an HTTP/JSON interface, described by an OpenAPI 3.1 contract generated from the implementation, so the published spec always matches the running service. The MCP servers, the client libraries, and these docs all derive from that one contract.

Authentication & personas

The principal, persona, home tenant, and knowledge-base access are resolved once per request. There are three security schemes:

Token claims carry sub (principal id), kind (person or agent), persona, kb_access, and scopes. Access is relationship-based: a principal is a reader or steward of a specific base, checked per request after the tenant is resolved. Every knowledge-base-bound path is scoped by tenant and kb_id and is persona-gated.

Persona taxonomy

The personas used across the endpoint tables are business_user (application user), steward, admin, auditor (also written compliance), partner_author, and agent; some routes also use subscriber (an entitled pack or OKF consumer). Licensed framing, generation, and render operations additionally require the caller's tenant to be entitled to the framework or pack.

Agent tokens

Issue an agent token by posting an AgentTokenRequest with the agent_id, the kb_ids and scopes it may use, an authority matrix (per action class and autonomy bound), and a ttl_minutes (default 60). Tokens are listable, scope-editable, rotatable, and revocable. An agent only composes the operations its scopes allow, and an agent at a low autonomy level stages a change into the approval queue rather than committing it directly.

Safety classes

Every operation declares one of five safety classes. A client, the MCP cover, and the apps all use the class to decide when to confirm, to preview, or to poll before acting.

The class is carried on each operation in the OpenAPI schema and consumed by the cover, so a client knows when a confirmation step is mandatory.

Core mechanics

Idempotency

Mutations accept an Idempotency-Key header. A replay returns the original result; a replay with a different body returns request.idempotency_mismatch. The apply request also carries an idempotency_key field.

Preview then apply

Mutating and destructive actions that change a base run a preview that returns an ImpactDiff and a preview_token, then a separate apply that commits, writes provenance, and emits a warrant where the action is decision-bearing.

# 1. preview: see exactly what will change
POST /manipulate/{kb_id}/preview
  -> ImpactDiff { action, direct, cascade, risk_flags, reversible }
     + preview_token

# 2. apply: bind the commit to that preview
POST /manipulate/{kb_id}/apply
  { "preview_token": "...", "idempotency_key": "..." }

An apply whose preview has drifted returns CONFLICT and requires a fresh preview. The cascade respects the circuit breaker, so a runaway change is capped rather than committed.

Pagination

List endpoints are cursor-based. Send cursor and limit (maximum 200); receive { items, next_cursor, has_more }.

Real-time

People stream over a WebSocket at /ws/{kb_id}, authenticated on the upgrade handshake, receiving persona-filtered ChangeEvent objects (item, score, edge, job, curation, breaker) with replay-by-id across a reconnect. Agents receive the same events as HMAC-signed webhooks with a delivery log and retry. For answers, set stream on a query to receive server-sent events.

Common workflows

Ask a question and verify the answer

# ask: returns an AnswerEnvelope (answer + citation list)
POST /query/{kb_id}
  { "question": "What is our fair-lending control protocol?", "stream": false }

# inspect the reasoning and fetch the signed warrant
GET  /query/{kb_id}/trace/{answer_id}
GET  /query/{kb_id}/warrant/{answer_id}

Federate across several bases (your own, cross-tenant grants, and subscribed packs) with POST /query/federate; each base answers from its own governed content and the responses are composed with attribution.

Bring in and curate knowledge

# discover or upload sources, then watch the pipeline
POST /collect/{kb_id}/discover
POST /collect/{kb_id}/upload
GET  /catalog/{kb_id}/runs/{run_id}

# work the steward's queue; decisions are preview-then-apply
GET  /curate/{kb_id}/queue
POST /curate/{kb_id}/queue/{queue_id}/decision
POST /curate/{kb_id}/snapshot        # seal a point-in-time state
POST /curate/{kb_id}/swap            # atomic blue/green promotion

Author a base as code

POST /recipe                          # author
POST /recipe/{recipe_id}/validate
POST /recipe/{recipe_id}/compile      # preview the build
POST /recipe/{recipe_id}/hydrate      # gated build of the base

Frame a subject, read coverage, render a deliverable

# scout, set the coverage target, then generate the framed structure
POST /framegraph/{kb_id}/scout
POST /framegraph/{kb_id}/expected-questions
POST /framegraph/{kb_id}/generate                     # job: aspects + subsets

# read coverage, then render a warranted deliverable and export it
GET  /framegraph/{kb_id}/clusters/{cluster_id}/coverage
POST /deliverables/{deliverable_id}/render            # job
POST /export/{kb_id}                                  # job: the single export path

Endpoint reference

The ten functional routers, plus the platform and partner groups. Each row is representative, not exhaustive; the authoritative list is the OpenAPI contract. Personas and the safety class are declared on every operation.

auth sign-in & tokens

recipe knowledge as code

collect discovery & ingestion

catalog pipeline status

substrate read-only views

query ask, search, research

curate shape & maintain

manipulate what-if, preview/apply

agents oversight & controls

admin runs the platform, never content

Platform & partner groups

Framing, deliverables & coverage

The FrameGraph runtime and the template system are first-class API surfaces, the same engine behind the Canvas in the app and the Browse and steward projections. A frame is applied over a topic graph; the result is a cached, navigable knowledge cluster (a Snap) with a coverage read; a deliverable renders a structured, warranted document from it. Licensed frameworks and templates run only for an entitled tenant, and the internal prompt bundle is never returned.

frames the catalogue, applied

framegraph the runtime

clusters Snaps & coverage

deliverables structured, warranted outputs

config & export

OKF endpoints

Export a source, a collection, or a whole base as a portable OKF bundle, and import external OKF directly. These live on cks-sync and are entitlement-aware: a non-entitled caller receives source metadata only on licensed content, and a licensed bundle returns 402 to a caller without the entitlement.

Import is preview-then-apply and mutating. Conformance is checked against the declared okf_version; a newer minor version is a warning, not a rejection, and CKS hard-rejects only on structural non-conformance (unparseable frontmatter or a missing type).

The MCP cover

The MCP surface is a curated subset of the API exposed as governed tools, decomposed into eight lean servers so a client loads only the short tool list it needs. The tools are generated from the OpenAPI contract (one tool per operation, named {group}_{action}), so the agent surface cannot silently widen. Persona is checked on connection and again per call; every tool carries tenant and knowledge-base context; and each tool's safety class tells the client when to confirm, preview, or poll first.

Errors & limits

Errors share one structured shape: { code, message, request_id, details? }, with namespaced codes. Every response carries a request_id for correlation.

Common HTTP statuses: 202 (import accepted and enqueued), 204 (revoke or delete), 402 (not entitled to licensed content), 404 (not found), 409 (a drifted preview), and 503 (/readyz when a dependency is not ready).

Quotas and spend

Rather than a fixed request-rate ceiling, control is per tenant and persona: tenant quotas on knowledge bases, storage, daily tokens, and seats; usage metering and per-user reporting against included limits; spend budgets with circuit breakers; and agent-action breakers. Exceeding a quota throttles or refuses with a clear error rather than silently degrading a neighbour. The pagination limit is capped at 200.