API

Overview

The data model in one breath: a bundle is a folder of concepts; a concept is a markdown document at a path such as auth/token-expiry, with type, tags, relations and a rev. Links in the web app are relations here. See the manual for the rest.

The API

https://api.fra.korpus.cloud/v1

Send the token as Authorization: Bearer …. No CORS: a token in a browser page is a token anyone can read.

• GET /v1: what this credential may call. {api, delegation, rules, tools}, each op with name, title, description, read_only, destructive and its input as JSON Schema. delegation is null for me. api moves only on a break.
• POST /v1/<op> with the arguments as a JSON object: 200 {data, text}. A refusal is {"error": {"code", "message", …details}} with the HTTP status the failure has everywhere in Korpus (400 a bad input, 403 restricted or out of room, 404 not found, 409 a conflict, 412 rev_mismatch, 429 rate_limited, and 503 maintenance or database_starting with Retry-After).

GET https://api.fra.korpus.cloud/v1

200 OK
{ "api": 1, "delegation": "nightly-sync", "rules": [ … ],
  "tools": [ { "name": "list_folder", "title": "List folder", "description": "…",
               "read_only": true, "destructive": false, "input": { …JSON Schema… } }, … ] }

curl -fsS https://api.fra.korpus.cloud/v1/list_folder \
  -H "Authorization: Bearer $KORPUS_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"bundle": "01JBQ3M7X9VK2NDCTF8ZPYW4RH", "folder": "runbooks"}'

200 OK
{ "data": { "entries": [ … ], "hidden": false },
  "text": "…" }

412 Precondition Failed
{ "error": { "code": "rev_mismatch",
             "message": "concept \"runbooks/deploy\" has changed since you read it (now rev 5); …",
             "current_rev": 5, "updated_by": "…", "updated_at": "…" } }

Refused before any op runs:

The data shapes are typed in the SDK (Tools in its type definitions); the text is the one an MCP client reads.

MCP

A client reads an address from its config. The .mcp.json shape Claude Code and similar clients read:

{
  "mcpServers": {
    "korpus": {
      "type": "http",
      "url": "https://mcp.fra.korpus.cloud/"
    }
  }
}

Instructions

On initialize the server sends instructions a client passes to its model:

1. Which Korpus deployment the client reached.
2. A short overview: the data model, which tools only look, the change description every write carries, how to find things (list_folder first).
3. The access's name and job (me or a delegation) and, for a delegation, its rules.

Everything longer sits behind the manual tool, so a client that drops the instructions can still read them. Topics:

MCP: tools

One tool per action, each with a title a client shows and hints it sorts by. The reading tools carry readOnlyHint, so most clients let a person allow them for good; every other tool asks, and the ones that remove or end something also carry destructiveHint. Every tool is openWorldHint: false. A delegation gets no managing op at all.

• Change descriptions. create_concept, update_concept, delete_concept, add_relation and remove_relation take a required change_description: one line, what changed and why. It is the log; nothing else records why a concept moved.
• Index and log. Every folder has an index (read_index: the titles and descriptions of its concepts) and a log (read_log: its changes, newest first). Both are generated from the content as OKF 0.2 §8 and §9 describe, never stored, so no concept may be named index or log.
• Revisions. read_concept returns a concept's rev. Pass it back on update_concept and the call fails with rev_mismatch if someone changed the concept meanwhile. Without it the update lands and says whose revision it changed. update_concept changes only the fields given; "" clears a text field.

On the wire

A tool call is an ordinary tools/call. Its answer is a tool result with one plain-text content item, written for a model to read; read_asset with inline adds the file itself (an image, text or an embedded resource). There are no resource_links and no structuredContent; a program that wants the data as JSON uses the API door (The API).

POST /
Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json, text/event-stream

{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": { "name": "create_concept", "arguments": {
    "bundle": "01M3…", "path": "README",
    "type": "Guide", "title": "Research",
    "body": "# Research\nWhat this bundle is for.",
    "change_description": "Said what this bundle is for" } } }

200 OK
{ "jsonrpc": "2.0", "id": 7, "result": {
  "isError": false,
  "content": [
    { "type": "text", "text": "ok README created, rev 1" }
  ] } }

