REST API · v1

Build on Cairni with the REST API

Reach your wikis from any language over plain HTTPS + JSON — the same capabilities as the MCP server (read, search, compile, ask). Issue a key in Settings → Developer, then send it as a Bearer header.

Base URL: https://api.cairni.com/v1
Auth: Authorization: Bearer cairni_live_…
Format: JSON
Version: v1

The version is part of the URL (/v1). We won't make breaking changes to v1 — anything that could break existing code (removing a field, changing a response shape) ships as a new /v2 instead, so your integration keeps working.

curl

curl https://api.cairni.com/v1/me \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "user": { "id": "u_a1b2c3", "name": "Ada Lovelace", "email": "ada@example.com" },
  "livemode": true,
  "env": "live",
  "scopes": ["*"],
  "token_id": "tok_9d8e"
}

Authentication

Create a key in Settings → Developer — choose Full access or specific scopes, with an optional expiry. The key is shown once, so store it securely. Every request needs the Bearer header; session cookies are not accepted.

wiki:read
Read wikis, pages, and search.
wiki:ask
Ask grounded questions (uses credits).
wiki:write
Create wikis and edit pages.

Full access (*) grants every wiki action your account can do — but always within your own permissions, never exposing other people's private wikis. Keys can be disabled, rotated, or revoked anytime.

Identity

Check connectivity and confirm which key is calling.

GET/ping

Health check

Unauthenticated reachability check — no key required.

key onlyfree

Response

ok

boolean

Always true when reachable.

service

string

Service identifier.

version

string

API version.

GET /ping

curl https://api.cairni.com/v1/ping

200 OK

{
  "ok": true,
  "service": "cairni-developer-api",
  "version": "v1"
}

GET/me

Who am I

Returns the identity, environment, and scopes of the calling key — handy for SDK bootstrap and debugging.

key onlyfree

Response

user

object

The key owner: id, name, email.

livemode

boolean

Always true — Cairni keys are live-only.

env

string

Always "live".

scopes

string[]

Granted scopes, or ["*"] for full access.

token_id

string | null

Id of the API key making the request.

Errors

401 unauthorized

GET /me

curl https://api.cairni.com/v1/me \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "user": { "id": "u_a1b2c3", "name": "Ada Lovelace", "email": "ada@example.com" },
  "livemode": true,
  "env": "live",
  "scopes": ["wiki:read", "wiki:ask"],
  "token_id": "tok_9d8e"
}

Wikis

List, inspect, and create wikis. You only ever see your own and shared wikis.

GET/wikis

List wikis

Lists wikis you can access (your own plus shared), paginated with an opaque cursor.

wiki:readfree

Parameters

Query

cursor

string

Opaque cursor from a previous response's next_cursor.

limit

integer · default 50

Page size, 1–100.

Response

object

string

Always "list".

data

Wiki[]

The wikis on this page.

has_more

boolean

True if more results exist past next_cursor.

next_cursor

string | null

Pass as ?cursor= for the next page; null when no more.

Errors

401 unauthorized 403 forbidden

GET /wikis

curl https://api.cairni.com/v1/wikis \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "wiki",
      "slug": "product-handbook",
      "name": "Product Handbook",
      "visibility": "restricted",
      "language": "en",
      "role": "owner",
      "workspace": { "name": "Ada's workspace", "kind": "personal" },
      "page_count": 12
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/wikis/{slug}

Get a wiki

Returns a wiki's metadata. Wikis you can't access return 404 — their existence is hidden.

wiki:readfree

Parameters

Path

slugreq

string

Wiki identifier.

Response

slug

string

Wiki identifier used in paths.

name

string

Display name.

visibility

string

workspace | restricted | public.

language

string

Primary content language.

role

string | null

Your role (owner|admin|manager|editor|viewer).

workspace

object | null

Owning workspace: name, kind (personal|team).

page_count

integer

Number of pages.

home

string | null

Slug of the home/overview page, if set.

created_at

string | null

ISO-8601 creation timestamp.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}

curl https://api.cairni.com/v1/wikis/my-wiki \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "wiki",
  "slug": "product-handbook",
  "name": "Product Handbook",
  "visibility": "restricted",
  "language": "en",
  "role": "owner",
  "workspace": { "name": "Ada's workspace", "kind": "personal" },
  "page_count": 12,
  "description": "Everything about how we build.",
  "home": "overview",
  "category": "engineering",
  "created_at": "2026-06-01T09:30:00+00:00"
}

POST/wikis

Create a wiki

