REST API の使い方
REST API の使い方
Docmost の REST API でページ・スペース・ユーザー等をプログラムから操作するための入口ガイドです。
こんなときに読む
- 自動化スクリプトや外部システムと連携したい
- API ドキュメントの場所と認証方法を知りたい
- ブラウザ操作と API の使い分けを決めたい
公式 API ドキュメント
- エンドポイント一覧・リクエスト/レスポンス形式
- 認証ヘッダーの指定方法
- バージョンや追加エンドポイントはドキュメントを正とする
認証
API キー（推奨）
- 個人 API キーを発行（
/settings/account/api-keys） - リクエストに Bearer トークンとして付与
Authorization: Bearer YOUR_API_KEY
Enterprise: 個人 API キーは Enterprise 機能です（No.8.5）。
セッション Cookie
ブラウザと同じログインセッションを使う方法もありますが、統合・バッチ処理では API キーを推奨します。
ベース URL
| 環境 | ベース URL |
|---|---|
| クラウド | テナントの URL（例: https://yourteam.docmost.com） |
| セルフホスト | APP_URL の値（例: https://docs.example.com） |
API パスは通常 /api/... 配下です。詳細は api-docs を参照してください。
典型的なユースケース
| 用途 | 例 |
|---|---|
| ページの作成・更新 | CI からリリースノートを投稿 |
| スペース・メンバー管理 | オンボーディング自動化 |
| 検索・エクスポート | レポート生成 |
| Webhook 連携 | 外部イベントとドキュメント同期 |
MCP との使い分け
| 手段 | 向いていること |
|---|---|
| REST API | CI/CD・バッチ・外部システムからエンドポイントを直接呼ぶ CRUD 自動化 |
| MCP | Cursor 等の AI エージェントから、会話の流れでページ・スペースを検索・作成・更新する（No.9.3） |
| ブラウザ | 日常の編集・レビュー・共同作業 |
MCP でもページやスペースの作成・更新は可能です。大規模な一括処理や API レベルの細かい制御には REST API を選びます。
→ 画面と手段の選び方: 「どこから使う？ — Web・API・MCP の選び方」（No.1.3）
エラーと権限
| HTTP | 意味 | 対処 |
|---|---|---|
| 401 | 認証失敗 | API キー・ヘッダーを確認 |
| 403 | 権限不足 | WS / Space ロール、EE ページ権限（No.11.4） |
| 404 | リソースなし | ID・スラッグを確認 |
| 429 | レート制限 | リトライ間隔を調整 |
セキュリティ
- API キーは環境変数やシークレット管理に保存
- 最小権限 … 必要なスコープのあるキーのみ発行
- ログにキーを出力しない
関連ナレッジ
- API キー: 「個人 API キーの発行」（No.8.5）
- MCP: 「MCP 連携設定」（No.9.3）
- 権限: 「用語と権限」（No.2.2）
- 逆引き: 「やりたいことから探す」（No.1.1）