A call that fails answers the same way with isError: true and the text <code>: <message>. Only transport and account problems are JSON-RPC or HTTP errors: 401 without a valid token, and 403 (-32003) for a credential this address does not take or a blocked account (the list).

Every op

Every op below is served at both doors: POST /v1/<op> on the API, a tool of the same name over MCP, with the same arguments, rules and limits. Parameters with ? are optional. The input schemas (GET /v1, tools/list) carry the same fields with a description each; the manual topics explain the behaviour. manual is MCP only.

Field shapes

Reading readOnly · idempotent · every access, inside its rules

Writing asks · every access, inside its rules

Managing asks · me only

Only on the API

These ops are served at the API door alone: the web app's own, and a few a program signed in as you may call. who says who is offered each: you, signed in (your own sign-in, never a delegation), the web app (its own session alone: account, billing, support) or no sign-in (the cancel page, which needs no credential). A delegation sees none of them. Questions about billing: support@korpus.cloud.

Files

An asset is a file (a PDF, a spreadsheet, an archive) and the concept that explains it, at one path: type: asset, with an asset block the server writes (filename, content type, size, source, whether it has landed). The body is required. It says what is in the file, so the next agent reads two kilobytes of prose instead of parsing forty megabytes again. Moving or deleting the concept moves or deletes the file; whoever may read the concept may download it.

• Upload by URL: create_asset (over MCP or the API) with bytes and content_type answers one line for a shell: curl -fsS -T <file> -H 'content-type: …' "$(curl -fsS https://mcp.fra.korpus.cloud/u/<id>)". The link is good for 15 minutes; the content type and length are signed, so send exactly what you declared. The file goes straight to storage, up to 100 MB.
• Upload as text: text instead of bytes stores a small UTF-8 file (a CSV, JSON or Markdown, up to 1 MB) at once, for an agent with no shell.
• Download: read_asset answers a URL valid for 60 seconds; with inline the file itself comes back in the answer (up to 3 MB): an image as image content, text as text, anything else as an embedded resource.
• Replace: update_asset with the rev you read takes a new file, and any document fields, in one write; the old file is deleted once it commits.

Files count against their own space, apart from the document space, charged to whoever created the bundle (quota_exceeded, limit asset_space). In the web app, drop a file on a folder.

Resources and prompts

Both are text/markdown and go through the same access checks as the tools.

Errors

Over MCP a failure reads <code>: <message>, sometimes followed by details as JSON and a pointer to a manual topic; at the API it is {"error": {"code", "message", …details}}, with the HTTP status the failure has everywhere in Korpus. The message names the fix.

More codes

Before a tool runs

Refusals of the request itself, before any tool: over MCP a JSON-RPC error -32003 with the HTTP status, at the API {"error": {"code", "message"}}.

The codes are the same on every door and in the SDK's KorpusError. Retry hints: rate_limited, maintenance and database_starting carry retry_after, in seconds. A rate_limited wait is seconds: wait it out, then go on where you stopped. manual topic=errors explains every code.

Limits and usage

Space is the one quota: counted per person, over the bundles they created, for documents and for files apart. A concept counts its body and fields (title, description, tags, relations, frontmatter), plus 1 KB. Full, a write answers quota_exceeded; get_usage shows how full each is, and is never refused. Writes and reads each have a short-term rate, there only to stop a runaway loop: a call counts 1, a batch 1 per item, a body search or an export 10 reads. Over one, the call answers rate_limited with retry_after in seconds. The rates are higher on Plus and are not published.

The SDK

@korpus-cloud/sdk is Korpus from code: a CI job, a cron script, an app of yours reads and writes the same bundles people and AI apps use, as a delegation held to the rules you give it. Every method is one op of the API.

Use

import { Korpus } from '@korpus-cloud/sdk';

const korpus = new Korpus(); // KORPUS_KEY, a trusted workload, or a sign-in from korpus login
const notes = korpus.bundle('01JBQ3M7X9VK2NDCTF8ZPYW4RH');

// Find, read, change.
const entries = await notes.folder('runbooks');
const { concept } = await notes.read('runbooks/deploy');
await notes.update('runbooks/deploy', {
  rev: concept.rev, // fails with rev_mismatch if someone changed it since
  body: concept.body + '\n- Check the dashboard after the deploy.',
  change_description: 'Added the post-deploy check',
});