Creates a new wiki in your personal space — you become its manager. Free. To fill it, compile sources (below).

wiki:writefree

Parameters

Body

namereq

string

Display name for the new wiki.

description

string

Optional one-line description.

Response

…

Wiki

The created wiki (same shape as Get a wiki).

Errors

401 unauthorized 403 forbidden 422 invalid_request

POST /wikis

curl -X POST https://api.cairni.com/v1/wikis \
  -H "Authorization: Bearer cairni_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Product Handbook","description":"Everything about how we build."}'

201 Created

{
  "object": "wiki",
  "slug": "product-handbook",
  "name": "Product Handbook",
  "visibility": "restricted",
  "language": "en",
  "role": "owner",
  "workspace": { "name": "Ada's workspace", "kind": "personal" },
  "page_count": 0,
  "description": "Everything about how we build.",
  "home": null,
  "category": null,
  "created_at": "2026-06-13T10:00:00+00:00"
}

Pages

Read the compiled pages inside a wiki.

GET/wikis/{slug}/pages

List pages

Lists a wiki's pages in display order, cursor-paginated.

wiki:readfree

Parameters

Path

slugreq

string

Wiki identifier.

Query

cursor

string

Opaque cursor for the next page.

limit

integer · default 50

Page size, 1–100.

Response

data

Page[]

Page references (no body — use Get a page for the body).

has_more

boolean

True if more results exist past next_cursor.

next_cursor

string | null

Pass as ?cursor= for the next page.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}/pages

curl https://api.cairni.com/v1/wikis/my-wiki/pages \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "page",
      "slug": "getting-started",
      "title": "Getting started",
      "type": "concept",
      "summary": "A short overview of onboarding.",
      "is_home": false,
      "position": 0,
      "updated_at": "2026-06-10T12:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/wikis/{slug}/pages/{page}

Get a page

Returns a page's canonical Markdown body and metadata.

wiki:readfree

Parameters

Path

slugreq

string

Wiki identifier.

pagereq

string

Page slug.

Response

body

string

Canonical Markdown body.

wiki

string

Slug of the wiki this page belongs to.

sources

string[]

Provenance — source names cited by this page.

version

integer

Revision number.

edit_origin

string

ai | human.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}/pages/{page}

curl https://api.cairni.com/v1/wikis/my-wiki/pages/getting-started \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "page",
  "slug": "getting-started",
  "title": "Getting started",
  "type": "concept",
  "summary": "A short overview of onboarding.",
  "is_home": false,
  "position": 0,
  "updated_at": "2026-06-10T12:00:00+00:00",
  "wiki": "product-handbook",
  "body": "# Getting started\n\nWelcome to the handbook…",
  "sources": ["onboarding.pdf"],
  "version": 3,
  "edit_origin": "ai"
}

Search

Find pages by keyword across your wikis.

GET/search

Search pages

Matches page titles and summaries across accessible wikis, or a single wiki with ?wiki=slug.

wiki:readfree

Parameters

Query

q

string

Search terms (token AND match).

wiki

string

Restrict to a single wiki slug.

limit

integer · default 20

Max results, 1–50.

Response

data

SearchResult[]

Matching pages with their wiki slug.

query

string

Echo of the q parameter.

has_more

boolean

True if results were truncated at the limit.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /search

curl https://api.cairni.com/v1/search \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "search_result",
      "wiki": "product-handbook",
      "slug": "getting-started",
      "title": "Getting started",
      "summary": "A short overview of onboarding.",
      "type": "concept"
    }
  ],
  "query": "onboarding",
  "has_more": false
}

Compile

Hand Cairni a source; it compiles it into pages in the background. There is no raw page-edit endpoint — sources in, structured pages out.

POST/wikis/{slug}/sources

Compile a source

Hands a URL or text to Cairni, which compiles it into wiki pages in the background. Returns a job to poll. Requires editor access; uses workspace credits.

wiki:writecredits

Parameters

Path

slugreq

string

Wiki identifier.

Body

typereq

string

"url" or "text".

url

string

Required when type=url (http/https).

text

string

Required when type=text.

name

string

Optional label for the source.

instruction

string

Extra guidance appended to the compile prompt.

Response

source

object

The created source: name, kind, status, duplicate.

job_id

string | null

Poll GET …/jobs/{id}. Null when duplicate/synchronous.

status

string

queued | duplicate | done.

Errors

401 unauthorized 402 insufficient_credits 403 forbidden 404 not_found 422 invalid_request

POST /wikis/{slug}/sources

