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에서 키를 만드세요 — Full access 또는 특정 스코프를 고르고, 만료는 선택. 키는 한 번만 보이니 안전하게 보관하세요. 모든 요청에 Bearer 헤더가 필요하며, 세션 쿠키는 받지 않습니다.

wiki:read
위키·페이지 읽기·검색.
wiki:ask
그라운디드 질문(크레딧 사용).
wiki:write
위키 생성·페이지 편집.

Full access(*)는 계정이 할 수 있는 모든 위키 작업을 허용하지만, 항상 본인 권한 안에서만 동작하며 타인의 비공개 위키는 절대 노출하지 않습니다. 키는 언제든 비활성·회전·폐기할 수 있습니다.

신원

연결 확인 및 호출 중인 키 정보 확인.

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

내 키 정보

호출한 키의 신원·환경·권한을 반환 — 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}

페이지 조회

페이지의 정본 마크다운 본문과 메타데이터를 반환.

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스코프·권한 거부

키는 유효하지만 이 작업이 허용되지 않습니다. 필요한 스코프가 없거나(예: read 전용 키로 쓰기 호출 — 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로 Cairni를 추가하면 동일한 '허용' 화면이 나옵니다.

토큰으로 연결

스크립트·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는 표준 remote-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	페이지 마크다운 읽기	wiki:read	무료
search	위키 전체 검색	wiki:read	무료
ask	출처 인용 그라운디드 Q&A	wiki:ask	크레딧
put_page	페이지 직접 작성(raw)	wiki:write	무료
create_wiki	새 위키 생성	wiki:write	무료
ingest	원자료를 넘겨 Cairni가 편찬	wiki:write	크레딧

put_page는 클라이언트가 작성한 마크다운을 그대로 저장 — 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

내 키 정보

호출한 키의 신원·환경·권한을 반환 — 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}

페이지 조회

페이지의 정본 마크다운 본문과 메타데이터를 반환.

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

오디오 편찬

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인증 실패

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로 Cairni를 추가하면 동일한 '허용' 화면이 나옵니다.

토큰으로 연결

스크립트·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	페이지 마크다운 읽기	wiki:read	무료
search	위키 전체 검색	wiki:read	무료
ask	출처 인용 그라운디드 Q&A	wiki:ask	크레딧
put_page	페이지 직접 작성(raw)	wiki:write	무료
create_wiki	새 위키 생성	wiki:write	무료
ingest	원자료를 넘겨 Cairni가 편찬	wiki:write	크레딧

스코프·보안

wiki:read
위키·페이지 읽기·검색.
wiki:ask
그라운디드 질문(크레딧 사용).
wiki:write
위키 생성·페이지 편집.

연결할 준비됐나요?

토큰을 발급하거나 Cairni를 열어 시작하세요.