// Many at once: each item answers on its own.
const items = await notes.createMany(
  [
    { path: 'log/2026-10-22', type: 'Log', body: 'Nightly sync: 14 records.' },
    { path: 'log/2026-10-23', type: 'Log', body: 'Nightly sync: 9 records.' },
  ],
  'Nightly sync results',
);
for (const item of items.items) if (item.status !== 'ok') console.error(item.path, item.error.message);

Every method is one op. korpus.call(name, args) reaches any of them by name, typed, with the text a model would have read beside the data:

const { data, text } = await korpus.call('check_relations', { bundle: notes.id });

Every change takes a change_description: one line, what changed and why. It is the log; nothing else records why a concept moved. Rules, paths and fields are those of the ops: Every op has each parameter, Delegations and rights the rules.

Every method

korpus is a new Korpus(); bundle is korpus.bundle(id), with the bundle id from listBundles(). why is the change description.

Files

A file (an asset) is kept beside the concept that explains it, at one path; body says what is in it, so the next reader need not open the file. uploadAsset sends the bytes straight to storage, never through Korpus, up to 100 MB; with rev it replaces the file.

const pdf = await readFile('q3-board-pack.pdf');
await notes.uploadAsset('reports/q3-board-pack', pdf, {
  filename: 'q3-board-pack.pdf',
  content_type: 'application/pdf',
  body: 'Q3 board pack. Revenue 1.2 M (+8 %), churn 2.1 %. Hiring freeze until Q1.',
  change_description: 'Filed the Q3 board pack',
});
const { bytes } = await notes.downloadAsset('reports/q3-board-pack');

Files count against their own space, apart from the space for documents, charged to whoever created the bundle (quota_exceeded, limit asset_space).

Collections and views

A collection is a folder of items that share one shape: a name (incidents), an item type (Incident), fields, required sections and a key the path is made from. The owner defines and changes it (defineCollection, updateCollection, as me), and every write of an item is checked against it (item_mismatch, wrong_path, wrong_type, not_allowed_here). A view is a saved query of one or more collections, shown as a table, list, board or tree (defineView). A delegation reads both and queries the items; a type no collection declares is queried too (type), by its values as stored.

const { collections } = await notes.schema();
const incidents = await notes.collection('incidents'); // fields, views, a blank item
const open = await notes.query({
  from: ['incidents'],
  where: [{ field: 'severity', op: 'in', value: ['high', 'critical'] }],
  sort: [{ field: 'opened', dir: 'desc' }],
  limit: 20,
});
if (open.mode === 'rows') for (const row of open.rows) console.log(row.path, row.fields);
const board = await notes.query({ view: 'open-incidents' }); // a saved view

Conditions: eq, ne, lt, lte, gt, gte, in, prefix, contains, exists, up to 10, all of which must hold. Sort by up to three fields; path ends the order. Several collections read together take only the core fields (date, status, stale_after, owner, title). group_by and aggregates answer groups or totals instead of rows. The answer's mode says which (rows, groups, totals); rows carry a cursor when there is more.

Errors and retries

A refusal throws KorpusError: status (the HTTP status; 0 when no answer came), code (stable: restricted, not_found, rev_mismatch, rate_limited, …), message (what to do, for a person), retryAfter in seconds where the server names a wait, and details. The codes are those of Errors; a key of another deployment is refused with 401 (give its URL, or let the key name it).

import { KorpusError } from '@korpus-cloud/sdk';

try {
  await notes.update('runbooks/deploy', { rev: 4, body, change_description: 'Rewrote step 3' });
} catch (error) {
  if (error instanceof KorpusError && error.code === 'rev_mismatch') {
    // read again, merge, update with the new rev
  } else throw error;
}

Writes and reads have the same short-term rates as on every way into Korpus. Over one the call is refused with rate_limited and retryAfter in seconds. new Korpus({ retries: 2 }) waits that long and sends it again. korpus.usage() says how full your document and file space is and is never refused. The ceilings every plan shares: Limits and usage.