curl -X POST https://api.cairni.com/v1/wikis/my-wiki/sources \
  -H "Authorization: Bearer cairni_live_…" \
  -H "Content-Type: application/json" \
  -d '{"type":"url","url":"https://example.com/post","name":"Launch post"}'

202 Accepted

{
  "object": "ingest",
  "wiki": "product-handbook",
  "source": {
    "name": "Launch post",
    "kind": "url",
    "status": "queued",
    "duplicate": false
  },
  "job_id": "job_3f9c",
  "status": "queued"
}

POST/wikis/{slug}/sources/audio

Compile an audio recording

Upload an audio file (multipart/form-data). Cairni transcribes and diarizes it, then compiles the transcript into pages — all in the background. Poll the returned job_id through transcribing → compiling → done.

wiki:writecredits

Parameters

Path

slugreq

string

Wiki identifier.

Body

filereq

file

The audio file (multipart/form-data): .mp3, .m4a, .wav, .webm…

name

string

Optional label for the recording.

participants

string

Comma-separated participant names, used to seed speaker labels.

instruction

string

Extra guidance appended to the compile prompt.

Response

job_id

string

Poll GET …/jobs/{job_id}; it reports transcribing → compiling → done with compiled_pages.

status

string

Starts at "transcribing".

Errors

401 unauthorized 402 insufficient_credits 403 forbidden 404 not_found 413 422 invalid_request

POST /wikis/{slug}/sources/audio

curl -X POST https://api.cairni.com/v1/wikis/my-wiki/sources/audio \
  -H "Authorization: Bearer cairni_live_…" \
  -F "file=@meeting.mp3" \
  -F "name=Standup" \
  -F "participants=Ada,Bob"

202 Accepted

{
  "object": "ingest",
  "wiki": "product-handbook",
  "source": { "name": "Standup", "kind": "audio", "status": "transcribing", "duplicate": false },
  "job_id": "src_9a8b",
  "status": "transcribing"
}

GET/wikis/{slug}/jobs

List compile jobs

Lists this wiki's recent compile jobs, newest first.

wiki:writefree

Parameters

Path

slugreq

string

Wiki identifier.

Query

limit

integer · default 20

Max jobs, 1–100.

Response

data

Job[]

Recent jobs (same shape as Get a job).

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}/jobs

curl https://api.cairni.com/v1/wikis/my-wiki/jobs \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "job",
      "id": "job_3f9c",
      "status": "running",
      "phase": "compile",
      "progress": 60,
      "total": 5,
      "done": 3,
      "compiled_pages": ["intro", "setup"],
      "detail": "compiling 'setup'",
      "source_id": "src_77ab"
    }
  ]
}

GET/wikis/{slug}/jobs/{job_id}

Get a compile job

Returns a compile job's status, phase, progress, and the pages written so far. Poll until status is "done".

wiki:writefree

Parameters

Path

slugreq

string

Wiki identifier.

job_idreq

string

Job id from Compile a source.

Response

status

string

queued | running | done | failed.

phase

string

progress

integer

0–100.

compiled_pages

string[]

Slugs of pages written so far.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}/jobs/{job_id}

curl https://api.cairni.com/v1/wikis/my-wiki/jobs/job_3f9c \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "job",
  "id": "job_3f9c",
  "status": "done",
  "phase": "done",
  "progress": 100,
  "total": 3,
  "done": 3,
  "compiled_pages": ["intro", "setup", "faq"],
  "detail": "",
  "source_id": "src_77ab"
}

Ask

Ask a question and get an answer grounded in the wiki, with citations.

POST/wikis/{slug}/ask

Ask a question

Answers a question grounded in the wiki, citing the pages used. Refuses (refused=true) when the wiki has no grounding. Uses workspace credits.

wiki:askcredits

Parameters

Path

slugreq

string

Wiki identifier.

Body

questionreq

string

Natural-language question to answer from the wiki.

Response

answer

string

The grounded answer.

refused

boolean

True if the wiki had no grounding to answer.

reason

string

Why it refused (empty on success).

cited_pages

string[]

Page slugs the answer is grounded in.

cited_sources

string[]

Source names cited.

Errors

401 unauthorized 402 insufficient_credits 403 forbidden 404 not_found 422 invalid_request

POST /wikis/{slug}/ask

curl -X POST https://api.cairni.com/v1/wikis/my-wiki/ask \
  -H "Authorization: Bearer cairni_live_…" \
  -H "Content-Type: application/json" \
  -d '{"question":"What changed in v2?"}'

200 OK

