API reference.

Every main operation in Corvair Knowledge Substrate, for your own software. The same operations are available to AI assistants as MCP tools, and to scripts through the command line, with the same permissions everywhere.

Address and format

ItemValue
Base addresshttps://cks.corvair.ai
FormatJSON in and out, over HTTPS. Times are ISO 8601 with a time-zone offset.
Knowledge basesMost routes name the base they work on, as {kb_id}. Memory routes name a project or a conversation; Vault routes name a Vault.
LabelsEvery route says whether it reads, changes, or needs a preview first, in the OpenAPI description.
MCPEach 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>
TokenWhere it comes fromUse it for
Access keyMade 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-inFrom the screens, the command line or an AI assistant's sign-in.Anything that person may do, including administrator changes.
An application's identityA 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": {}
}
CodeStatusWhat it means
auth.unauthenticated401No sign-in, or it has expired.
auth.forbidden403Signed in, but not allowed to do this.
auth.kb_access_denied403Not a member of this knowledge base.
cli.person_required403A key was used where a person must sign in.
resource.not_found404Nothing at that address, or you may not see it.
resource.conflict409It changed since you read it. Read it again and retry.
request.validation422A field is missing or wrong. details says which.
mutation.preview_required428Ask for a preview first, then send its token.
request.idempotency_mismatch409The same Idempotency-Key was sent with a different body.
request.rate_limited429Too many requests. Wait and retry.
upstream.timeout504A service behind the API took too long. Retry.
internal.error500Something 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.

MethodRouteWhat it does
POST/query/{kb_id}/searchSearch. 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}/warrantSeal an answer as a Validity Warrant, when you need proof.
POST/query/{kb_id}/coverageHow well each topic is covered, for a heat map.
GET/kb/{kb_id}/overviewThe base at a glance: documents, passages, claims and topics.
GET/kb/{kb_id}/documentsList 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}/passagesIts passages, with page and heading.
GET/kb/{kb_id}/documents/{doc_id}/claimsIts claims and the result of each check.
GET/kb/{kb_id}/documents/{doc_id}/okfIts record in the Open Knowledge Format.
POST/kb/{kb_id}/claims/{claim_id}:confirmConfirm a claim. Also :correct and :report.
GET/kb/{kb_id}/topicsTopics, with their documents and learnings. Terms at /terms.
GET/kb/{kb_id}/changesWhat the base changed on its own, each with its reason.
POST/kb/{kb_id}/changes/{change_id}:undoUndo 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.

MethodRouteWhat it does
POST/collect/{kb_id}/sourcesAdd a web page or document by its address.
GET/collect/{kb_id}/sitesThe 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}:crawlRead a site again, after :crawl-preview shows the cost.
POST/collect/{kb_id}/gapsFill 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.

MethodRouteWhat it does
POST/v1/conversations/{conversation_id}/eventsRecord one event: a message, a decision or a hand-over.
POST/v1/conversations/{conversation_id}/events:batchRecord many events at once.
GET/v1/conversations/{conversation_id}/eventsList a conversation's events, in order.
POST/v1/conversations/{conversation_id}/context:openBuild an agent's context in three pieces when a conversation opens.
POST/v1/conversations/{conversation_id}/context:continueEach turn, return only what is new.
POST/v1/conversations/{conversation_id}/context:wakeRefresh the context after a quiet spell.
GET/v1/conversations/{conversation_id}/prompt-contextThe context in one piece, within a token budget you set.
POST/v1/conversations/{conversation_id}/events:searchSearch one conversation's history by words, tags or topic.
POST/v1/projects/{project_id}/memory:searchSearch a project's memory. memory:answer asks it a question.
POST/v1/conversations/{conversation_id}/memories:generateMake long-term memories from a conversation.
GET/v1/memoriesList long-term memories. POST adds one; PUT /v1/memories/{memory_id} edits one.
GET/v1/projects/{project_id}/learningsLearnings drawn from many conversations.
POST/v1/learnings/{learning_id}:retireRetire a learning. Also :merge.
POST/v1/speakersAdd a person or agent who takes part. GET /v1/speakers lists them.
DELETE/v1/speakers/{speaker_id}/dataErase 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.

