For AI agents
docspi Agent Reference
This page is deliberately plain: headings, lists, and code blocks only. It is written for an AI agent reading it via WebFetch to help a human onboard onto docspi with no prior knowledge of the product.
Goal
A human signs up. The agent then pairs itself, configures MCP, creates a project, saves a document, and publishes it -- fully autonomously.
Flow
- Human signs up in a browser at https://docspi.ai/signin.
- Agent calls POST /api/agent-pairing/start, shows the human the verification link, then polls POST /api/agent-pairing/poll until approved.
- Agent configures the docspi-mcp MCP server with the returned token, or calls the REST API directly with an Authorization: Bearer header.
- Agent calls POST /api/projects to create a project, then POST /api/projects/:projectId/documents/save to save a document.
- Agent calls POST /api/published-docs to create a published-doc record, then POST /api/published-docs/:id/publish to make it public.
Endpoints
All Bearer-authenticated endpoints accept the same docspi API token issued by the pairing flow.
POST /api/agent-pairing/startauth: none- Start a device-pairing request. Body: { clientName }. Returns userCode, deviceCode, verificationUriComplete, interval.
POST /api/agent-pairing/pollauth: none (device code is the secret)- Poll for pairing approval. Body: { deviceCode }. Returns authorization_pending / slow_down / expired_token / access_denied, or 200 with the issued token.
POST /api/projectsauth: Bearer <docspi API token>- Create a project. Body: { name, description? }.
POST /api/projects/:projectId/documents/saveauth: Bearer <docspi API token>- Create or update a document by virtual path. Body: { virtualPath, content }.
POST /api/published-docsauth: Bearer <docspi API token>- Create a published-doc record from saved content. Body: { projectId, publicTitle, slug, content }.
POST /api/published-docs/:id/publishauth: Bearer <docspi API token>- Flip a published-doc record live at a public URL.
Notes 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.
- The full REST + MCP surface, including scopes, is described at /docs/api.
- See /docs for the narrated, human-readable version of this same flow.