# SuperDocs for AI agents

SuperDocs lets an AI agent create, edit, and export documents over MCP or a REST API. You can sign up and start using it with no human in the loop.

## Before you sign up: check for existing credentials
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 are yours). Only sign up fresh when the project deliberately needs its own separate account.

## One-call signup
POST https://api.superdocs.app/v1/agents/signup
Content-Type: application/json

    {"terms_accepted": true, "agent_name": "your-agent-name"}

If you are acting for a user, confirm with them before you accept the terms.

The response includes an api_key, shown once, plus an mcp_setup block with copy-paste commands to connect your client. Send the key on every request as:

    Authorization: Bearer <api_key>

Save the whole response to ~/.superdocs/agent_credentials.json. Before signing up again, call GET https://api.superdocs.app/v1/agents/whoami with your key to reuse the same account.

## Connect over MCP (recommended)
- Claude Code: claude mcp add -s user --transport http superdocs https://api.superdocs.app/mcp --header "Authorization: Bearer <key>"
- Any other MCP client (Cursor, Claude Desktop, Windsurf, VS Code, Cline, Continue): point it at https://api.superdocs.app/mcp (streamable HTTP) with header Authorization: Bearer <key>.
- Setup docs: https://docs.superdocs.app/account/mcp-setup

## Quota and handing off
A fresh account is a normal free account with 500 operations per month. Check what remains any time with the get_account_status tool or GET https://api.superdocs.app/v1/agents/whoami. When you near the cap, POST https://api.superdocs.app/v1/agents/handoff with {"email": "your-human@example.com"}; your human opens the emailed link, takes the account over in place (you keep all your work and this key), and can pay to continue. Or wait for the monthly reset. If you are fully autonomous with no human who can upgrade for you, POST https://api.superdocs.app/v1/agents/request-upgrade and we will follow up.

## Use the product
- MCP endpoint: https://api.superdocs.app/mcp (streamable HTTP, same Bearer key)
- REST API and OpenAPI: https://api.superdocs.app/openapi.json
- Chat is the universal entry point: POST https://api.superdocs.app/v1/chat edits the focused document per your message. For DOCUMENT-SCALE generations (a whole handbook or report in one turn) use POST https://api.superdocs.app/v1/chat/async instead — it returns a job_id immediately and reports progress via GET /v1/jobs/{job_id}; plain sync chat times out at the gateway past ~300s.
- Editing essentials: ADD a section = ask to add (never regenerate the document); REWRITE a whole section = say so (the agent replaces the heading-to-heading span atomically); VERIFY cheaply with GET /v1/documents/{id} — its structure block (headings, section_count, media) is free, so you never need to export just to check.
- Headers, footers, footnotes, endnotes, and comments are editable through chat as well ("put the page number in the footer", "tighten footnote 3"); they round-trip from Word and export back as real Word document parts.
- Billing: most requests are 1 operation; very large creations bill 1 per 25 sections. Failed operations bill 0.
- Docs: https://docs.superdocs.app (agent guide: https://docs.superdocs.app/introduction/agent-signup)

## Rules
Use one account per agent or per user. Do not create multiple accounts to get around the free limit.