{
  "object": "answer",
  "wiki": "product-handbook",
  "question": "What changed in v2?",
  "answer": "v2 added cursor pagination and a structured error model.",
  "refused": false,
  "reason": "",
  "cited_pages": ["changelog", "api-v2"],
  "cited_sources": []
}

Errors

Every non-2xx response returns the same JSON shape plus an X-Request-Id header. Branch on error.type (a stable contract), never on the message text or the HTTP status alone.

Error body

error.type

string

Stable, machine-readable category — branch on this, not the message.

error.message

string

Human-readable explanation; may name the offending field.

error.request_id

string

Same value as the X-Request-Id response header — quote it in bug reports.

404 Not Found

{
  "error": {
    "type": "not_found",
    "message": "Notebook not found",
    "request_id": "req_8f3c1a"
  }
}

401unauthorizedAuthentication failed

The Authorization header is missing or malformed, or the key is invalid, disabled, or expired. Send a valid `Authorization: Bearer cairni_live_…` key — session cookies are not accepted on the API. Rotate or re-issue the key in Settings → Developer if needed.

402insufficient_creditsOut of credits

The wiki's workspace has no credits left for a paid action (compiling a source, or ask). The error body includes `needed` and `available`. Top up credits or upgrade the plan — reads are always free, so this only affects POST …/sources and POST …/ask.

403forbiddenScope or permission denied

The key is valid but isn't allowed to do this. Either it lacks the required scope (e.g. a read-only key calling a write endpoint — check GET /me's scopes), or your role on the wiki is too low: compiling needs editor access or higher. Use a key with the right scope, or get edit access to the wiki.

404not_foundNot found — or hidden

The wiki, page, or job doesn't exist, or you can't access it. To avoid leaking which wikis exist, Cairni returns 404 (not 403) for wikis you can't access — so a 404 can mean "it exists, but it isn't yours". Double-check the slug and that the key's owner has access.

422invalid_requestInvalid request

The request body or query parameters didn't validate — a missing required field, an unknown `type`, a non-http(s) URL, empty text, or a `limit` out of range. The `message` names the offending field so you can fix it and retry.

429rate_limitedToo many requests

You're sending requests too fast, or too many compile jobs are already running for your account. Back off and retry after a short wait, and let in-flight jobs finish (poll GET …/jobs/{id}) before starting more.

Prefer a ready-made client integration (Claude Code, Cursor, Codex)? The same capabilities are available over MCP — see the MCP server guide below.

Model Context Protocol

Use your Cairni wikis in any AI client

Cairni exposes an MCP server, so clients like Claude, Cursor, and Codex can search, read, ask, and even compile into your wikis — your own and the ones shared with you. Connect once with OAuth, no copy-pasting tokens.

Your wikis

Cairni MCP

Claude Code

Endpoint: https://mcp.cairni.com/
Transport: Streamable HTTP
Auth: OAuth 2.1 · dynamic client registration · or PAT

Connect with OAuth (recommended)

The fastest way — your browser opens a consent screen and you click Allow.

Add the server

In Claude Code, run:

shell

claude mcp add --transport http cairni https://mcp.cairni.com/

Authorize in the browser

A Cairni page opens. Log in if needed, review the requested access, and click Allow.

Done

Your client now has tools like list_wikis, search, ask, and put_page.

Claude Desktop and claude.ai (Team / Enterprise): add Cairni under Settings → Connectors with the same URL — you'll get the same Allow screen.

Connect with a token

For scripts, CI, or clients without OAuth — use a personal access token (PAT).

Create a token

In Cairni, go to Settings → Developer, pick scopes (read / ask / write), and copy it once.

Add it as a header

shell

claude mcp add --transport http cairni https://mcp.cairni.com/ \
  --header "Authorization: Bearer cairni_live_…"

Or in claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "cairni": {
      "type": "http",
      "url": "https://mcp.cairni.com/",
      "headers": { "Authorization": "Bearer cairni_live_…" }
    }
  }
}

Other clients

Cairni speaks the standard remote-MCP protocol, so any MCP-capable client connects to the same endpoint. Clients that only support local (stdio) servers can use the mcp-remote bridge, which runs the OAuth flow for you.

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "cairni": { "url": "https://mcp.cairni.com/" }
  }
}

Or open Settings → MCP → Add new server. Authorize with OAuth on first use.

Codex

shell

codex mcp add cairni --url https://mcp.cairni.com/

First-time rmcp setup: add experimental_use_rmcp_client = true under [features] in ~/.codex/config.toml, then run codex mcp login cairni.

VS Code · Windsurf · Zed · others

