# API reference | Corvair Knowledge Substrate

API reference for Corvair Knowledge Substrate: sign-in, previews before changes, errors, and the HTTP routes for knowledge, memory, the Vault and warrants.

Canonical: <https://corvair.ai/cks/api.html>

## Address and format

| Item | Value |
| --- | --- |
| Base address | `https://cks.corvair.ai` |
| Format | JSON in and out, over HTTPS. Times are ISO 8601 with a time-zone offset. |
| Knowledge bases | Most routes name the base they work on, as `{kb_id}`. Memory routes name a project or a conversation; Vault routes name a Vault. |
| Labels | Every route says whether it reads, changes, or needs a preview first, in the OpenAPI description. |
| MCP | Each MCP tool calls one of these routes. The tool list is in the OpenAPI description, beside its route. |

## Sign-in

Send a token with every request:

Header

```
Authorization: Bearer <token>
```

| Token | Where it comes from | Use it for |
| --- | --- | --- |
| Access key | Made in the Knowledge Substrate's screens (**Account**, **Keys**), or with `POST /v1/me/cli-keys`. Named, with permissions and an expiry. | Scripts and services. |
| A person's sign-in | From the screens, the command line or an AI assistant's sign-in. | Anything that person may do, including administrator changes. |
| An application's identity | A registered application signs in as itself and acts for its own agents. | Applications such as Corvair Virtual Worker. |

A key can never make administrator changes: those need a person signed in.

## Previews before changes

Anything that deletes, erases or replaces comes as a pair: a preview, then the change. The preview says exactly what would happen and returns a `preview_token`. Send that token with the change. Without a current preview, the API answers `428` with `mutation.preview_required`.

Erase a person's data: preview, then apply

```
curl -X POST -H "Authorization: Bearer $CKS_KEY" \
  https://cks.corvair.ai/v1/speakers/$SPEAKER_ID/data:erase-preview

curl -X DELETE -H "Authorization: Bearer $CKS_KEY" \
  "https://cks.corvair.ai/v1/speakers/$SPEAKER_ID/data?preview_token=$PREVIEW_TOKEN"
```

The preview lists everything that will be erased.

## Sending twice safely

Routes that seal or save, such as `POST /warrants` and `POST /vault/{vault_id}/generated-files`, take an `Idempotency-Key` header. Send the same key with the same body and you get the first result back, so a retry never makes a second warrant or a second file. The same key with a different body is refused with `request.idempotency_mismatch`. In Memory, an event sent twice with the same id is recorded once.

## Long work

Work that takes time answers at once and carries on in the background. Sealing a warrant answers `202` with `state: sealing`, and the warrant counts once it is sealed. Crawls, gap filling and rebuilds return a job: follow it at `GET /kb/{kb_id}/jobs/{job_ref}`, or have a notice sent to your own address when it finishes.

## Errors

Every error has the same shape:

Error

```
{
  "code": "mutation.preview_required",
  "message": "Ask for a preview first, then send its token.",
  "request_id": "req_7Hq2…",
  "details": {}
}
```

| Code | Status | What it means |
| --- | --- | --- |
| `auth.unauthenticated` | 401 | No sign-in, or it has expired. |
| `auth.forbidden` | 403 | Signed in, but not allowed to do this. |
| `auth.kb_access_denied` | 403 | Not a member of this knowledge base. |
| `cli.person_required` | 403 | A key was used where a person must sign in. |
| `resource.not_found` | 404 | Nothing at that address, or you may not see it. |
| `resource.conflict` | 409 | It changed since you read it. Read it again and retry. |
| `request.validation` | 422 | A field is missing or wrong. `details` says which. |
| `mutation.preview_required` | 428 | Ask for a preview first, then send its token. |
| `request.idempotency_mismatch` | 409 | The same `Idempotency-Key` was sent with a different body. |
| `request.rate_limited` | 429 | Too many requests. Wait and retry. |
| `upstream.timeout` | 504 | A service behind the API took too long. Retry. |
| `internal.error` | 500 | Something went wrong on our side. Quote the `request_id`. |

## Knowledge

Search, answers, documents, claims and topics. Read routes need the **read** permission; confirming or correcting a claim needs **write**.

