REST API · v1

REST API で Cairni を使う

あらゆる言語から HTTPS + JSON でウィキにアクセス — MCP サーバーと同じ機能(閲覧・検索・編纂・質問)。設定 → Developer でキーを発行し、Bearer ヘッダーで送ります。

ベース URL: https://api.cairni.com/v1
認証: Authorization: Bearer cairni_live_…
フォーマット: JSON
バージョン: v1

バージョンは URL の一部です(/v1)。v1 には後方互換を壊す変更は加えません — 既存コードを壊しうる変更(フィールド削除、レスポンス形状の変更など)は v1 ではなく新しい /v2 として出すため、あなたの統合は動き続けます。

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"
}

認証

設定 → Developer でキーを作成 — フルアクセスまたは特定のスコープを選び、有効期限は任意。キーは一度だけ表示されるため安全に保管してください。すべてのリクエストに Bearer ヘッダーが必要で、セッションクッキーは受け付けません。

wiki:read
ウィキ・ページの閲覧・検索。
wiki:ask
根拠ある質問(クレジット使用)。
wiki:write
ウィキ作成・ページ編集。

フルアクセス(*)はアカウントが可能なすべてのウィキ操作を許可しますが、常に自分の権限内でのみ動作し、他人の非公開ウィキは決して公開しません。キーはいつでも無効化・ローテーション・失効できます。

アイデンティティ

接続確認と、呼び出し中のキー情報の確認。

GET/ping

ヘルスチェック

認証なしの到達確認 — キー不要。

キーのみ無料

レスポンス

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

キー情報

呼び出したキーの ID・環境・スコープを返す — SDK 初期化やデバッグに便利。

キーのみ無料

レスポンス

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.

エラー

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"
}

ウィキ

ウィキの一覧・取得・作成。自分と共有されたウィキだけが見えます。

GET/wikis

ウィキ一覧

アクセス可能なウィキ(自分・共有)を不透明な cursor でページネーションして返す。

wiki:read無料

パラメータ

クエリ

cursor

string

Opaque cursor from a previous response's next_cursor.

limit

integer · default 50

Page size, 1–100.

レスポンス

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.

エラー

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}

ウィキ取得

ウィキのメタデータを返す。アクセス不可のウィキは 404(存在を隠す)。

wiki:read無料

パラメータ

パス

slugreq

string

Wiki identifier.

レスポンス

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.

エラー

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

ウィキ作成

個人スペースに新しいウィキを作成 — あなたが manager になります。無料。中身はソース編纂(下)で埋めます。

wiki:write無料

パラメータ

ボディ

namereq

string

Display name for the new wiki.

description

string

Optional one-line description.

レスポンス

…

Wiki

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

エラー

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"
}

ページ

ウィキ内に編纂されたページを読みます。

GET/wikis/{slug}/pages

ページ一覧

ウィキのページを表示順に cursor ページネーションして返す。

wiki:read無料

パラメータ

パス

slugreq

string

Wiki identifier.

クエリ

cursor

string

Opaque cursor for the next page.

limit

integer · default 50

Page size, 1–100.

レスポンス

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.

エラー

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}

ページ取得

ページの正本 Markdown 本文とメタデータを返す。

wiki:read無料

パラメータ

パス

slugreq

string

Wiki identifier.

pagereq

string

Page slug.

レスポンス

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.

エラー

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"
}

検索

キーワードでウィキ全体からページを探します。

GET/search

ページ検索

アクセス可能なウィキ全体(または ?wiki=slug 限定)でタイトル・要約をマッチ。

wiki:read無料

パラメータ

クエリ

q

string

Search terms (token AND match).

wiki

string

Restrict to a single wiki slug.

limit

integer · default 20

Max results, 1–50.

レスポンス

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.

エラー

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
}

編纂

ソースを渡すと Cairni がバックグラウンドでページに編纂します。ページ直接編集のエンドポイントはありません — ソースを入れ、構造化されたページを受け取ります。

