CSwiki

REST API Reference

Wikiを外部システムとつなぐ。

接続先Wikiのページを検索・取得・作成・更新する、Wiki単位のJSON API仕様です。

Overview

基本仕様と認証

APIの操作対象は、Bearerトークンを発行した1つのWikiに限定されます。Wiki管理者が「設定 → 外部連携」で連携を作成し、必要な権限だけを付与してください。

Base URLhttps://{wiki-host}/api/integration/v1
Content typeapplication/json
AuthenticationBearer token
Rate limit60 requests / minute
権限許可される操作
pages:readページの検索・取得
pages:create新規ページの直接公開
pages:update既存ページの編集
トークンは作成直後に一度だけ表示されます

安全な場所へ保存し、ソースコードやWiki本文へ記載しないでください。漏えいした場合は設定画面で再発行します。

Request headers

共通ヘッダー

名前必須値・制約説明
Authorization必須Bearer <access-token>すべての操作で指定します。
Content-Type本文ありapplication/jsonPOST・PUTで指定します。
Idempotency-KeyPOST・PUT1〜128文字、制御文字不可同じ連携内で処理を一意に識別します。
安全な再送

同じ Idempotency-Key と同じ内容を再送すると最初の結果を返し、replayed が true になります。同じキーで内容を変えると 409 idempotency_conflict です。

Endpoints

ページ操作

GET /pages searchPages

ページ名と現行本文を検索します。検索語が空の場合は更新日時の新しい順に返します。

権限 pages:read成功 200 OK

Query parameters

名前型必須制約・既定値
qstring任意最大200文字
limitinteger任意1〜50、既定値20

Response 200

{
  "pages": [{
    "name": "会議/2026-07-25",
    "url": "https://{wiki-host}/会議/2026-07-25",
    "excerpt": "会議概要...",
    "current_revision_id": 42,
    "updated_at": "2026-07-25T10:30:00+09:00"
  }]
}
GET /pages/{page_name} getPage

現行Markdown本文、タグ、更新に必要なリビジョンIDを取得します。階層名は各セグメントをURLエンコードします。

権限 pages:read成功 200 OK

Response 200

{
  "name": "会議/2026-07-25",
  "body": "# 会議概要",
  "tags": ["会議"],
  "current_revision_id": 42,
  "updated_at": "2026-07-25T10:30:00+09:00",
  "url": "https://{wiki-host}/会議/2026-07-25"
}

Responses 200 取得成功 · 401 認証失敗 · 403 権限不足 · 404 page_not_found

POST /pages createPage

新規ページを作成し、下書きを経ずに公開します。既存または削除済みページの名前は再利用できません。

権限 pages:create成功 201 Created

Request body application/json

フィールド型必須制約
namestring必須最大255文字
bodystring必須最大1,000,000文字
summarystring | null任意最大255文字
tagsstring[]任意最大10件、各50文字、重複不可
source_refsstring[]任意最大10件、各500文字、重複不可

Request example

curl -X POST "https://{wiki-host}/api/integration/v1/pages" \
  -H "Authorization: Bearer <access-token>" \
  -H "Idempotency-Key: meeting-2026-07-25" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "会議/2026-07-25",
    "body": "# 会議概要",
    "summary": "会議ページを作成",
    "tags": ["会議"],
    "source_refs": ["議事録: 2026-07-25"]
  }'

Responses 201 作成成功 · 200 再送結果 · 409 page_already_exists · 409 idempotency_conflict · 422 入力不正

PUT /pages/{page_name} updatePage

既存ページの本文全体を置き換え、新しい履歴を作成します。先にGETで現行版を取得してください。

権限 pages:update成功 200 OK

Request body application/json

フィールド型必須制約・説明
bodystring必須最大1,000,000文字。置き換え後の本文全体
base_revision_idinteger必須GETで取得した current_revision_id
summarystring | null任意最大255文字
tagsstring[]任意更新後のタグ全体。省略時は空
source_refsstring[]任意この履歴の参照元

Request example

curl -X PUT "https://{wiki-host}/api/integration/v1/pages/会議/2026-07-25" \
  -H "Authorization: Bearer <access-token>" \
  -H "Idempotency-Key: meeting-update-1" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "# 会議概要\n\n決定事項を追記",
    "base_revision_id": 42,
    "summary": "決定事項を追記",
    "tags": ["会議"]
  }'
409 revision_conflict の処理

ページを再取得し、変更内容を現行本文へ反映してから新しいIdempotency-Keyで再試行します。

Responses 200 成功 · 403 page_frozen · 404 page_not_found · 409 revision_conflict · 409 idempotency_conflict · 422 入力不正

Errors

エラーレスポンス

API固有のエラーは、機械判定用の error と利用者向けの message をJSONで返します。

{
  "error": "revision_conflict",
  "message": "ページが別の操作で更新されています。",
  "current_revision_id": 43
}
HTTPerror意味・対処
401unauthorizedトークンが無効、失効済み、期限切れ、または別Wiki用です。
403forbidden操作に必要な権限がありません。
403page_frozen凍結ページは更新できません。
404page_not_foundページが存在しないか削除済みです。
409page_already_exists同名の現存または削除済みページがあります。
409revision_conflict指定した版が古いため再取得します。
409idempotency_conflict同じキーが別の内容で使われています。
422invalid_idempotency_key冪等キーが未指定または不正です。
422validation errorerrors の各フィールドを修正します。
429rate limit時間を置いて再試行します。