shell

npx -y mcp-remote https://mcp.cairni.com/

For any client that only supports local (stdio) servers, register this as the command (command: npx, args: -y mcp-remote <url>). The bridge opens the OAuth consent in your browser, then relays the tools.

Tools

Every tool runs with your permissions — you only ever see your own and shared wikis.

Tool	What it does	Scope	Cost
list_wikis	List wikis you can access	wiki:read	free
read_page	Read a page's Markdown	wiki:read	free
search	Search across your wikis	wiki:read	free
ask	Grounded Q&A with citations	wiki:ask	credits
put_page	Write a page directly (raw)	wiki:write	free
create_wiki	Create a new wiki	wiki:write	free
ingest	Hand sources to Cairni to compile	wiki:write	credits

put_page writes Markdown your client composed — no Cairni AI runs, so it's free. ask and ingest use Cairni's LLM and draw from the wiki's workspace credits.

Scopes & security

wiki:read
Read wikis, pages, and search.
wiki:ask
Ask grounded questions (uses credits).
wiki:write
Create wikis and edit pages.

Tokens are scoped and revocable — manage or revoke them anytime in Settings → Developer. OAuth uses PKCE and a consent screen; we never expose other people's private wikis.

Ready to connect?

Create a token or open Cairni to get started.

REST API · v1

Build on Cairni with the REST API

Base URL: https://api.cairni.com/v1
Auth: Authorization: Bearer cairni_live_…
Format: JSON
Version: v1

curl

curl https://api.cairni.com/v1/me \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "user": { "id": "u_a1b2c3", "name": "Ada Lovelace", "email": "ada@example.com" },
  "livemode": true,
  "env": "live",
  "scopes": ["*"],
  "token_id": "tok_9d8e"
}

Authentication

wiki:read
Read wikis, pages, and search.
wiki:ask
Ask grounded questions (uses credits).
wiki:write
Create wikis and edit pages.

Identity

Check connectivity and confirm which key is calling.

GET/ping

Health check

Unauthenticated reachability check — no key required.

key onlyfree

Response

ok

boolean

Always true when reachable.

service

string

Service identifier.

version

string

API version.

GET /ping

curl https://api.cairni.com/v1/ping

200 OK

{
  "ok": true,
  "service": "cairni-developer-api",
  "version": "v1"
}

GET/me

Who am I

Returns the identity, environment, and scopes of the calling key — handy for SDK bootstrap and debugging.

key onlyfree

Response

user

object

The key owner: id, name, email.

livemode

boolean

Always true — Cairni keys are live-only.

env

string

Always "live".

scopes

string[]

Granted scopes, or ["*"] for full access.

token_id

string | null

Id of the API key making the request.

Errors

401 unauthorized

GET /me

curl https://api.cairni.com/v1/me \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "user": { "id": "u_a1b2c3", "name": "Ada Lovelace", "email": "ada@example.com" },
  "livemode": true,
  "env": "live",
  "scopes": ["wiki:read", "wiki:ask"],
  "token_id": "tok_9d8e"
}

Wikis

List, inspect, and create wikis. You only ever see your own and shared wikis.

GET/wikis

List wikis

Lists wikis you can access (your own plus shared), paginated with an opaque cursor.

wiki:readfree

Parameters

Query

cursor

string

Opaque cursor from a previous response's next_cursor.

limit

integer · default 50

Page size, 1–100.

Response

object

string

Always "list".

data

Wiki[]

The wikis on this page.

has_more

boolean

True if more results exist past next_cursor.

next_cursor

string | null

Pass as ?cursor= for the next page; null when no more.

Errors

401 unauthorized 403 forbidden

GET /wikis

curl https://api.cairni.com/v1/wikis \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "wiki",
      "slug": "product-handbook",
      "name": "Product Handbook",
      "visibility": "restricted",
      "language": "en",
      "role": "owner",
      "workspace": { "name": "Ada's workspace", "kind": "personal" },
      "page_count": 12
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/wikis/{slug}

Get a wiki

Returns a wiki's metadata. Wikis you can't access return 404 — their existence is hidden.

wiki:readfree

Parameters

Path

slugreq

string

Wiki identifier.

Response

slug

string

Wiki identifier used in paths.

name

string

Display name.

visibility

string

workspace | restricted | public.

language

string

Primary content language.

role

string | null

Your role (owner|admin|manager|editor|viewer).

workspace

object | null

Owning workspace: name, kind (personal|team).

page_count

integer

Number of pages.

home

string | null

Slug of the home/overview page, if set.

created_at

