---
name: Superdocs
description: Use when building AI-powered document editing features, integrating document generation into products, automating document workflows, or connecting AI tools to document editing via REST API or MCP. Agents should reach for this skill when they need to create, edit, analyze, or export documents through natural language instructions.
metadata:
    mintlify-proj: superdocs
    version: "1.0"
---

# SuperDocs Skill

## Product summary

SuperDocs is an AI-powered document editing platform accessible via REST API, MCP server, or web app. Send a document and a natural language instruction, and the AI edits it directly — adding sections, rewriting content, restructuring, or analyzing. The platform persists documents across sessions (called Files), supports multi-document editing, human-in-the-loop approval workflows, and exports to DOCX, PDF, HTML, Markdown, or plain text. Primary docs: https://docs.superdocs.app. Key endpoints: `POST /v1/chat` (sync editing), `POST /v1/chat/async` (long operations), `GET /v1/documents` (list Files), `POST /v1/documents/export` (export). MCP server at `https://api.superdocs.app/mcp/` with 38 tools. Authentication: `Authorization: Bearer sk_YOUR_API_KEY` header.

## When to use

Reach for this skill when:
- An agent needs to create, edit, or analyze documents via natural language (e.g., "add a confidentiality clause to section 3")
- Building a product feature that generates or modifies documents (contracts, reports, proposals, handbooks)
- Automating document workflows — batch processing, multi-step edits, approval chains
- Integrating document editing into Claude Desktop, Cursor, VS Code, or other MCP-aware tools
- The agent needs to work with multiple documents in one session (tabs/multi-document mode)
- Exporting documents in multiple formats (DOCX, PDF, HTML, Markdown)
- Implementing human-in-the-loop approval before AI changes are applied
- Handling long-running operations that need progress tracking or background processing
- The agent is autonomous and needs its own account (agent self-signup)

## Quick reference

### Authentication
```bash
curl -H "Authorization: Bearer sk_YOUR_API_KEY" https://api.superdocs.app/v1/chat
```
Keys start with `sk_` and are created in Settings > API Keys at use.superdocs.app. Verify a key works with `GET /v1/sessions` (free, no operations consumed).

### Core endpoints
| Endpoint | Purpose |
|----------|---------|
| `POST /v1/chat` | Synchronous edit/create/analyze (blocks until done) |
| `POST /v1/chat/async` | Async edit (returns job_id, poll for status) |
| `GET /v1/documents` | List saved Files |
| `POST /v1/documents/upload` | Load a file (DOCX, PDF, etc.) into a session |
| `POST /v1/documents/export` | Export document as DOCX, PDF, HTML, Markdown, or TXT |
| `GET /v1/sessions/{id}/history` | Load full conversation history and document state |
| `POST /v1/sessions/{id}/revert` | Rewind chat and document to before a user message |
| `POST /v1/chat/async/{session_id}/approve` | Approve/deny AI-proposed changes (HITL) |
| `GET /v1/jobs/{job_id}` | Poll async job status |

### Session and File IDs
- **Session ID**: Any string you choose (e.g., `user_123_contract-draft`). First request with a new session_id creates it; reuse the same id to continue. Sessions persist indefinitely.
- **File ID** (durable_document_id): Returned by upload/create, used to reopen saved documents across sessions. Same id works in `list_documents`, `get_document_detail`, `rename_document`, `archive_document`.

### Model tiers and thinking depth
```json
{
  "message": "Rewrite section 3",
  "session_id": "my-session",
  "model_tier": "core",
  "thinking_depth": "balanced"
}
```
Tiers: `turbo` (fastest, lowest cost), `core` (default, balanced), `pro` (complex analysis), `max` (most capable). Depths: `fast`, `balanced` (default, dynamic), `deep` (extended reasoning). Use `pro` or `max` + `deep` for high-stakes documents (contracts, medical, regulatory).

### Operation billing
- Most requests: **1 operation**
- Large creations (96+ sections): **1 per 25 sections**
- Failed operations: **0 operations**
- Already-satisfied requests: **0 operations**
- Reads (structure, list, job polling): **free**
- Searches: **1 operation**
Check remaining quota: `GET /v1/agents/whoami` or `get_account_status` MCP tool.

## Decision guidance

| Scenario | Use sync (`/v1/chat`) | Use async (`/v1/chat/async`) |
|----------|----------------------|------------------------------|
| Quick edits, interactive chat | ✓ | — |
| Long operations (whole handbook, restructure) | — | ✓ |
| Need progress tracking or SSE streaming | — | ✓ |
| Human-in-the-loop approval required | — | ✓ |
| Background/batch processing | — | ✓ |
| Simple integrations, fast response needed | ✓ | — |

| Document type | Suggested tier | Suggested depth |
|---------------|----------------|-----------------|
| Typo fix, quick reword | `core` | `fast` |
| Multi-section edit | `core` | `balanced` |
| Complex contract analysis | `pro` or `max` | `deep` |
| Batch processing (100+ docs) | `turbo` | `fast` or `balanced` |
| High-stakes (legal, medical, regulatory) | `pro` or `max` | `deep` |

| Need | Use |
|------|-----|
| Load a file to edit | `POST /v1/documents/upload` (sync, immediate) |
| Reference material for AI context | `POST /v1/attachments/upload` (async, indexed) |
| Save a document for later | Automatic — every document is a File |
| Reopen a saved document | `POST /v1/sessions/{id}/documents/open` with document_id |
| Export for delivery | `POST /v1/documents/export` with format (docx, pdf, html, markdown, txt) |

## Workflow

