docspi

Agent Quickstart

Sign up. Say "go". Your agent takes it from there.

This page is the complete, self-contained walkthrough an AI agent needs to onboard a brand-new docspi user end-to-end: pairing, MCP setup, creating a project, saving a document, and publishing it -- without any human typing API calls.

The five steps

  1. A human signs up for docspi.
  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.

1. Sign up

A human creates a docspi account. This is the only step that must happen in a browser.

Create a free account

2. Pair your agent

docspi uses a device-code pairing flow (similar to signing in to a smart TV). The agent starts a pairing request, shows the human a short code to approve, and polls until the human approves it in the browser.

Start a pairing request:

curl -s -X POST https://docspi.ai/api/agent-pairing/start \
  -H "Content-Type: application/json" \
  -d '{"clientName": "Claude Code / my-project"}'
{
  "userCode": "WJHQ-KMPX",
  "deviceCode": "5f2b1c...c9",
  "verificationUri": "https://docspi.ai/pair",
  "verificationUriComplete": "https://docspi.ai/pair?code=WJHQ-KMPX",
  "expiresIn": 600,
  "interval": 5
}

The response includes a one-time deviceCode (keep it secret -- it is the agent's credential) and a verificationUriComplete for the human to open.

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 until approved:

DEVICE_CODE="5f2b1c...c9"
while true; do
  RES=$(curl -s -X POST https://docspi.ai/api/agent-pairing/poll \
    -H "Content-Type: application/json" \
    -d "{\"deviceCode\": \"$DEVICE_CODE\"}")
  ERR=$(echo "$RES" | jq -r '.error // empty')
  if [ -z "$ERR" ]; then
    export DOCSPI_API_TOKEN=$(echo "$RES" | jq -r '.token')
    break
  elif [ "$ERR" = "authorization_pending" ]; then
    sleep 5
  else
    echo "Pairing stopped: $ERR"; break
  fi
done

Poll every `interval` seconds (default 5). A pending approval returns authorization_pending; once the human approves, the response includes the agent's API token.

3. Configure MCP

Point the docspi-mcp server at the token from step 2. Any MCP-compatible agent (Claude Code, Cursor, etc.) can now call docspi tools directly.

{
  "mcpServers": {
    "docspi": {
      "command": "npx",
      "args": [
        "-y",
        "docspi-mcp"
      ],
      "env": {
        "DOCSPI_API_URL": "https://docspi.ai/api",
        "DOCSPI_API_TOKEN": "dsp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

4. Create a project and save a document

Create a project, then save a document into it by virtual path. docspi creates any missing folders automatically.

curl -s -X POST https://docspi.ai/api/projects \
  -H "Authorization: Bearer $DOCSPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Runbook", "description": "Operational runbook for Acme"}'
# -> { "data": { "id": "<projectId>", "slug": "acme-runbook", ... } }
curl -s -X POST https://docspi.ai/api/projects/$PROJECT_ID/documents/save \
  -H "Authorization: Bearer $DOCSPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"virtualPath": "/getting-started.md", "content": "# Getting started\n..."}'
# -> { "data": { "nodeId": "<nodeId>", ... } }

5. Publish

Create a published-doc record from the saved content, then flip it live. The document is now reachable at a public URL -- no authentication required to read it.

curl -s -X POST https://docspi.ai/api/published-docs \
  -H "Authorization: Bearer $DOCSPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "'"$PROJECT_ID"'", "publicTitle": "Getting Started", "slug": "getting-started", "content": "# Getting started\n..."}'
# -> { "data": { "id": "<publishedDocId>", ... } }
curl -s -X POST https://docspi.ai/api/published-docs/$PUBLISHED_DOC_ID/publish \
  -H "Authorization: Bearer $DOCSPI_API_TOKEN"
# now live at https://docspi.ai/d/<tenant-slug>/acme-runbook/getting-started

Machine-readable references