string | null

ISO-8601 creation timestamp.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}

curl https://api.cairni.com/v1/wikis/my-wiki \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "wiki",
  "slug": "product-handbook",
  "name": "Product Handbook",
  "visibility": "restricted",
  "language": "en",
  "role": "owner",
  "workspace": { "name": "Ada's workspace", "kind": "personal" },
  "page_count": 12,
  "description": "Everything about how we build.",
  "home": "overview",
  "category": "engineering",
  "created_at": "2026-06-01T09:30:00+00:00"
}

POST/wikis

Create a wiki

Creates a new wiki in your personal space — you become its manager. Free. To fill it, compile sources (below).

wiki:writefree

Parameters

Body

namereq

string

Display name for the new wiki.

description

string

Optional one-line description.

Response

…

Wiki

The created wiki (same shape as Get a wiki).

Errors

401 unauthorized 403 forbidden 422 invalid_request

POST /wikis

curl -X POST https://api.cairni.com/v1/wikis \
  -H "Authorization: Bearer cairni_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Product Handbook","description":"Everything about how we build."}'

201 Created

{
  "object": "wiki",
  "slug": "product-handbook",
  "name": "Product Handbook",
  "visibility": "restricted",
  "language": "en",
  "role": "owner",
  "workspace": { "name": "Ada's workspace", "kind": "personal" },
  "page_count": 0,
  "description": "Everything about how we build.",
  "home": null,
  "category": null,
  "created_at": "2026-06-13T10:00:00+00:00"
}

Pages

Read the compiled pages inside a wiki.

GET/wikis/{slug}/pages

List pages

Lists a wiki's pages in display order, cursor-paginated.

wiki:readfree

Parameters

Path

slugreq

string

Wiki identifier.

Query

cursor

string

Opaque cursor for the next page.

limit

integer · default 50

Page size, 1–100.

Response

data

Page[]

Page references (no body — use Get a page for the body).

has_more

boolean

True if more results exist past next_cursor.

next_cursor

string | null

Pass as ?cursor= for the next page.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}/pages

curl https://api.cairni.com/v1/wikis/my-wiki/pages \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "page",
      "slug": "getting-started",
      "title": "Getting started",
      "type": "concept",
      "summary": "A short overview of onboarding.",
      "is_home": false,
      "position": 0,
      "updated_at": "2026-06-10T12:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/wikis/{slug}/pages/{page}

Get a page

Returns a page's canonical Markdown body and metadata.

wiki:readfree

Parameters

Path

slugreq

string

Wiki identifier.

pagereq

string

Page slug.

Response

body

string

Canonical Markdown body.

wiki

string

Slug of the wiki this page belongs to.

sources

string[]

Provenance — source names cited by this page.

version

integer

Revision number.

edit_origin

string

ai | human.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}/pages/{page}

curl https://api.cairni.com/v1/wikis/my-wiki/pages/getting-started \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "page",
  "slug": "getting-started",
  "title": "Getting started",
  "type": "concept",
  "summary": "A short overview of onboarding.",
  "is_home": false,
  "position": 0,
  "updated_at": "2026-06-10T12:00:00+00:00",
  "wiki": "product-handbook",
  "body": "# Getting started\n\nWelcome to the handbook…",
  "sources": ["onboarding.pdf"],
  "version": 3,
  "edit_origin": "ai"
}

Search

Find pages by keyword across your wikis.

GET/search

Search pages

Matches page titles and summaries across accessible wikis, or a single wiki with ?wiki=slug.

wiki:readfree

Parameters

Query

q

string

Search terms (token AND match).

wiki

string

Restrict to a single wiki slug.

limit

integer · default 20

Max results, 1–50.

Response

data

SearchResult[]

Matching pages with their wiki slug.

query

string

Echo of the q parameter.

has_more

boolean

True if results were truncated at the limit.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /search

curl https://api.cairni.com/v1/search \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "search_result",
      "wiki": "product-handbook",
      "slug": "getting-started",
      "title": "Getting started",
      "summary": "A short overview of onboarding.",
      "type": "concept"
    }
  ],
  "query": "onboarding",
  "has_more": false
}

Compile

Hand Cairni a source; it compiles it into pages in the background. There is no raw page-edit endpoint — sources in, structured pages out.

POST/wikis/{slug}/sources

Compile a source

Hands a URL or text to Cairni, which compiles it into wiki pages in the background. Returns a job to poll. Requires editor access; uses workspace credits.

wiki:writecredits

Parameters

Path

slugreq

string

Wiki identifier.