MethodRouteWhat it does
POST/vault/{vault_id}/uploadsStart an upload. Send the parts with PUT …/uploads/{upload_id}/content, then :complete.
POST/vault/{vault_id}/filesUpload a small file in one request.
GET/vault/{vault_id}/filesList 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-filesSave a file your service generated, with its provenance.
POST/vault/{vault_id}/files/{file_id}:ingestSend a checked version to knowledge.
POST/vault/{vault_id}/files/{file_id}:rescanScan a file again. A held file is released with :release-preview and :release.
POST/vault/{vault_id}/searchSearch files by name, type and content.
POST/vault/{vault_id}/files/{file_id}/versions/{version_id}:sealSeal one version as a warrant, after :seal-preview.

Warrants

Seal decisions, check them and seal what came of them.

MethodRouteWhat it does
POST/warrantsSeal a decision. Answers 202 with state: sealing at once.
POST/decisions/{kb_id}Record a decision from a conversation, sealed as a warrant.
GET/warrantsList warrants you may see. GET /warrants/{warrant_id} reads one.
POST/warrants/{warrant_id}/verifyRun the seven checks.
GET/warrants/{warrant_id}/downloadDownload a warrant to check it offline.
POST/warrants/{warrant_id}/outcomesSeal what came of a decision, after outcomes:preview.
POST/warrants/{warrant_id}/disclosures:eraseErase 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

MethodRouteWhat it does
GET/auth/meWho you are signed in as.
GET/tenantsThe tenants you belong to.
GET/v1/me/cli-credentialsYour keys and command-line sign-ins.
POST/v1/me/cli-keysMake an access key.
POST/v1/me/cli-credentials/{credential_id}:endEnd a key or a sign-in.

Administration

For tenant and platform administrators, signed in as a person.

MethodRouteWhat it does
GET/admin/overviewThe installation at a glance.
GET/admin/kbKnowledge bases. POST /admin/kb makes one.
GET/admin/principalsPeople and agents, and what they may do.
GET/admin/bindingsWhich knowledge base, memory and Vault each project uses.
GET/admin/registered-clientsThe 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 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 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.
PartHow it works
Browser sign-inThe 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-inFor 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.
Session12 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.
KeysMade 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.
Scopesread, write and admin.
What a key cannot doMake keys, change access, or apply a previewed change outside a tenant marked test or demo. Those need a person.
Where a script finds a keyCKS_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 liveIn 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.
OptionEnvironmentMeaning
--profileCKS_PROFILEWhich install
-t, --tenantCKS_TENANTTenant key, name or id
-b, --baseCKS_BASEKnowledge base name or id; fills {kb_id}, and the paired Vault and memory instance
--agentCKS_AGENTRegistered agent id or role key, for memory commands
--conversationCKS_CONVERSATIONMemory conversation id
-o, --outputCKS_OUTPUTtable, json, ndjson, csv, yaml or id
--no-inputCKS_NO_INPUTNever 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.

PlaceCommands
Knowledgecks search, cks ask, cks document list|show|claims, cks topic list|show, cks coverage, cks insights, cks trends
Buildcks build map|generate|accept, cks discover, cks crawl, cks job list|show|cancel|retry
Sources and sitescks source list|show|add|remove, cks source rule list|set, cks site show|set|watch, cks canonical
Look insidecks okf state, cks okf files, cks okf show, cks claim show
Memorycks 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
Vaultcks file list|show|upload|versions|download, cks file held|release, cks file search
Admincks 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 inauth, 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.

CodeWhen
0Done
1Any other failure
2Wrong use: unknown option, bad value, a name with two matches
3Not signed in, or the sign-in has ended
4Refused, with the server's fixed code
5Not found
6It changed meanwhile
7A person must be present: a change outside a test tenant with no prompt, or with a key
8Too many requests, after the retries
9Server error, server not reached, or a write whose result is not known
10An upgrade is available (the upgrade check only)
11A 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.

Connect your first assistant.