Skip to main content

​
For AI Agents

SuperDocs is built to be used by AI agents, not just people. An agent can create an account and get a working API key in a single request, then use the REST API or the MCP server right away. No web sign-up form, no waiting on a human.
If you are an agent acting on behalf of a user, confirm with them before you accept the terms and create an account.

​
0. Check for existing credentials first

If ~/.superdocs/agent_credentials.json exists on this machine, a previous agent already created an account. Call GET https://api.superdocs.app/v1/agents/whoami with that api_key and reuse the account — its documents and remaining quota carry over. Sign up fresh only when the project deliberately needs its own separate account.

​
1. Sign up

curl
curl -X POST https://api.superdocs.app/v1/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"terms_accepted": true, "agent_name": "your-agent-name"}'
The response returns everything you need, including the API key (shown only once): 
{
  "account_id": "…",
  "slug": "your-agent-name-a1b2c3",
  "email": "your-agent-name-a1b2c3@agents.superdocs.app",
  "api_key": "sk_…",
  "quota": { "tier": "free", "monthly_limit": 500, "used": 0, "remaining": 500 },
  "endpoints": {
    "mcp": "https://api.superdocs.app/mcp",
    "chat": "https://api.superdocs.app/v1/chat",
    "whoami": "https://api.superdocs.app/v1/agents/whoami",
    "openapi": "https://api.superdocs.app/openapi.json"
  },
  "mcp_setup": {
    "claude_code": "claude mcp add --transport http superdocs https://api.superdocs.app/mcp --header \"Authorization: Bearer sk_…\"",
    "generic_mcp": "Point any MCP client at https://api.superdocs.app/mcp (Streamable HTTP) with header Authorization: Bearer <your key>",
    "rest_fallback": "Prefer REST? POST https://api.superdocs.app/v1/chat with the Bearer header",
    "docs": "https://docs.superdocs.app/account/mcp-setup"
  },
  "handoff": { "how": "When you near the 500-op cap, POST /v1/agents/handoff with your key and {email}; you get back a short takeover code to give your human, who then adopts the account and can pay to continue" }
}
The mcp_setup block gives you copy-paste commands to connect right away.
Save api_key now. It is shown only once. Store the whole response at ~/.superdocs/agent_credentials.json and call GET /v1/agents/whoami before signing up again so you reuse the same account instead of creating a new one.
Optional body fields: agent_name (a label), operated_by_email (your operator’s email, used only if you hand off later), and model_metadata (free-form details about your model).

​
2. Use your key

Send the key as a Bearer token on every request, on the REST API or the MCP server.
REST
curl -X POST https://api.superdocs.app/v1/chat \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Draft a one-page NDA", "session_id": "s1"}'
For MCP, point your client at https://api.superdocs.app/mcp (streamable HTTP) with the same Bearer key. In Claude Code, one command connects it:
Claude Code
claude mcp add --transport http superdocs https://api.superdocs.app/mcp \
  --header "Authorization: Bearer sk_YOUR_KEY"
Other clients (Cursor, Claude Desktop, Windsurf, VS Code, Cline, Continue) take the same URL and header. See MCP Setup. Call the get_account_status tool anytime to check your remaining operations.

​
Long generations

For document-scale generations (a whole handbook or long report in one turn), use POST /v1/chat/async — it returns a job_id immediately and reports progress via GET /v1/jobs/{job_id}. Plain sync /v1/chat hits the platform gateway timeout (~300s) on very long turns. Editing patterns, placement, verification, and billing are covered in the Agent editing playbook.

​
3. Quota and handing off to a human

Your account is a normal free account: 500 operations per month, the same as a human free account. When you near the cap and want to keep going, hand the account to your human so they can take it over and pay:
curl
curl -X POST https://api.superdocs.app/v1/agents/handoff \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "your-human@example.com", "working_context": "the ~/Documents/acme project on your Mac"}'
Pass working_context (a short note on where you are running) so the email is recognizable and does not look like spam. The response includes a short takeover_code (like ABCD-1234). Show that takeover code to your human, and tell them where to find it if they ask (you can also save it to a file such as ~/.superdocs/takeover-code.txt). We email a one-time link to the address you gave. Your human opens it, signs in, and enters the takeover code, then takes the account over in place, so you keep all your work and your API key keeps working the whole time. They can then upgrade or pay from the app. The takeover code is a security check: it proves the person adopting the account is really the one running you, so a link that reaches the wrong inbox cannot be used to take the account. Never email the code or post it anywhere public. (If your human already has a SuperDocs account, they sign into that instead.) You can also just wait: your quota resets at the start of each month.
Fully autonomous with no human who can upgrade for you? POST https://api.superdocs.app/v1/agents/request-upgrade with your key (optionally a short note). We don’t offer agent-native card payment yet, but we’re gauging demand and will follow up. A human handoff upgrades you immediately; this path is for when there truly is no human.

​
Rules and limits

  • Use one account per agent or user. Do not create multiple accounts to get around the free limit.
  • Check your status anytime with GET /v1/agents/whoami or the get_account_status MCP tool. It tells you how many operations remain so you can hand off before you hit the cap.