Body

typereq

string

"url" or "text".

url

string

Required when type=url (http/https).

text

string

Required when type=text.

name

string

Optional label for the source.

instruction

string

Extra guidance appended to the compile prompt.

Response

source

object

The created source: name, kind, status, duplicate.

job_id

string | null

Poll GET …/jobs/{id}. Null when duplicate/synchronous.

status

string

queued | duplicate | done.

Errors

401 unauthorized 402 insufficient_credits 403 forbidden 404 not_found 422 invalid_request

POST /wikis/{slug}/sources

curl -X POST https://api.cairni.com/v1/wikis/my-wiki/sources \
  -H "Authorization: Bearer cairni_live_…" \
  -H "Content-Type: application/json" \
  -d '{"type":"url","url":"https://example.com/post","name":"Launch post"}'

202 Accepted

{
  "object": "ingest",
  "wiki": "product-handbook",
  "source": {
    "name": "Launch post",
    "kind": "url",
    "status": "queued",
    "duplicate": false
  },
  "job_id": "job_3f9c",
  "status": "queued"
}

POST/wikis/{slug}/sources/audio

Compile an audio recording

wiki:writecredits

Parameters

Path

slugreq

string

Wiki identifier.

Body

filereq

file

The audio file (multipart/form-data): .mp3, .m4a, .wav, .webm…

name

string

Optional label for the recording.

participants

string

Comma-separated participant names, used to seed speaker labels.

instruction

string

Extra guidance appended to the compile prompt.

Response

job_id

string

Poll GET …/jobs/{job_id}; it reports transcribing → compiling → done with compiled_pages.

status

string

Starts at "transcribing".

Errors

401 unauthorized 402 insufficient_credits 403 forbidden 404 not_found 413 422 invalid_request

POST /wikis/{slug}/sources/audio

curl -X POST https://api.cairni.com/v1/wikis/my-wiki/sources/audio \
  -H "Authorization: Bearer cairni_live_…" \
  -F "file=@meeting.mp3" \
  -F "name=Standup" \
  -F "participants=Ada,Bob"

202 Accepted

{
  "object": "ingest",
  "wiki": "product-handbook",
  "source": { "name": "Standup", "kind": "audio", "status": "transcribing", "duplicate": false },
  "job_id": "src_9a8b",
  "status": "transcribing"
}

GET/wikis/{slug}/jobs

List compile jobs

Lists this wiki's recent compile jobs, newest first.

wiki:writefree

Parameters

Path

slugreq

string

Wiki identifier.

Query

limit

integer · default 20

Max jobs, 1–100.

Response

data

Job[]

Recent jobs (same shape as Get a job).

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}/jobs

curl https://api.cairni.com/v1/wikis/my-wiki/jobs \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "job",
      "id": "job_3f9c",
      "status": "running",
      "phase": "compile",
      "progress": 60,
      "total": 5,
      "done": 3,
      "compiled_pages": ["intro", "setup"],
      "detail": "compiling 'setup'",
      "source_id": "src_77ab"
    }
  ]
}

GET/wikis/{slug}/jobs/{job_id}

Get a compile job

Returns a compile job's status, phase, progress, and the pages written so far. Poll until status is "done".

wiki:writefree

Parameters

Path

slugreq

string

Wiki identifier.

job_idreq

string

Job id from Compile a source.

Response

status

string

queued | running | done | failed.

phase

string

progress

integer

0–100.

compiled_pages

string[]

Slugs of pages written so far.

Errors

401 unauthorized 403 forbidden 404 not_found

GET /wikis/{slug}/jobs/{job_id}

curl https://api.cairni.com/v1/wikis/my-wiki/jobs/job_3f9c \
  -H "Authorization: Bearer cairni_live_…"

200 OK

{
  "object": "job",
  "id": "job_3f9c",
  "status": "done",
  "phase": "done",
  "progress": 100,
  "total": 3,
  "done": 3,
  "compiled_pages": ["intro", "setup", "faq"],
  "detail": "",
  "source_id": "src_77ab"
}

Ask

Ask a question and get an answer grounded in the wiki, with citations.

POST/wikis/{slug}/ask

Ask a question

Answers a question grounded in the wiki, citing the pages used. Refuses (refused=true) when the wiki has no grounding. Uses workspace credits.

wiki:askcredits

Parameters

Path

slugreq

string

Wiki identifier.

Body

questionreq

string

Natural-language question to answer from the wiki.

Response

answer

string

The grounded answer.

refused

boolean

True if the wiki had no grounding to answer.

reason

string