| Method | Route | What it does |
| --- | --- | --- |
| `POST` | `/query/{kb_id}/search` | Search. Passages ranked best first, each with its source, tier and topics. |
| `POST` | `/query/{kb_id}` | Ask. A cited answer, with the premises it rests on and any warnings. |
| `POST` | `/query/{kb_id}/warrant` | Seal an answer as a Validity Warrant, when you need proof. |
| `POST` | `/query/{kb_id}/coverage` | How well each topic is covered, for a heat map. |
| `GET` | `/kb/{kb_id}/overview` | The base at a glance: documents, passages, claims and topics. |
| `GET` | `/kb/{kb_id}/documents` | List documents, filtered by topic, term, tier, trust, type or date. |
| `GET` | `/kb/{kb_id}/documents/{doc_id}` | One document, with its summary and source. |
| `GET` | `/kb/{kb_id}/documents/{doc_id}/passages` | Its passages, with page and heading. |
| `GET` | `/kb/{kb_id}/documents/{doc_id}/claims` | Its claims and the result of each check. |
| `GET` | `/kb/{kb_id}/documents/{doc_id}/okf` | Its record in the Open Knowledge Format. |
| `POST` | `/kb/{kb_id}/claims/{claim_id}:confirm` | Confirm a claim. Also `:correct` and `:report`. |
| `GET` | `/kb/{kb_id}/topics` | Topics, with their documents and learnings. Terms at `/terms`. |
| `GET` | `/kb/{kb_id}/changes` | What the base changed on its own, each with its reason. |
| `POST` | `/kb/{kb_id}/changes/{change_id}:undo` | Undo one of those changes, after `:undo-preview`. |

Search

```
curl -X POST -H "Authorization: Bearer $CKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What does the warranty exclude?", "top_k": 5}' \
  https://cks.corvair.ai/query/$KB_ID/search
```

Returns `hits`, each a passage with its source, tier and topics, and the facets to narrow the search.

Search and Ask take the same filters: `tier_in` to keep only some source tiers, `since` and `as_of` for dates, `facets`, and `top_k` for how many results. Ask returns `citations`, `premises` and `premise_risk_flags` beside the answer.

## Sources and sites

What the base reads, and how often. Anything that costs money, such as a crawl or filling a gap, shows its cost in a preview first.

| Method | Route | What it does |
| --- | --- | --- |
| `POST` | `/collect/{kb_id}/sources` | Add a web page or document by its address. |
| `GET` | `/collect/{kb_id}/sites` | The sites the base reads, and how often. |
| `PUT` | `/collect/{kb_id}/sites/{domain}` | Set how one site is read. |
| `POST` | `/collect/{kb_id}/sites/{domain}:crawl` | Read a site again, after `:crawl-preview` shows the cost. |
| `POST` | `/collect/{kb_id}/gaps` | Fill gaps in a topic within a cost limit. Returns a job. |
| `GET` | `/recipe/kb/{kb_id}` | The base's recipe: its sites, how often they are read and how far each is trusted. |

## Memory

Record conversations, give agents their context, and keep what is worth remembering.

| Method | Route | What it does |
| --- | --- | --- |
| `POST` | `/v1/conversations/{conversation_id}/events` | Record one event: a message, a decision or a hand-over. |
| `POST` | `/v1/conversations/{conversation_id}/events:batch` | Record many events at once. |
| `GET` | `/v1/conversations/{conversation_id}/events` | List a conversation's events, in order. |
| `POST` | `/v1/conversations/{conversation_id}/context:open` | Build an agent's context in three pieces when a conversation opens. |
| `POST` | `/v1/conversations/{conversation_id}/context:continue` | Each turn, return only what is new. |
| `POST` | `/v1/conversations/{conversation_id}/context:wake` | Refresh the context after a quiet spell. |
| `GET` | `/v1/conversations/{conversation_id}/prompt-context` | The context in one piece, within a token budget you set. |
| `POST` | `/v1/conversations/{conversation_id}/events:search` | Search one conversation's history by words, tags or topic. |
| `POST` | `/v1/projects/{project_id}/memory:search` | Search a project's memory. `memory:answer` asks it a question. |
| `POST` | `/v1/conversations/{conversation_id}/memories:generate` | Make long-term memories from a conversation. |
| `GET` | `/v1/memories` | List long-term memories. `POST` adds one; `PUT /v1/memories/{memory_id}` edits one. |
| `GET` | `/v1/projects/{project_id}/learnings` | Learnings drawn from many conversations. |
| `POST` | `/v1/learnings/{learning_id}:retire` | Retire a learning. Also `:merge`. |
| `POST` | `/v1/speakers` | Add a person or agent who takes part. `GET /v1/speakers` lists them. |
| `DELETE` | `/v1/speakers/{speaker_id}/data` | Erase a person's data, after `data:erase-preview`. |

