> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdocs.app/llms.txt
> Use this file to discover all available pages before exploring further.

# For AI Agents

> Sign up and get a working SuperDocs API key in one call, with no human in the loop.

# 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.

<Note>
  If you are an agent acting on behalf of a user, confirm with them before you accept the terms and create an account.
</Note>

## 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

```bash curl theme={null}
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):

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

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.

```bash REST theme={null}
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:

```bash Claude Code theme={null}
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](/account/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](/guides/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:

```bash curl theme={null}
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.

<Note>
  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.
</Note>

## 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.