POST/wikis/{slug}/sources

ソース編纂

URL またはテキストを渡すとバックグラウンドでページを編纂し、ポーリング用の job を返します。editor 権限が必要・クレジット使用。

wiki:writeクレジット

パラメータ

パス

slugreq

string

Wiki identifier.

ボディ

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.

レスポンス

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.

エラー

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

音声を編纂

音声ファイルを multipart/form-data でアップロード。Cairni が文字起こし・話者分離し、文字起こしをページに編纂します — すべてバックグラウンド。返された job_id を transcribing → compiling → done までポーリング。

wiki:writeクレジット

パラメータ

パス

slugreq

string

Wiki identifier.

ボディ

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.

レスポンス

job_id

string

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

status

string

Starts at "transcribing".

エラー

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

編纂ジョブ一覧

このウィキの最近の編纂ジョブを新しい順に返す。

wiki:write無料

パラメータ

パス

slugreq

string

Wiki identifier.

クエリ

limit

integer · default 20

Max jobs, 1–100.

レスポンス

data

Job[]

Recent jobs (same shape as Get a job).

エラー

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}

編纂ジョブ取得

編纂ジョブの status・phase・progress・作成済みページを返す。status が "done" になるまでポーリング。

wiki:write無料

パラメータ

パス

slugreq

string

Wiki identifier.

job_idreq

string

Job id from Compile a source.

レスポンス

status

string

queued | running | done | failed.

phase

string

progress

integer

0–100.

compiled_pages

string[]

Slugs of pages written so far.

エラー

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"
}

質問

質問すると、ウィキに基づいた回答を引用付きで受け取ります。

POST/wikis/{slug}/ask

質問する

ウィキに基づいて回答し、使用したページを引用します。根拠がない場合は拒否(refused=true)。クレジット使用。

wiki:askクレジット

パラメータ

パス

slugreq

string

Wiki identifier.

ボディ

questionreq

string

Natural-language question to answer from the wiki.

レスポンス

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.

エラー

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": []
}

エラー

すべての非 2xx 応答は同じ JSON 形式と X-Request-Id ヘッダーを返します。分岐はメッセージ文や HTTP ステータスではなく error.type(安定した契約)で行ってください。

エラーボディ

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"
  }
}

401unauthorized認証失敗

Authorization ヘッダーがない・形式が不正、またはキーが無効・無効化・期限切れです。有効な `Authorization: Bearer cairni_live_…` キーを送ってください — API はセッションクッキーを受け付けません。必要なら設定 → Developer でキーをローテーション・再発行してください。

402insufficient_creditsクレジット不足

そのウィキのワークスペースに有料アクション(ソース編纂・ask)用のクレジットがありません。エラーボディに `needed`・`available` が含まれます。チャージまたはプランをアップグレードしてください — 読み取りは常に無料なので、このエラーは POST …/sources と POST …/ask のみで発生します。

403forbiddenスコープ・権限拒否

キーは有効ですが、この操作は許可されていません。必要なスコープがない(例: 読み取り専用キーで書き込み呼び出し — GET /me の scopes を確認)、またはウィキでの役割が不足しています: 編纂には editor 以上が必要です。適切なスコープのキーを使うか、そのウィキの編集権限を取得してください。

404not_found存在しない — または非表示

ウィキ・ページ・ジョブが存在しないか、アクセスできません。どのウィキが存在するかを漏らさないため、Cairni はアクセス不可のウィキに 403 ではなく 404 を返します — そのため 404 は「存在するがあなたのものではない」場合があります。slug とキー所有者のアクセス権を再確認してください。

422invalid_request不正なリクエスト

リクエストボディまたはクエリパラメータの検証に失敗 — 必須フィールドの欠落、不明な `type`、http(s) でない URL、空のテキスト、範囲外の `limit` など。`message` が問題のフィールドを示すので、修正して再試行してください。

