AIエージェント向け

docspi エージェント・リファレンス

このページは見出し・箇条書き・コードブロックのみで構成されています。docspi の予備知識がないAIエージェントが WebFetch で読み取り、人間のオンボーディングを支援できるようにするためです。

ゴール

人間はサインアップするだけ。その後はエージェントがペアリング、MCP設定、プロジェクト作成、ドキュメント保存、公開までを完全に自律実行します。

人間がブラウザで https://docspi.ai/signin からサインアップする。
エージェントが POST /api/agent-pairing/start を呼び、人間に承認用リンクを提示し、POST /api/agent-pairing/poll を承認されるまでポーリングする。
エージェントが取得したトークンで docspi-mcp MCPサーバーを設定するか、Authorization: Bearer ヘッダーで直接REST APIを呼び出す。
エージェントが POST /api/projects でプロジェクトを作成し、POST /api/projects/:projectId/documents/save でドキュメントを保存する。
エージェントが POST /api/published-docs で公開ドキュメントのレコードを作成し、POST /api/published-docs/:id/publish で公開する。

Bearer認証が必要なエンドポイントはすべて、ペアリングフローで発行された同一の docspi APIトークンを使用します。

POST /api/agent-pairing/startauth: none: device-pairing リクエストを開始する。Body: { clientName }。userCode / deviceCode / verificationUriComplete / interval を返す。
POST /api/agent-pairing/pollauth: none (device code is the secret): ペアリング承認をポーリングする。Body: { deviceCode }。authorization_pending / slow_down / expired_token / access_denied、または承認済みなら 200 とトークンを返す。
POST /api/projectsauth: Bearer <docspi API token>: プロジェクトを作成する。Body: { name, description? }。
POST /api/projects/:projectId/documents/saveauth: Bearer <docspi API token>: 仮想パスを指定してドキュメントを作成・更新する。Body: { virtualPath, content }。
POST /api/published-docsauth: Bearer <docspi API token>: 保存済みの内容から公開ドキュメントのレコードを作成する。Body: { projectId, publicTitle, slug, content }。
POST /api/published-docs/:id/publishauth: Bearer <docspi API token>: 公開ドキュメントのレコードを公開状態に切り替え、公開URLで到達可能にする。