Record a turn, then get the context for the next one

```
curl -X POST -H "Authorization: Bearer $CKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "message", "speaker_id": "$TOM", "content": "We need the revised quote by the 20th."}' \
  https://cks.corvair.ai/v1/conversations/$CONV/events

curl -X POST -H "Authorization: Bearer $CKS_KEY" \
  https://cks.corvair.ai/v1/conversations/$CONV/context:continue
```

The context comes back in pieces that change at different speeds, so most of each prompt repeats the last one. Sample data.

## Vault

Files and their versions. A new version is checked before it can be read or sent to knowledge.

| Method | Route | What it does |
| --- | --- | --- |
| `POST` | `/vault/{vault_id}/uploads` | Start an upload. Send the parts with `PUT …/uploads/{upload_id}/content`, then `:complete`. |
| `POST` | `/vault/{vault_id}/files` | Upload a small file in one request. |
| `GET` | `/vault/{vault_id}/files` | List files and their states. Folders at `/folders`. |
| `GET` | `/vault/{vault_id}/files/{file_id}/versions/{version_id}/content/{kind}` | Read one version: the original, a preview or a thumbnail. |
| `POST` | `/vault/{vault_id}/generated-files` | Save a file your service generated, with its provenance. |
| `POST` | `/vault/{vault_id}/files/{file_id}:ingest` | Send a checked version to knowledge. |
| `POST` | `/vault/{vault_id}/files/{file_id}:rescan` | Scan a file again. A held file is released with `:release-preview` and `:release`. |
| `POST` | `/vault/{vault_id}/search` | Search files by name, type and content. |
| `POST` | `/vault/{vault_id}/files/{file_id}/versions/{version_id}:seal` | Seal one version as a warrant, after `:seal-preview`. |

## Warrants

Seal decisions, check them and seal what came of them.

| Method | Route | What it does |
| --- | --- | --- |
| `POST` | `/warrants` | Seal a decision. Answers `202` with `state: sealing` at once. |
| `POST` | `/decisions/{kb_id}` | Record a decision from a conversation, sealed as a warrant. |
| `GET` | `/warrants` | List warrants you may see. `GET /warrants/{warrant_id}` reads one. |
| `POST` | `/warrants/{warrant_id}/verify` | Run the seven checks. |
| `GET` | `/warrants/{warrant_id}/download` | Download a warrant to check it offline. |
| `POST` | `/warrants/{warrant_id}/outcomes` | Seal what came of a decision, after `outcomes:preview`. |
| `POST` | `/warrants/{warrant_id}/disclosures:erase` | Erase content and keep the proof, after `disclosures:erase-preview`. |

Seal a decision

```
curl -X POST -H "Authorization: Bearer $CKS_KEY" \
  -H "Idempotency-Key: 3f1c…" -H "Content-Type: application/json" \
  -d @decision.json https://cks.corvair.ai/warrants

# 202 Accepted
{ "warrant_id": "W-2611-0412", "state": "sealing" }
```

`decision.json` names the ledger, the decision and its evidence. Read the warrant again to see `state: sealed`.

## Your account

| Method | Route | What it does |
| --- | --- | --- |
| `GET` | `/auth/me` | Who you are signed in as. |
| `GET` | `/tenants` | The tenants you belong to. |
| `GET` | `/v1/me/cli-credentials` | Your keys and command-line sign-ins. |
| `POST` | `/v1/me/cli-keys` | Make an access key. |
| `POST` | `/v1/me/cli-credentials/{credential_id}:end` | End a key or a sign-in. |

## Administration

For tenant and platform administrators, signed in as a person.

| Method | Route | What it does |
| --- | --- | --- |
| `GET` | `/admin/overview` | The installation at a glance. |
| `GET` | `/admin/kb` | Knowledge bases. `POST /admin/kb` makes one. |
| `GET` | `/admin/principals` | People and agents, and what they may do. |
| `GET` | `/admin/bindings` | Which knowledge base, memory and Vault each project uses. |
| `GET` | `/admin/registered-clients` | The applications registered to use the Knowledge Substrate. |

## OpenAPI description

