Agent Quickstart

# Agent Quickstart A human signs up once. The agent then pairs, configures MCP, creates a project, saves a document, and publishes it -- fully autonomously, with no API calls typed by a human. ## The five steps 1. A human signs up for docspi in a browser at https://docspi.ai/signin (the only step that must happen in a browser). 2. The agent pairs itself with the new account (device-code flow). 3. The agent configures the docspi MCP server. 4. The agent creates a project and saves a document. 5. The agent publishes the document to a public URL. ## Step 2: Pair your agent docspi uses a device-code pairing flow, similar to signing in to a smart TV. - Start: `POST /api/agent-pairing/start`. Body: `{ clientName }`. Returns `userCode`, `deviceCode`, `verificationUriComplete`, `interval`. - The `deviceCode` is a one-time credential -- keep it secret. - Ask the human to open the `verificationUriComplete` link (or go to `/pair` and type the `userCode`) and click Approve. Do not continue until they confirm they approved it. - Poll: `POST /api/agent-pairing/poll`. Body: `{ deviceCode }`. Poll every `interval` seconds (default 5). A pending approval returns `authorization_pending`; once approved, the response includes the agent's API token. ## Step 3: Configure MCP Point the `docspi-mcp` server at the token from step 2 (as the `DOCSPI_API_TOKEN` environment variable). Any MCP-compatible agent (Claude Code, Cursor, etc.) can now call docspi tools directly. See `mcp-server.md` for the full tool list. ## Step 4: Create a project and save a document - `POST /api/projects`. Body: `{ name, description? }`. - `POST /api/projects/:projectId/documents/save`. Body: `{ virtualPath, content }`. docspi creates any missing folders automatically. ## Step 5: Publish - `POST /api/published-docs`. Body: `{ projectId, publicTitle, slug, content }`. - `POST /api/published-docs/:id/publish`. The document is now reachable at a public URL -- no authentication required to read it. ## Rules for agents - Never ask a human to paste their password or session cookie to you. The pairing flow is the only supported way for an agent to obtain credentials. ## See also - `use-cases.md` -- what docspi solves and for whom - `mcp-server.md` -- MCP server setup and the full 13-tool reference - `api-reference.md` -- full REST API reference - `concepts.md` -- glossary of docspi concepts --- # エージェント向けクイックスタート人間は一度サインアップするだけ。あとはエージェントがペアリング、MCP設定、プロジェクト作成、ドキュメント保存、公開までを完全に自律実行します。人間がAPI呼び出しを手打ちする必要はありません。 ## 5つのステップ 1. 人間がブラウザで https://docspi.ai/signin から docspi にサインアップする（ブラウザ操作が必要なのはこのステップだけ）。 2. エージェントが device-code フローでアカウントとペアリングする。 3. エージェントが docspi MCP サーバーを設定する。 4. エージェントがプロジェクトを作成しドキュメントを保存する。 5. エージェントがドキュメントを公開URLとして公開する。 ## ステップ2: エージェントをペアリングする docspi はスマートTVのサインインに似た device-code 型のペアリングフローを採用しています。 - 開始: `POST /api/agent-pairing/start`。Body: `{ clientName }`。`userCode`, `deviceCode`, `verificationUriComplete`, `interval` を返す。 - `deviceCode` は一度だけ返される認証情報 -- 秘匿すること。 - 人間に `verificationUriComplete` のリンク（または `/pair` を開いて `userCode` を入力）を開いて「承認」をクリックしてもらう。承認したと確認が取れるまで次に進まないこと。 - ポーリング: `POST /api/agent-pairing/poll`。Body: `{ deviceCode }`。`interval` 秒（既定5秒）ごとにポーリングする。未承認の間は `authorization_pending` が返り、承認されるとレスポンスにエージェント用のAPIトークンが含まれる。 ## ステップ3: MCPを設定するステップ2で取得したトークンを `DOCSPI_API_TOKEN` 環境変数として `docspi-mcp` サーバーに設定する。MCP対応のエージェント（Claude Code, Cursor など）はこれで docspi のツールを直接呼び出せる。全ツールの一覧は `mcp-server.md` を参照。 ## ステップ4: プロジェクトを作成しドキュメントを保存する - `POST /api/projects`。Body: `{ name, description? }`。 - `POST /api/projects/:projectId/documents/save`。Body: `{ virtualPath, content }`。存在しないフォルダは docspi が自動的に作成する。 ## ステップ5: 公開する - `POST /api/published-docs`。Body: `{ projectId, publicTitle, slug, content }`。 - `POST /api/published-docs/:id/publish`。これでドキュメントは認証不要の公開URLで閲覧できるようになる。 ## エージェントへの注意事項 - 人間にパスワードやセッションCookieを貼り付けさせてはいけない。エージェントが認証情報を取得できる唯一の方法はペアリングフローである。 ## 関連ページ - `use-cases.md` -- docspi が何を・誰のために解決するか - `mcp-server.md` -- MCPサーバーのセットアップと全13ツールのリファレンス - `api-reference.md` -- API リファレンス全体 - `concepts.md` -- 用語集 --- Canonical: https://docspi.ai/docs