### 1. Understand the task
- Is this a quick edit (sync) or long operation (async)?
- Does the document exist or need to be created?
- Is human approval required before changes apply?
- What's the output format (DOCX, PDF, etc.)?

### 2. Prepare the document
- **If uploading a file**: `POST /v1/documents/upload` with session_id and file (DOCX, PDF, HTML, TXT, MD, RTF, ODT supported)
- **If starting from scratch**: Send just a message to an empty session; AI generates the document
- **If reopening a saved File**: `POST /v1/sessions/{id}/documents/open` with document_ids

### 3. Send the edit request
```bash
curl -X POST https://api.superdocs.app/v1/chat \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Add a confidentiality clause to section 3",
    "session_id": "my-session",
    "document_html": "<h1>Contract</h1>...",
    "model_tier": "core",
    "approval_mode": "approve_all"
  }'
```
For long operations, use `/v1/chat/async` and poll `/v1/jobs/{job_id}` for status.

### 4. Handle the response
- **Sync response**: `document_changes.updated_html` contains the new document. Render it in your editor.
- **Async response**: Get `job_id`. Poll `/v1/jobs/{job_id}` until `status` is `completed`, then read `result.document_changes.updated_html`.
- **HITL approval**: If `status` is `awaiting_approval`, read `metadata.pending_changes`, render diffs, then `POST /v1/chat/{session_id}/approve` with decisions.

### 5. Verify the result
```bash
curl https://api.superdocs.app/v1/documents/{document_id} \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
```
Read the `structure` block (free, never billed) — headings, section count, block count, media counts. Use this to verify edits without exporting.

### 6. Export or save
- **Save as File**: Automatic — every document is saved. Reopen later with `open_documents`.
- **Export**: `POST /v1/documents/export` with format (docx, pdf, html, markdown, txt) and optional filename/margins/watermark.
- **Large exports (>20 MB)**: Use pre-signed upload flow — `POST /v1/uploads` → PUT HTML to signed URL → `POST /v1/documents/export` with upload_id.

## Common gotchas

- **Don't re-send `document_html` every turn.** The server keeps the document between turns. Only re-send it when you changed the HTML outside chat (e.g., user edited in your editor) and want the AI to see those edits. Omit it on follow-up turns.
- **Preserve `data-chunk-id` attributes.** These identify document sections for targeted edits. If your HTML sanitizer strips them, configure it to preserve `data-*` attributes.
- **Session IDs must be stable.** Use the same session_id to continue a conversation. Don't generate random IDs per turn.
- **Revert blocks in-flight jobs.** Can't revert while a chat job is running on the same session. Wait for it to complete or cancel it first.
- **HITL approval requires top-level `approved` field.** Even in batch approvals, the top-level `approved` is required by the schema. Set it to true or false; per-change decisions override it.
- **Async jobs expire after 1 hour.** Pending, in-progress, and awaiting-approval jobs are cleaned up 1 hour after creation. Persist the job_id if you need to resume polling later.
- **Don't use `/v1/users/*` endpoints with API keys.** Those endpoints accept web-app session tokens only. Use `/v1/sessions`, `/v1/chat`, `/v1/documents` instead.
- **Large edits may pause mid-way.** A very large operation can pause with `awaiting_kind: "continue_prompt"` asking whether to continue. This is distinct from HITL approval. Resume with `POST /v1/chat/{session_id}/continue` with `continue: true`.
- **Exports have format-specific size caps.** DOCX/PDF/HTML: 100 MB. Markdown/TXT: 50 MB. For larger documents, use the email-fallback endpoint.
- **Agent signup is one call.** `POST /v1/agents/signup` with `{"terms_accepted": true, "agent_name": "..."}` returns a working API key. Check `~/.superdocs/agent_credentials.json` first to reuse an existing account.

## Verification checklist

Before submitting work:

- [ ] **Document structure is correct.** Call `GET /v1/documents/{id}` and check the `structure` block — headings, section count, block count match expectations.
- [ ] **No silent failures.** If the AI said "I couldn't complete that edit," the operation was not billed (0 operations). Verify the response message.
- [ ] **Session ID is stable.** Reused the same session_id across turns, not generated a new one per request.
- [ ] **Exports are in the right format.** Verified the export format (docx, pdf, html, markdown, txt) matches the requirement.
- [ ] **HITL approvals are complete.** If using `approval_mode: "ask_every_time"`, all pending changes were approved or denied before moving on.
- [ ] **Async jobs are polled to completion.** For `/v1/chat/async` requests, polled `/v1/jobs/{job_id}` until `status` is `completed`, not just until the first response.
- [ ] **API key is valid.** Ran `GET /v1/sessions` with the key and got a 200 response (not 401).
- [ ] **Quota is sufficient.** Checked remaining operations with `GET /v1/agents/whoami` before starting large batch work.
- [ ] **No data-chunk-id stripping.** If sending HTML back to the server, verified `data-chunk-id` attributes are intact.

## Resources

- **Full documentation**: https://docs.superdocs.app/llms.txt — comprehensive page-by-page navigation for agents
- **Quickstart**: https://docs.superdocs.app/introduction/quickstart — get your first API key and make your first request in 5 minutes
- **Agent editing playbook**: https://docs.superdocs.app/guides/agent-editing-playbook — field guide for AI agents doing document work (choosing operations, verification, placement, billing)
- **MCP setup**: https://docs.superdocs.app/mcp/setup — connect from Claude Desktop, Cursor, VS Code, or Claude Code

---

> For additional documentation and navigation, see: https://docs.superdocs.app/llms.txt