Why it refused (empty on success).

cited_pages

string[]

Page slugs the answer is grounded in.

cited_sources

string[]

Source names cited.

Errors

401 unauthorized 402 insufficient_credits 403 forbidden 404 not_found 422 invalid_request

POST /wikis/{slug}/ask

curl -X POST https://api.cairni.com/v1/wikis/my-wiki/ask \
  -H "Authorization: Bearer cairni_live_…" \
  -H "Content-Type: application/json" \
  -d '{"question":"What changed in v2?"}'

200 OK

{
  "object": "answer",
  "wiki": "product-handbook",
  "question": "What changed in v2?",
  "answer": "v2 added cursor pagination and a structured error model.",
  "refused": false,
  "reason": "",
  "cited_pages": ["changelog", "api-v2"],
  "cited_sources": []
}

Errors

Every non-2xx response returns the same JSON shape plus an X-Request-Id header. Branch on error.type (a stable contract), never on the message text or the HTTP status alone.

Error body

error.type

string

Stable, machine-readable category — branch on this, not the message.

error.message

string

Human-readable explanation; may name the offending field.

error.request_id

string

Same value as the X-Request-Id response header — quote it in bug reports.

404 Not Found

{
  "error": {
    "type": "not_found",
    "message": "Notebook not found",
    "request_id": "req_8f3c1a"
  }
}

401unauthorizedAuthentication failed

402insufficient_creditsOut of credits

403forbiddenScope or permission denied

404not_foundNot found — or hidden

422invalid_requestInvalid request

429rate_limitedToo many requests

Prefer a ready-made client integration (Claude Code, Cursor, Codex)? The same capabilities are available over MCP — see the MCP server guide below.

Model Context Protocol

Use your Cairni wikis in any AI client

Your wikis

Cairni MCP

Claude Code

Endpoint: https://mcp.cairni.com/
Transport: Streamable HTTP
Auth: OAuth 2.1 · dynamic client registration · or PAT

Connect with OAuth (recommended)

The fastest way — your browser opens a consent screen and you click Allow.

Add the server

In Claude Code, run:

shell

claude mcp add --transport http cairni https://mcp.cairni.com/

Authorize in the browser

A Cairni page opens. Log in if needed, review the requested access, and click Allow.

Done

Your client now has tools like list_wikis, search, ask, and put_page.

Claude Desktop and claude.ai (Team / Enterprise): add Cairni under Settings → Connectors with the same URL — you'll get the same Allow screen.

Connect with a token

For scripts, CI, or clients without OAuth — use a personal access token (PAT).

Create a token

In Cairni, go to Settings → Developer, pick scopes (read / ask / write), and copy it once.

Add it as a header

shell

claude mcp add --transport http cairni https://mcp.cairni.com/ \
  --header "Authorization: Bearer cairni_live_…"

Or in claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "cairni": {
      "type": "http",
      "url": "https://mcp.cairni.com/",
      "headers": { "Authorization": "Bearer cairni_live_…" }
    }
  }
}

Other clients

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "cairni": { "url": "https://mcp.cairni.com/" }
  }
}

Or open Settings → MCP → Add new server. Authorize with OAuth on first use.

Codex

shell

codex mcp add cairni --url https://mcp.cairni.com/

First-time rmcp setup: add experimental_use_rmcp_client = true under [features] in ~/.codex/config.toml, then run codex mcp login cairni.

VS Code · Windsurf · Zed · others

shell

npx -y mcp-remote https://mcp.cairni.com/

Tools

Every tool runs with your permissions — you only ever see your own and shared wikis.

Tool	What it does	Scope	Cost
list_wikis	List wikis you can access	wiki:read	free
read_page	Read a page's Markdown	wiki:read	free
search	Search across your wikis	wiki:read	free
ask	Grounded Q&A with citations	wiki:ask	credits
put_page	Write a page directly (raw)	wiki:write	free
create_wiki	Create a new wiki	wiki:write	free
ingest	Hand sources to Cairni to compile	wiki:write	credits

put_page writes Markdown your client composed — no Cairni AI runs, so it's free. ask and ingest use Cairni's LLM and draw from the wiki's workspace credits.

Scopes & security

wiki:read
Read wikis, pages, and search.
wiki:ask
Ask grounded questions (uses credits).
wiki:write
Create wikis and edit pages.

Tokens are scoped and revocable — manage or revoke them anytime in Settings → Developer. OAuth uses PKCE and a consent screen; we never expose other people's private wikis.

Ready to connect?

Create a token or open Cairni to get started.