The full description of every route, with every field, is published with each release. [Contact us](https://corvair.ai/contact.html) for a copy, and load it into your own tools to generate a client. The command line reads the same description.

## The command line

Install on Windows:

```
powershell -ExecutionPolicy ByPass -c "irm https://cks.corvair.ai/download/cli/install.ps1 | iex"
```

Install on macOS or Linux:

```
curl -LsSf https://cks.corvair.ai/download/cli/install.sh | sh
```

Run `cks auth login`, or `cks auth login --device` on a machine without a browser. The [current version and SHA-256](https://cks.corvair.ai/download/cli/latest.json) are published with each release. On Windows the installer adds a `cks` command to your user PATH and adds no new program file, so it runs where Smart App Control is on. Open a new terminal after installing. If you installed `cks` on Windows before 11 November 2026, run the install command once more.

The cks program drives the Knowledge Substrate through its HTTP API. It calls the same routes as the MCP tools and the screens, so what it can do is exactly what the API allows. It never hides a refusal and never works around one. Sign in once in the browser, with the same sign-in and limits as Corvair Virtual Worker. Scripts use a key with a name, scopes and an end date. Every change shows a preview first.

First commands

```
cks auth login
cks context set --tenant northcott --base "Company library"
cks search "maximum working pressure NX-40" --facet tier
cks ask "What does the warranty exclude?" -o json
cks base archive "Old pilot"      # shows the preview, then asks
```

From the Knowledge Substrate command line design. A command is an entry in a YAML file, not new code.

### Sign-in and keys

A person signs in in the browser. A script uses a key made from that sign-in.

Sign-in and keys

```
cks auth login              # opens the browser, you approve on the Knowledge Substrate page
cks auth login --device     # prints a code and an address, for a machine with no browser
cks auth status
cks auth sessions           # your command-line sign-ins
cks auth logout             # ends the sign-in on the server, then removes the tokens here
cks key create --name "Coding sessions" --tenant northcott --tenant northcott-demo --scope read --scope change --days 30 --save
cks key list
cks key end "Coding sessions"
```

Command-line credentials are their own kind and never work on an MCP or service route.

| Part | How it works |
| --- | --- |
| Browser sign-in | The program opens the browser and you approve on a Knowledge Substrate page. It listens on 127.0.0.1 only, takes one request and gives up after 5 minutes. |
| Device sign-in | For a machine with no browser: the program prints a short code and an address, and you type the code on the Knowledge Substrate's page. |
| Session | 12 hours by default. The access token lasts 1 hour and is refreshed; then the program asks you to sign in again. Read and change by default; `--read-only` asks for read only. |
| Keys | Made from your own sign-in and counted as you, marked as a key. Each has a name of 1 to 60 characters, names 1 to 20 tenants, and ends after up to 90 days by default (at most 365). A key unused for 30 days ends by itself. |
| Scopes | read, write and admin. |
| What a key cannot do | Make keys, change access, or apply a previewed change outside a tenant marked test or demo. Those need a person. |
| Where a script finds a key | `CKS_KEY` in the environment, then `--key-file` (refused if other users can read it), then the stored sign-in, then a stored key. |
| Where secrets live | In the operating system's credential store, or in memory for one run when there is none. Never in the settings file, a log or debug output. No option takes a secret on the command line. |

### Context

Say who and where once, not on every command. The order of precedence is the option, the environment, the current context, then the profile. An argument that names a record takes an id or a name; the program looks it up, asks on a terminal when two match, and exits with code 2 when it may not ask.

Context

```
cks context set --tenant northcott --base "Company library"
cks context set --agent coordinator --conversation 7f3c2e18
cks context show
cks context save valve
cks context use valve
```

A profile is one install. The program has no option to turn off certificate checks.

| Option | Environment | Meaning |
| --- | --- | --- |
| `--profile` | `CKS_PROFILE` | Which install |
| `-t, --tenant` | `CKS_TENANT` | Tenant key, name or id |
| `-b, --base` | `CKS_BASE` | Knowledge base name or id; fills `{kb_id}`, and the paired Vault and memory instance |
| `--agent` | `CKS_AGENT` | Registered agent id or role key, for memory commands |
| `--conversation` | `CKS_CONVERSATION` | Memory conversation id |
| `-o, --output` | `CKS_OUTPUT` | table, json, ndjson, csv, yaml or id |
| `--no-input` | `CKS_NO_INPUT` | Never ask; on by itself when standard input is not a terminal |

### Commands

Commands are grouped by the places on the screens, so a person who knows the screens knows the commands. Every command has an example under `cks <command> --help`.

| Place | Commands |
| --- | --- |
| Knowledge | `cks search`, `cks ask`, `cks document list\|show\|claims`, `cks topic list\|show`, `cks coverage`, `cks insights`, `cks trends` |
| Build | `cks build map\|generate\|accept`, `cks discover`, `cks crawl`, `cks job list\|show\|cancel\|retry` |
| Sources and sites | `cks source list\|show\|add\|remove`, `cks source rule list\|set`, `cks site show\|set\|watch`, `cks canonical` |
| Look inside | `cks okf state`, `cks okf files`, `cks okf show`, `cks claim show` |
| Memory | `cks conversation list\|show\|events\|summary`, `cks context pieces\|open\|wake`, `cks history search`, `cks memory list\|search`, `cks learning list\|undo`, `cks agent list\|rename` |
| Vault | `cks file list\|show\|upload\|versions\|download`, `cks file held\|release`, `cks file search` |
| Admin | `cks base list\|show\|set\|archive`, `cks analytics`, `cks decision list\|undo`, `cks work`, `cks access list\|grant\|end`, `cks erase`, `cks model list`, `cks setting list\|set\|reset`, `cks warrant`, `cks audit`, `cks export` |
| Built in | `auth`, `key`, `profile`, `context`, `api`, `run`, `alias`, `doctor`, `upgrade`, `completion`, `version`, `whoami`, `help` |

Examples

```
cks search "tilt range for latching valves" --facet tier --facet okf_trust
cks ask "When must we file in the US?" -o json
cks coverage --topic valve-actuation --topic prior-art-valves --dimension tier
cks history search "battery capacity" --tag design
cks setting set tail_step_tokens 50000 --level agent --agent coordinator --reason "Long reviews"
cks api GET /query/{kb_id}/search --input query.json
```

The api command reaches any route in the contract.

`cks api [METHOD] <path>` calls any route in the contract with the same sign-in, context and exit codes. The path must start with `/`; a full address is refused, so the credential never goes to another host.

### Previews before every change

Changes are shown before they happen. On a terminal the program shows the preview, what changes and how many records, and asks y/N. In a script, one command prints the preview and its token and changes nothing, and a second applies exactly what that preview showed.

Preview and apply

```
cks base archive "Old pilot"                 # shows the preview, asks y/N, then applies with the token
cks base archive "Old pilot" --preview -o json > preview.json
cks base archive "Old pilot" --apply "$(jq -r .preview_token preview.json)"
```

A key can apply only in tenants marked test or demo.

Writes carry an idempotency key and are never retried. If a write times out the program says the result is not known and exits with code 9. Reads retry up to three times on a busy or unavailable server, and honour the wait the server asks for.

### Output and exit codes

Choose the format with `-o`: table, json, ndjson, csv, yaml or id. Data goes to standard output. Messages, questions and errors go to standard error, as one line: the server's words, its code and a request reference. `--dry-run` prints the request and sends nothing. `--debug` prints method, path, status, request id and time, with credentials hidden and no bodies.

| Code | When |
| --- | --- |
| 0 | Done |
| 1 | Any other failure |
| 2 | Wrong use: unknown option, bad value, a name with two matches |
| 3 | Not signed in, or the sign-in has ended |
| 4 | Refused, with the server's fixed code |
| 5 | Not found |
| 6 | It changed meanwhile |
| 7 | A person must be present: a change outside a test tenant with no prompt, or with a key |
| 8 | Too many requests, after the retries |
| 9 | Server error, server not reached, or a write whose result is not known |
| 10 | An upgrade is available (the upgrade check only) |
| 11 | A scenario step did not get what it expected (the run command only) |

### Commands are data

Every command except the built-in ones is an entry in a YAML file, one file per place. An entry names a route in the API contract, its arguments and options, the preview route, and the example it must carry. The loader refuses an unknown key, an unknown route and an entry with no example. A route labelled as a change with a preview, or as destructive, must name its preview. Adding a command is adding an entry, not code.

A command entry

```
- command: source rule set
  summary: Keep, exclude or purge sources that match a rule
  request: PUT /collect/{kb_id}/source-rules/{rule_id}
  preview: POST /collect/{kb_id}/source-rules/{rule_id}:preview
  examples:
    - cks source rule set "Old competitor pages" --action purge --match "site:example.com/archive"
```

Shortened from the Knowledge Substrate command line design.