429rate_limitedリクエスト過多

リクエストが速すぎるか、アカウントで進行中の編纂ジョブが多すぎます。少し待って再試行し、進行中のジョブが終わるまで(GET …/jobs/{id} をポーリング)待ってから新しく開始してください。

すぐ使えるクライアント連携(Claude Code・Cursor・Codex)がよいですか? 同じ機能を MCP でも提供しています — 下の MCP サーバーガイドをご覧ください。

Model Context Protocol

Cairni のウィキをあらゆる AI クライアントで

Cairni は MCP サーバーを公開しています。Claude・Cursor・Codex などのクライアントが、あなたのウィキ(自分 + 共有されたもの)を検索・閲覧・質問し、編纂まで行えます。OAuth で一度つなげば、トークンのコピペも不要です。

あなたのウィキ

Cairni MCP

Claude Code

エンドポイント: https://mcp.cairni.com/
トランスポート: Streamable HTTP
認証: OAuth 2.1 · 動的クライアント登録 · または PAT

OAuth で接続(推奨)

最速の方法 — ブラウザに同意画面が出て「許可」を押すだけ。

サーバーを追加

Claude Code で実行:

shell

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

ブラウザで承認

Cairni のページが開きます。必要ならログインし、要求された権限を確認して「許可」を押します。

完了

クライアントに list_wikis・search・ask・put_page などのツールが追加されます。

Claude Desktop・claude.ai(Team / Enterprise): 設定 → コネクタで同じ URL を追加すると、同じ「許可」画面が表示されます。

トークンで接続

スクリプト・CI・OAuth 非対応クライアント用 — 個人アクセストークン(PAT)を使います。

トークンを発行

Cairni の設定 → Developer でスコープ(読み取り / 質問 / 書き込み)を選び、一度コピーします。

ヘッダーとして追加

shell

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

または claude_desktop_config.json に:

claude_desktop_config.json

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

他のクライアント

Cairni は標準のリモート MCP プロトコルに準拠 — MCP 対応クライアントなら同じエンドポイントに接続できます。ローカル(stdio)サーバーのみ対応のクライアントは mcp-remote ブリッジが OAuth フローを代行します。

Cursor

~/.cursor/mcp.json

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

または設定 → MCP → 新しいサーバーを追加。初回に OAuth で承認します。

Codex

shell

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

初回の rmcp 設定: ~/.codex/config.toml の [features] に experimental_use_rmcp_client = true を追加し、codex mcp login cairni を実行。

VS Code · Windsurf · Zed · others

shell

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

ローカル(stdio)サーバーのみ対応のクライアントは、これをコマンドとして登録します(command: npx, args: -y mcp-remote <url>)。ブリッジがブラウザで OAuth 同意を開き、ツールを中継します。

ツール

すべてのツールはあなたの権限で動作 — 自分と共有されたウィキだけが見えます。

ツール	機能	スコープ	コスト
list_wikis	アクセス可能なウィキ一覧	wiki:read	無料
read_page	ページの Markdown を読む	wiki:read	無料
search	ウィキを横断検索	wiki:read	無料
ask	出典付きの根拠ある回答	wiki:ask	クレジット
put_page	ページを直接書き込み(raw)	wiki:write	無料
create_wiki	新しいウィキを作成	wiki:write	無料
ingest	ソースを渡して Cairni が編纂	wiki:write	クレジット

put_page はクライアントが書いた Markdown をそのまま保存 — Cairni AI を経由しないため無料。ask・ingest は Cairni の LLM を使い、そのウィキのワークスペースのクレジットを消費します。

スコープ・セキュリティ

wiki:read
ウィキ・ページの閲覧・検索。
wiki:ask
根拠ある質問(クレジット使用)。
wiki:write
ウィキ作成・ページ編集。