The database pauses after a while idle. A call that meets it starting is refused with database_starting before anything ran, so the client waits retryAfter and sends the same call again, by itself, for up to wakeWait seconds all told (30 by default); an upgrade's maintenance gate is waited out alike. korpus.awaitReady() warms it up ahead of time.

Options

new Korpus(options), every one optional:

The variables: KORPUS_KEY (a delegation's key, which names its deployment), KORPUS_AUDIENCE (a trusted workload's audience), KORPUS_DELEGATION (which stored sign-in) and KORPUS_URL (which Korpus, over what the key or the audience names).

What a delegation cannot do

It is held to its rules: it works inside the bundles and paths they name, and listings leave out what it may not read. Creating, sharing, exporting or deleting bundles, defining collections and views and managing delegations stay with you: in the web app, as me over MCP, or with the korpus command.

The CLI

The SDK ships one command, korpus. Install it once: npm install -g @korpus-cloud/sdk.

As you

korpus login [--url <url>]
korpus logout

korpus login alone opens Korpus in your browser: you allow Korpus CLI to use Korpus as you, and the browser comes back to the command on 127.0.0.1. Every other command then runs as you, with your own permissions, so it can do what a delegation cannot: make and share bundles, and make delegations with their rules, keys and trusts. It never uses KORPUS_KEY, and a program's new Korpus() never picks this sign-in up. It is a connection of me on the Access page, where you revoke it.

korpus bundle list | create <name> | show | update | delete <bundle> --confirm <name>
korpus schema <bundle>
korpus collection list <bundle> | show <bundle> <collection>
korpus delegation list | create <name> [--person <@user|email>] [--rule <bundle>:<path>:<rights>]... | allow | deny | update | delete
korpus delegation received | accept <@from> <name> | leave <@from> <name>
korpus key create <delegation> --label <what for> [--days 30|90|365] [--door api|mcp]
korpus trust github <delegation> --repo <owner/name> --environment <env>
korpus trust aws <delegation> --issuer <url> --role-arn <arn>
korpus connection list [<access>] | revoke <access> <id>
korpus whoami
korpus call <tool> ['<json arguments>']

Concepts go in and out as Markdown files, laid out like an export: <path>.md, YAML frontmatter, then the body. type, title, description, tags, relations, status, stale_after and date are the concept's fields; any other key is kept as written. korpus read adds rev, the revision it read, and korpus update sends each file's rev back, so it fails with rev_mismatch if someone changed the concept since; --rev overrides it for one file.

korpus ls <bundle> [<folder>] [-r]
korpus read <bundle> <path> [-o <file.md> | --out <dir>]
korpus create <bundle> <file.md>... -m <why> [--root <dir> | --path <path>] [--type <type>]
korpus update <bundle> <file.md>... -m <why> [--root <dir> | --path <path>] [--rev <n>]
korpus delete <bundle> <path>... -m <why>

A file's concept path is the file's path under --root without .md, or --path. Several files go as one batch per 50. Every command prints what the tool answered, or with --json its data; a new key alone goes to stdout. A database still starting is waited out as the SDK does (wakeWait). The deployment: --url, else KORPUS_URL, else the one you signed in to, else production. korpus help lists every command.

As a delegation

korpus login <delegation> [--user <username>] [--url <url>]
korpus logout <delegation> [--user <username>] [--url <url>]

korpus login <delegation> signs this machine in as the delegation by device code (Connect): it prints a short code and a link, you allow it in Korpus, and the sign-in is stored in ~/.config/korpus/sign-ins.json (owner only; $XDG_CONFIG_HOME if set), refreshed at the deployment's API as it ages. new Korpus() finds it; with several stored, name one with KORPUS_DELEGATION or the delegation option. The sign-in is a connection on the Access page, where you revoke it. korpus logout forgets it on this machine. --url names any URL of the deployment when it is not production; a bare host (dev.fra.korpus.cloud) is taken as https://. A login that waits for your yes keeps asking through a dropped network until the code expires.

A sign-in made here serves the API, where the SDK calls. An MCP client such as Claude Code signs in at the delegation's MCP address itself, or sends a key.

Not on the API

Publishing a bundle to the catalog, reviewing it and the users admin are for reviewers, in the web app or as a reviewer's me; they are not listed here. Billing is the web app's own session's, listed under Only on the API. Questions: support@korpus.cloud.