Developers

Your governed knowledge, available to your other AI tools.

A contract-first REST API, signed webhooks, and a hosted MCP server — with the same audience scopes enforced identically across all three. Author once in Cairn, serve your Claude, your Copilot, your Slack bot, your internal agents.

Get an API key See the MCP server

Retrieval APIaudience-scoped

POST /v1/knowledge/search
Authorization: Bearer ath_sk_…
Content-Type: application/json

{
  "query": "how do I add a teammate",
  "audience": "customer",
  "limit": 5
}

→ 200 · chunks with source ids, guide refs, step anchors, and freshness metadata. Internal chunks are absent, not filtered — a customer-scoped key never sees them.

01 — Integration surfaces

Six ways in, all built on the same contract.

RESTPublic REST APIFull coverage of the domain — guides, articles, conversations, contacts, knowledge, credits. Every route requires a policy, and CI fails on any route without policy coverage.

RetrievalRetrieval APIAudience-scoped semantic search over your own knowledge, returning chunks with source ids, guide references and step anchors — so your own agent can cite exactly as ours does.

MCPHosted MCP serverYour governed knowledge as tools your other AI clients can call, with audience scopes enforced identically rather than reimplemented per client.

WebhooksSigned webhooksLoop events pushed to you: gap clusters, drifted guides, drafts awaiting review, conversation lifecycle. Retried with backoff and redeliverable.

OAuthOAuth app platformBuild an app other workspaces can install, scoped by the same audience and permission model rather than a bespoke one.

No-codeZapier, Make, n8nFor the integrations that do not deserve a codebase. Same events, same auth model, no server to run.

02 — Contract first

The spec is the source of truth, and the build enforces it.

Which means the documentation cannot quietly drift away from the API you are actually calling.

Read the API reference →

OpenAPI 3.1

A single specification is the source of truth for every HTTP payload. It is not generated from the code as an afterthought — the code is checked against it.

Generated clients

Client types are generated from the spec, and CI fails on drift between the two. If the docs and the API disagree, the build breaks before you find out.

Auth

Workspace-scoped API keys, hashed at rest, with audience scope attached to the key. A customer-scoped key cannot reach internal knowledge — that is enforced at retrieval, not by a filter you could bypass.

Idempotency

Write endpoints accept an idempotency key so a retry after a timeout does not create a second guide, contact, or conversation.

Errors

Structured problem responses with a machine-readable code, not a prose message you would have to string-match. Rate limits return their reset window.

03 — MCP server

The last mile: your knowledge, governed once, reachable from everywhere.

Most knowledge bases are a dead end — content goes in and only that vendor's chatbot can read it. A hosted MCP server makes the same audience-scoped knowledge available to whatever else your company runs, with the scopes enforced identically rather than reimplemented.

Exposed tools

search_knowledge

Audience-scoped semantic search returning chunks with citations and freshness metadata.

get_guide

A full guide with its ordered steps, screenshots and per-step URLs.

list_gaps

Current ranked gap clusters — useful for wiring the loop into your own planning tools.

request_capture

Issue a capture request programmatically when your own systems detect an undocumented flow.

One place to govern

Add an internal runbook once and every connected client respects its audience tag. You are not maintaining a permission model per tool.

Citations travel

Chunks carry source ids and step anchors, so an answer produced by your Claude or your Copilot can cite the guide it came from — the same way ours does.

Revocable per key

Each connection is a scoped key you can revoke without touching the others, and every query is logged against it.

04 — Widget and walkthrough

Under 120KB, and it runs on your customers’ pages — so we treat the budget as a contract.

One snippet, or a JS API if you want to drive it yourself. Identity is HMAC-signed from your backend so the agent knows what the visitor is entitled to see before it answers. The walkthrough runtime is a further chunk under 25KB, loaded only when a walkthrough actually starts.

Widget bundle: Under 120KB, static CDN delivery
Walkthrough runtime: Under 25KB, loaded on demand
Identity: HMAC-SHA256 signed server-side
Mobile: Native iOS and Android SDKs

Widget JS API

// identify the visitor — hash signed server-side
Cairn.identify({
  id: "usr_8f2c",
  email: "sofia@northwind.test",
  hash: "<hmac-sha256>"
});

// pin a guide to this screen
Cairn.pinGuide("add-a-teammate", {
  selector: "[data-test=add-member]"
});

// start a walkthrough at a given step
Cairn.walkthrough("add-a-teammate", {
  step: 3
});

// react to what happened
Cairn.on("walkthrough:complete", fn);
Cairn.on("walkthrough:stepFailed", fn);

05 — Webhooks

Signed, retried, redeliverable.

The events worth building on are the ones the loop produces — a gap detected, a guide flagged as drifted, a draft ready for review. That is where an integration adds something your team would otherwise do by hand.

knowledge.gap.clustered

A new ranked gap cluster appeared, with its sample questions and estimated value.

guide.drift.flagged

A step stopped resolving and the guide crossed its health threshold — it is now paused as an AI answer source.

article.draft.ready

Conversation mining assembled a draft from resolved conversations and it is awaiting review.

capture.request.completed

Someone recorded the guide you requested; the cluster is now linked to real content.

conversation.escalated

The agent handed off to a human, with the retrieval set and confidence score attached.

walkthrough.completed

A customer finished a walkthrough end to end — the cleanest self-serve signal available.

credits.threshold.reached

Balance crossed a threshold you set, so you can act before the agent stops answering.

Secrets are hashed at rest. Deliveries are signed, retried with backoff, and redeliverable from the dashboard — so a bad deploy on your side does not silently lose a day of events.

06 — Clients and stack

What you would be integrating with

Clients we ship

Browser extension: Manifest V3, Chrome and Edge
Desktop: Tauri 2 — Windows and macOS
Mobile SDKs: iOS and Android, native
Widget: Single snippet or JS API
Help center: Server-rendered, your domain

Platform

Application: Laravel 13 / PHP 8.5
Frontend: Vue 3, TypeScript strict, Tailwind
Data: PostgreSQL 16 + pgvector, Redis
Realtime: Laravel Reverb websockets
Domain surface: 127 models, 431 API routes

Honest limits

The docs are young, and the API is unversioned in practice.

The developer docs are young. The rendered API reference, the widget guide and the webhook reference are live at docs.cairn.how; long-form integration guides beyond that are not written yet. The OpenAPI specification remains the authoritative contract.
The API is pre-launch and we have made no backwards-compatibility promise yet. Endpoints are stable in practice, but we will not claim a versioning policy we have not had to honour.
The OAuth app platform has no public directory and no review process — installs are private today.
No SDK for the REST API in any language beyond the generated types. If you want a client library, tell us which language and it becomes a real priority rather than a guess.

Get a key and point your own agent at it.

The trial includes API access and the MCP server. If the integration you need is not there, tell us before you build a workaround.

Start free Ask an API question