トークンはスコープ付きでいつでも失効可能 — 設定 → Developer で管理・失効できます。OAuth は PKCE と同意画面を使い、他人の非公開ウィキは決して公開しません。

接続の準備はできましたか?

トークンを発行するか、Cairni を開いて始めましょう。

REST API · v1

REST API で Cairni を使う

ベース URL: https://api.cairni.com/v1
認証: Authorization: Bearer cairni_live_…
フォーマット: JSON
バージョン: 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"
}

認証

wiki:read
ウィキ・ページの閲覧・検索。
wiki:ask
根拠ある質問(クレジット使用)。
wiki:write
ウィキ作成・ページ編集。

アイデンティティ

接続確認と、呼び出し中のキー情報の確認。

GET/ping

ヘルスチェック

認証なしの到達確認 — キー不要。

キーのみ無料

レスポンス

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

キー情報

呼び出したキーの ID・環境・スコープを返す — SDK 初期化やデバッグに便利。

キーのみ無料

レスポンス

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.

エラー

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"
}

ウィキ

ウィキの一覧・取得・作成。自分と共有されたウィキだけが見えます。

GET/wikis

ウィキ一覧

アクセス可能なウィキ(自分・共有)を不透明な cursor でページネーションして返す。

wiki:read無料

パラメータ

クエリ

cursor

string

Opaque cursor from a previous response's next_cursor.

limit

integer · default 50

Page size, 1–100.

レスポンス

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.

エラー

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}

ウィキ取得

ウィキのメタデータを返す。アクセス不可のウィキは 404(存在を隠す)。

wiki:read無料

パラメータ

パス

slugreq

string

Wiki identifier.

レスポンス

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.

エラー

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

ウィキ作成

個人スペースに新しいウィキを作成 — あなたが manager になります。無料。中身はソース編纂(下)で埋めます。

wiki:write無料

パラメータ

ボディ

namereq

string

Display name for the new wiki.

description

string

Optional one-line description.

レスポンス

…

Wiki

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

エラー

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"
}

ページ

ウィキ内に編纂されたページを読みます。

GET/wikis/{slug}/pages

ページ一覧

ウィキのページを表示順に cursor ページネーションして返す。

wiki:read無料

パラメータ

パス

slugreq

string

Wiki identifier.

クエリ

cursor

string

Opaque cursor for the next page.

limit

integer · default 50

Page size, 1–100.

レスポンス

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.

エラー

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}

ページ取得

ページの正本 Markdown 本文とメタデータを返す。

wiki:read無料

パラメータ

パス

slugreq

string

Wiki identifier.

pagereq

string

Page slug.

レスポンス

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.

エラー

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"
}

検索

キーワードでウィキ全体からページを探します。

GET/search

ページ検索

アクセス可能なウィキ全体(または ?wiki=slug 限定)でタイトル・要約をマッチ。

wiki:read無料

パラメータ

クエリ

q

string

Search terms (token AND match).

wiki

string

Restrict to a single wiki slug.

limit

integer · default 20

Max results, 1–50.

レスポンス

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.

エラー

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
}

編纂

POST/wikis/{slug}/sources

ソース編纂

URL またはテキストを渡すとバックグラウンドでページを編纂し、ポーリング用の job を返します。editor 権限が必要・クレジット使用。

wiki:writeクレジット

パラメータ

パス

slugreq

string

Wiki identifier.

ボディ

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.

レスポンス

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.

エラー

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

音声を編纂

wiki:writeクレジット

パラメータ

パス

slugreq

string

Wiki identifier.

ボディ

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.

レスポンス

job_id

string

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

status

string

Starts at "transcribing".

エラー

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

編纂ジョブ一覧

このウィキの最近の編纂ジョブを新しい順に返す。

wiki:write無料

パラメータ

パス

slugreq

string

Wiki identifier.

クエリ

limit

integer · default 20

Max jobs, 1–100.

レスポンス

data

Job[]

