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:
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.
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"
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:
{
"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. |
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
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. |
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
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. |
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 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 | shRun 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.
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
Sign-in and keys
A person signs in in the browser. A script uses a key made from that sign-in.
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"
| 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.
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
| 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 |
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
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.
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)"
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.
- 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"