Recent jobs (same shape as Get a job).

エラー

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}

編纂ジョブ取得

編纂ジョブの status・phase・progress・作成済みページを返す。status が "done" になるまでポーリング。

wiki:write無料

パラメータ

パス

slugreq

string

Wiki identifier.

job_idreq

string

Job id from Compile a source.

レスポンス

status

string

queued | running | done | failed.

phase

string

progress

integer

0–100.

compiled_pages

string[]

Slugs of pages written so far.

エラー

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"
}

質問

質問すると、ウィキに基づいた回答を引用付きで受け取ります。

POST/wikis/{slug}/ask

質問する

ウィキに基づいて回答し、使用したページを引用します。根拠がない場合は拒否(refused=true)。クレジット使用。

wiki:askクレジット

パラメータ

パス

slugreq

string

Wiki identifier.

ボディ

questionreq

string

Natural-language question to answer from the wiki.

レスポンス

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.

エラー

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": []
}

エラー

エラーボディ

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"
  }
}

401unauthorized認証失敗

402insufficient_creditsクレジット不足

403forbiddenスコープ・権限拒否

404not_found存在しない — または非表示

422invalid_request不正なリクエスト

429rate_limitedリクエスト過多

すぐ使えるクライアント連携(Claude Code・Cursor・Codex)がよいですか? 同じ機能を MCP でも提供しています — 下の MCP サーバーガイドをご覧ください。

Model Context Protocol

Cairni のウィキをあらゆる AI クライアントで

あなたのウィキ

Cairni MCP

Claude Code

エンドポイント: https://mcp.cairni.com/
トランスポート: Streamable HTTP
認証: OAuth 2.1 · 動的クライアント登録 · または PAT

OAuth で接続(推奨)

最速の方法 — ブラウザに同意画面が出て「許可」を押すだけ。

サーバーを追加

Claude Code で実行:

shell

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

ブラウザで承認

Cairni のページが開きます。必要ならログインし、要求された権限を確認して「許可」を押します。

完了

クライアントに list_wikis・search・ask・put_page などのツールが追加されます。

Claude Desktop・claude.ai(Team / Enterprise): 設定 → コネクタで同じ URL を追加すると、同じ「許可」画面が表示されます。

トークンで接続

スクリプト・CI・OAuth 非対応クライアント用 — 個人アクセストークン(PAT)を使います。

トークンを発行

Cairni の設定 → Developer でスコープ(読み取り / 質問 / 書き込み)を選び、一度コピーします。

ヘッダーとして追加

shell

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

または claude_desktop_config.json に:

claude_desktop_config.json

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

他のクライアント

Cursor

~/.cursor/mcp.json

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

または設定 → MCP → 新しいサーバーを追加。初回に OAuth で承認します。

Codex

shell

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

初回の rmcp 設定: ~/.codex/config.toml の [features] に experimental_use_rmcp_client = true を追加し、codex mcp login cairni を実行。

VS Code · Windsurf · Zed · others

shell

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

ツール

すべてのツールはあなたの権限で動作 — 自分と共有されたウィキだけが見えます。

ツール	機能	スコープ	コスト
list_wikis	アクセス可能なウィキ一覧	wiki:read	無料
read_page	ページの Markdown を読む	wiki:read	無料
search	ウィキを横断検索	wiki:read	無料
ask	出典付きの根拠ある回答	wiki:ask	クレジット
put_page	ページを直接書き込み(raw)	wiki:write	無料
create_wiki	新しいウィキを作成	wiki:write	無料
ingest	ソースを渡して Cairni が編纂	wiki:write	クレジット

スコープ・セキュリティ

wiki:read
ウィキ・ページの閲覧・検索。
wiki:ask
根拠ある質問(クレジット使用)。
wiki:write
ウィキ作成・ページ編集。

接続の準備はできましたか?

トークンを発行するか、Cairni を開いて始めましょう。