Q4 revenue increased by 15%.
"
})
data = response.json()
updated_html = data["document_changes"]["updated_html"]
# 2. Send the updated HTML back on the next request
response = requests.post("https://api.superdocs.app/v1/chat", headers=HEADERS, json={
"message": "Make the summary more concise",
"session_id": "my-doc",
"document_html": updated_html # send back exactly as received
})
```
The returned HTML contains `data-chunk-id` attributes on elements. These identify document sections and enable the AI to make targeted edits without reprocessing the entire document. These same IDs appear in API responses — for example, `chunk_id` and `insert_after_chunk_id` in [HITL proposed changes](/guides/human-in-the-loop#understanding-proposed-changes).
# Sessions
Source: https://superdocs.mintlify.app/concepts/sessions
Sessions persist conversation history and document state across requests. You choose the session ID.
# Sessions
A session holds your conversation history and document state. Reuse a session ID to pick up where you left off.
## How sessions work
You choose the `session_id` — any string you want. The API stores the conversation and document state for that session.
```bash theme={null}
# First request — starts a new session
curl -X POST https://api.superdocs.app/v1/chat \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Add an introduction section",
"session_id": "project-proposal-v1",
"document_html": "...updated HTML from previous response...
"
}'
```
The AI remembers the full conversation. On the second request, it knows about the introduction it just wrote.
## Persistence
Sessions persist across server restarts. You can close your browser, come back tomorrow, and resume with the same `session_id`.
## List sessions
```bash theme={null}
curl https://api.superdocs.app/v1/sessions \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
Returns session IDs, message counts, timestamps, and a preview of the first message.
## Load session history
```bash theme={null}
curl https://api.superdocs.app/v1/sessions/project-proposal-v1/history \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
The response includes:
* `messages` — Full conversation history
* `document_state` — Current document HTML, version ID, and attachment list
* `editor_action` — What to do with the document: `"update"` (load the HTML), `"clear"` (reset), or `"keep"` (no change)
## Session isolation
Sessions are isolated per user. Your sessions are never visible to other users.
## B2B session management
If you're serving multiple end users through a single API key, manage session IDs per user on your end. For example, prefix session IDs with your user's identifier:
```
session_id: "user_123_draft-contract"
session_id: "user_456_meeting-notes"
```
This keeps each user's conversations and documents separate.
## Delete a session
```bash theme={null}
curl -X DELETE https://api.superdocs.app/v1/users/me/sessions/project-proposal-v1 \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
# Templates
Source: https://superdocs.mintlify.app/concepts/templates
Upload reusable document templates that the AI can search and apply when creating content.
# Templates
Upload document templates for the AI to reference. When you ask the AI to create a document, it can search your templates and use them as a starting point.
## Upload a template
Templates support the same file types as attachments: `.docx`, `.pdf`, `.txt`, `.rtf`, `.md`.
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/templates/upload \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-F "file=@nda-template.docx"
```
Template processing is synchronous — the template is ready immediately after upload.
## List your templates
```bash theme={null}
curl https://api.superdocs.app/v1/templates \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## Delete a template
```bash theme={null}
curl -X DELETE https://api.superdocs.app/v1/templates/TEMPLATE_ID \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## How the AI uses templates
When you ask the AI to create a document (e.g., "Draft an NDA"), it searches your uploaded templates for relevant matches. If a template fits, the AI uses it as a starting point and customizes it based on your instructions.
Templates are scoped per user or organization — your templates are only visible to you.
# Error Codes
Source: https://superdocs.mintlify.app/errors/error-codes
HTTP status codes, error response format, and common error scenarios for the SuperDocs API.
# Error Codes
All API errors return a JSON response with a `detail` field:
```json theme={null}
{
"detail": "Human-readable error message"
}
```
## Status codes
| Code | Meaning | Common causes |
| ------- | --------------------- | -------------------------------------------------------- |
| **400** | Bad Request | Empty message, unsupported file type, invalid parameters |
| **401** | Unauthorized | Missing or invalid API key, expired token |
| **403** | Forbidden | Accessing a resource you don't own |
| **404** | Not Found | Job, session, template, or attachment doesn't exist |
| **422** | Validation Error | Request body doesn't match expected schema |
| **429** | Too Many Requests | Monthly operation limit reached |
| **500** | Internal Server Error | Unexpected server error |
| **504** | Gateway Timeout | AI processing exceeded 10 minutes |
## Common errors and fixes
### Authentication errors (401)
```json theme={null}
{"detail": "Invalid authorization header format. Expected 'Bearer '"}
```
**Fix:** Use `Authorization: Bearer sk_YOUR_KEY` (include the `Bearer ` prefix).
```json theme={null}
{"detail": "Invalid API key"}
```
**Fix:** Check that your key is correct and hasn't been revoked. Generate a new key from Settings > API Keys.
### Validation errors (400)
```json theme={null}
{"detail": "Message cannot be empty. Please provide a text message."}
```
**Fix:** Include a non-empty `message` in your request body.
```json theme={null}
{"detail": "Legacy .doc files are not supported. Please convert to .docx format and try again."}
```
**Fix:** Use a supported format (`.pdf`, `.docx`, `.txt`, `.rtf`, `.md`). Convert `.doc` files to `.docx`.
### Rate limit (429)
```json theme={null}
{"detail": "Monthly operation limit (500) reached. Upgrade your plan for more operations."}
```
**Fix:** Upgrade your plan at Settings > Billing, or wait for your monthly reset. Check the `usage` object in chat responses to monitor remaining operations.
### Timeout (504)
```json theme={null}
{"detail": "Request timed out. The AI agent took longer than 10 minutes to process your request. Please try again with a simpler request or contact support."}
```
**Fix:** Simplify your request, or break a complex task into smaller steps. Use the async endpoint (`/v1/chat/async`) for long operations.
### Not found (404)
```json theme={null}
{"detail": "Job not found"}
```
**Fix:** Jobs are cleaned up 1 hour after completion. Check the job ID and timing. Use `/v1/jobs` to list active jobs.
# Rate Limits
Source: https://superdocs.mintlify.app/errors/rate-limits
Operation limits per subscription tier, overage pricing, and how to handle 429 responses.
# Rate Limits
SuperDocs uses operation-based limits, not request-rate limits. Each AI action that modifies, analyzes, or searches a document counts as one operation.
## Limits by tier
| Plan | Included operations | At the limit | Max monthly bill |
| -------------- | ------------------- | ---------------------------------------- | ---------------- |
| **Free** | 500/mo | Pauses (429 error) | \$0 |
| **Plus** | 2,000/mo | Overage at \$0.015/op, up to 4,000 total | \$50 |
| **Pro** | 10,000/mo | Overage at \$0.015/op, no cap | Varies |
| **Enterprise** | Custom | Custom | Custom |
## Handling 429 responses
When you hit the limit on the free plan, the API returns:
```
HTTP/1.1 429 Too Many Requests
X-Usage-Limit: 500
X-Usage-Used: 500
X-Usage-Remaining: 0
{"detail": "Monthly operation limit (500) reached. Upgrade your plan for more operations."}
```
**Best practices:**
* Check the `usage` object in chat responses to track remaining operations
* Call `GET /v1/users/me/limits` before critical workflows
* Upgrade to a paid plan for uninterrupted access
## Check remaining operations
### From API responses
Every chat response includes usage data:
```json theme={null}
{
"usage": {
"monthly_used": 480,
"monthly_limit": 500,
"monthly_remaining": 20,
"was_billable": true,
"subscription_tier": "free"
}
}
```
### Via dedicated endpoint
```bash theme={null}
curl https://api.superdocs.app/v1/users/me/limits \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## Monthly reset
Operations reset at the start of each billing cycle. Free plans reset monthly from account creation. Paid plans reset on each billing renewal date.
# curl Examples
Source: https://superdocs.mintlify.app/examples/curl
Copy-paste ready curl commands for every key SuperDocs API operation.
# curl Examples
Replace `sk_YOUR_API_KEY` with your actual API key in all commands.
## Chat
### Send a message with document
```bash theme={null}
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 summary section at the top",
"session_id": "curl-demo",
"document_html": "Report
Q4 revenue increased 15%.
"
}'
```
### Send a message without document
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Draft a project proposal outline",
"session_id": "curl-demo"
}'
```
### Chat with model selection
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Analyze this contract for potential risks",
"session_id": "curl-demo",
"document_html": "...",
"model_tier": "max",
"thinking_depth": "deep"
}'
```
## Async chat
### Start an async request
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat/async \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Rewrite this document in formal language",
"session_id": "async-demo",
"document_html": "..."
}'
```
## Jobs
### Check job status
```bash theme={null}
curl https://api.superdocs.app/v1/jobs/JOB_ID \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### List all jobs
```bash theme={null}
curl https://api.superdocs.app/v1/jobs \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### Cancel a job
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/jobs/JOB_ID/cancel \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## Sessions
### List sessions
```bash theme={null}
curl https://api.superdocs.app/v1/sessions \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### Get session history
```bash theme={null}
curl https://api.superdocs.app/v1/sessions/SESSION_ID/history \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### Get session jobs
```bash theme={null}
curl https://api.superdocs.app/v1/sessions/SESSION_ID/jobs \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### Delete a session
```bash theme={null}
curl -X DELETE https://api.superdocs.app/v1/users/me/sessions/SESSION_ID \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## Attachments
### Upload a file
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/attachments/upload \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-F "file=@document.pdf" \
-F "session_id=my-session"
```
### Check attachment status
```bash theme={null}
curl https://api.superdocs.app/v1/attachments/status/SESSION_ID \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### Delete an attachment
```bash theme={null}
curl -X DELETE "https://api.superdocs.app/v1/attachments/ATTACHMENT_ID?session_id=my-session" \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## Templates
### Upload a template
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/templates/upload \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-F "file=@template.docx"
```
### List templates
```bash theme={null}
curl https://api.superdocs.app/v1/templates \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### Delete a template
```bash theme={null}
curl -X DELETE https://api.superdocs.app/v1/templates/TEMPLATE_ID \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## HITL approval
### Approve a single change
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat/SESSION_ID/approve \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "JOB_ID",
"change_id": "CHANGE_ID",
"approved": true
}'
```
### Approve multiple changes
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat/SESSION_ID/approve \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "JOB_ID",
"approved": true,
"changes": [
{"change_id": "ch_1", "approved": true},
{"change_id": "ch_2", "approved": false}
]
}'
```
### Deny with feedback
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat/SESSION_ID/approve \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "JOB_ID",
"change_id": "CHANGE_ID",
"approved": false,
"feedback": "Keep the original wording but add a reference to GDPR"
}'
```
## User management
### Get profile
```bash theme={null}
curl https://api.superdocs.app/v1/users/me \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### Get usage stats
```bash theme={null}
curl https://api.superdocs.app/v1/users/me/usage \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### Get tier limits
```bash theme={null}
curl https://api.superdocs.app/v1/users/me/limits \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## Health check
```bash theme={null}
curl https://api.superdocs.app/health
```
# JavaScript Examples
Source: https://superdocs.mintlify.app/examples/javascript
Complete working JavaScript examples for the SuperDocs API using fetch and EventSource.
# JavaScript Examples
All examples use the native `fetch` API and work in browsers and Node.js 18+.
## Basic chat with document
```javascript theme={null}
const API_KEY = "sk_YOUR_API_KEY";
const BASE = "https://api.superdocs.app";
async function chat(message, sessionId, documentHtml = null) {
const response = await fetch(`${BASE}/v1/chat`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
message,
session_id: sessionId,
document_html: documentHtml
})
});
return response.json();
}
// Usage
const data = await chat(
"Add an introduction paragraph",
"js-demo",
"My Document
Content here.
"
);
console.log("AI:", data.response);
if (data.document_changes) {
console.log("Updated HTML:", data.document_changes.updated_html);
}
```
## EventSource streaming
```javascript theme={null}
async function streamChat(message, sessionId, documentHtml) {
// 1. Start async job
const response = await fetch(`${BASE}/v1/chat/async`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
message,
session_id: sessionId,
document_html: documentHtml
})
});
const { job_id } = await response.json();
// 2. Open SSE stream
return new Promise((resolve, reject) => {
const url = `${BASE}/v1/chat/${sessionId}/stream?job_id=${job_id}&api_key=${API_KEY}`;
const eventSource = new EventSource(url);
eventSource.addEventListener("intermediate", (event) => {
const data = JSON.parse(event.data);
console.log("Progress:", data.content);
});
eventSource.addEventListener("final", (event) => {
const data = JSON.parse(event.data);
eventSource.close();
resolve(data.result);
});
eventSource.addEventListener("usage", (event) => {
const data = JSON.parse(event.data);
console.log(`Operations: ${data.monthly_used}/${data.monthly_limit}`);
});
eventSource.addEventListener("error", (event) => {
eventSource.close();
if (event.data) {
reject(new Error(JSON.parse(event.data).error));
}
});
});
}
// Usage
const result = await streamChat(
"Rewrite section 2 to be more formal",
"streaming-demo",
currentHtml
);
console.log("AI:", result.response);
```
## File upload
```javascript theme={null}
async function uploadAttachment(file, sessionId) {
const formData = new FormData();
formData.append("file", file);
formData.append("session_id", sessionId);
const response = await fetch(`${BASE}/v1/attachments/upload`, {
method: "POST",
headers: { "Authorization": `Bearer ${API_KEY}` },
body: formData
});
return response.json();
}
// Browser usage
const fileInput = document.querySelector('input[type="file"]');
const result = await uploadAttachment(fileInput.files[0], "my-session");
console.log("Job ID:", result.job_id);
```
## Job polling
```javascript theme={null}
async function pollJob(jobId) {
while (true) {
const response = await fetch(`${BASE}/v1/jobs/${jobId}`, {
headers: { "Authorization": `Bearer ${API_KEY}` }
});
const job = await response.json();
if (job.status === "completed") return job.result;
if (job.status === "failed") throw new Error(job.error);
if (job.status === "awaiting_approval") return job;
await new Promise(r => setTimeout(r, 2000));
}
}
// Usage
const { job_id } = await uploadAttachment(file, "my-session");
const result = await pollJob(job_id);
console.log("Attachment processed:", result.attachment_id);
```
## HITL approval
```javascript theme={null}
async function chatWithApproval(message, sessionId, documentHtml) {
// Start with approval mode
const response = await fetch(`${BASE}/v1/chat/async`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
message,
session_id: sessionId,
document_html: documentHtml,
approval_mode: "ask_every_time"
})
});
const { job_id } = await response.json();
// Poll and approve
while (true) {
const jobResponse = await fetch(`${BASE}/v1/jobs/${job_id}`, {
headers: { "Authorization": `Bearer ${API_KEY}` }
});
const job = await jobResponse.json();
if (job.status === "completed") return job.result;
if (job.status === "failed") throw new Error(job.error);
if (job.status === "awaiting_approval") {
const changes = job.metadata.pending_changes;
console.log(`${changes.length} change(s) proposed`);
// Auto-approve all (replace with UI in production)
await fetch(`${BASE}/v1/chat/${sessionId}/approve`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
job_id,
approved: true,
changes: changes.map(c => ({ change_id: c.change_id, approved: true }))
})
});
}
await new Promise(r => setTimeout(r, 2000));
}
}
```
# Python Examples
Source: https://superdocs.mintlify.app/examples/python
Complete working Python examples for the SuperDocs API using the requests library.
# Python Examples
All examples use the `requests` library. Install it with `pip install requests`.
## Basic chat with document
```python theme={null}
import requests
API_KEY = "sk_YOUR_API_KEY"
BASE = "https://api.superdocs.app"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
response = requests.post(f"{BASE}/v1/chat", headers=HEADERS, json={
"message": "Add an executive summary at the top",
"session_id": "python-demo",
"document_html": "Q4 Report
Revenue grew 15% year over year.
"
})
data = response.json()
print("AI:", data["response"])
if data.get("document_changes"):
updated_html = data["document_changes"]["updated_html"]
print("Document updated. Version:", data["document_changes"]["version_id"])
```
## Handle response and preserve HTML
```python theme={null}
# First request
response = requests.post(f"{BASE}/v1/chat", headers=HEADERS, json={
"message": "Create a project plan with 3 sections",
"session_id": "project-plan",
"document_html": ""
})
data = response.json()
current_html = data["document_changes"]["updated_html"]
# Second request — send the HTML back as-is
response = requests.post(f"{BASE}/v1/chat", headers=HEADERS, json={
"message": "Add deadlines to each section",
"session_id": "project-plan",
"document_html": current_html # preserve data-chunk-id attributes
})
data = response.json()
current_html = data["document_changes"]["updated_html"]
```
## Upload attachment and poll for completion
```python theme={null}
import time
# Upload
with open("reference.pdf", "rb") as f:
response = requests.post(
f"{BASE}/v1/attachments/upload",
headers={"Authorization": f"Bearer {API_KEY}"},
files={"file": ("reference.pdf", f, "application/pdf")},
data={"session_id": "my-session"}
)
job_id = response.json()["job_id"]
print(f"Upload started: {job_id}")
# Poll until ready
while True:
job = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS).json()
if job["status"] == "completed":
print("Attachment ready")
break
elif job["status"] == "failed":
print("Processing failed:", job["error"])
break
time.sleep(2)
# Now chat — the AI can reference the attachment
response = requests.post(f"{BASE}/v1/chat", headers=HEADERS, json={
"message": "Summarize the key points from the uploaded reference document",
"session_id": "my-session"
})
print("AI:", response.json()["response"])
```
## Async job with polling
```python theme={null}
import time
# Start async
response = requests.post(f"{BASE}/v1/chat/async", headers=HEADERS, json={
"message": "Rewrite this entire document in formal legal language",
"session_id": "legal-rewrite",
"document_html": "Agreement
We agree to work together on the project.
"
})
job_id = response.json()["job_id"]
# Poll
while True:
job = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS).json()
print(f"Status: {job['status']}")
if job["status"] == "completed":
result = job["result"]
print("AI:", result["response"])
if result.get("document_changes"):
print("Updated HTML:", result["document_changes"]["updated_html"][:200])
break
elif job["status"] == "failed":
print("Error:", job["error"])
break
time.sleep(2)
```
## SSE streaming
```python theme={null}
import json
import requests
# Start async job first
response = requests.post(f"{BASE}/v1/chat/async", headers=HEADERS, json={
"message": "Write a detailed analysis of section 2",
"session_id": "streaming-demo",
"document_html": "..."
})
job_id = response.json()["job_id"]
# Stream progress
url = f"{BASE}/v1/chat/streaming-demo/stream?job_id={job_id}&api_key={API_KEY}"
with requests.get(url, stream=True) as stream:
current_event = None
for line in stream.iter_lines():
if not line:
continue
decoded = line.decode("utf-8")
if decoded.startswith("event: "):
current_event = decoded[7:]
elif decoded.startswith("data: "):
data = json.loads(decoded[6:])
if current_event == "intermediate":
print(f"Progress: {data['content']}")
elif current_event == "final":
print(f"Done: {data['result']['response'][:100]}")
break
elif current_event == "error":
print(f"Error: {data['error']}")
break
```
## HITL approval flow
```python theme={null}
import time
# Start with approval mode
response = requests.post(f"{BASE}/v1/chat/async", headers=HEADERS, json={
"message": "Update the liability clause to cap damages at $1M",
"session_id": "contract-review",
"document_html": "...",
"approval_mode": "ask_every_time"
})
job_id = response.json()["job_id"]
# Poll and approve
while True:
job = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS).json()
if job["status"] == "completed":
print("Done:", job["result"]["response"])
break
elif job["status"] == "failed":
print("Error:", job["error"])
break
elif job["status"] == "awaiting_approval":
changes = job["metadata"]["pending_changes"]
print(f"\n{len(changes)} change(s) proposed:")
for c in changes:
print(f" - {c['operation']}: {c.get('ai_explanation', 'No explanation')}")
# Approve all
requests.post(f"{BASE}/v1/chat/contract-review/approve", headers=HEADERS, json={
"job_id": job_id,
"approved": True,
"changes": [{"change_id": c["change_id"], "approved": True} for c in changes]
})
print("Approved all changes")
time.sleep(2)
```
# AI-to-AI Integration
Source: https://superdocs.mintlify.app/guides/ai-to-ai
Connect your AI agent to SuperDocs for autonomous document editing without a browser.
# AI-to-AI Integration
Your AI agent can use SuperDocs as a document editing tool. No browser, no frontend — just API calls. Your AI decides what to edit, SuperDocs executes.
## How it works
This creates a loop: your AI agent controls *what* to edit, SuperDocs handles *how* to edit it.
## Example: Autonomous document workflow
```python theme={null}
import requests
API_KEY = "sk_YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
BASE = "https://api.superdocs.app/v1/chat"
# Your AI agent's workflow
tasks = [
"Create a project proposal with 4 sections: Overview, Goals, Timeline, Budget",
"Add specific milestones to the Timeline section",
"Add cost estimates to the Budget section",
"Review the entire document and fix any inconsistencies"
]
session_id = "ai-agent-proposal"
document_html = ""
for task in tasks:
response = requests.post(BASE, headers=HEADERS, json={
"message": task,
"session_id": session_id,
"document_html": document_html
})
data = response.json()
print(f"Task: {task}")
print(f"AI: {data['response'][:100]}...")
# Use the updated document for the next task
if data.get("document_changes"):
document_html = data["document_changes"]["updated_html"]
print("\nFinal document ready.")
```
## Session persistence
Use the same `session_id` across calls. SuperDocs remembers the full conversation, so your agent can reference previous changes:
```python theme={null}
# First call
requests.post(BASE, headers=HEADERS, json={
"message": "Draft a sales contract",
"session_id": "agent-contract",
"document_html": ""
})
# Later call — SuperDocs remembers the contract it drafted
requests.post(BASE, headers=HEADERS, json={
"message": "Add a payment terms section based on net-30",
"session_id": "agent-contract",
"document_html": current_html
})
```
## With MCP
If your AI agent supports MCP (like Claude), connect it directly to SuperDocs. See [MCP Integration](/mcp/setup) for setup. The AI agent gets native access to all 16 SuperDocs tools without writing any API client code.
# Async Jobs
Source: https://superdocs.mintlify.app/guides/async-jobs
Use async chat requests with job polling for long-running operations and background processing.
# Async Jobs
The sync endpoint (`POST /v1/chat`) waits for the AI to finish before responding. For long operations or background processing, use the async endpoint instead.
## When to use async
| Use sync (`/v1/chat`) | Use async (`/v1/chat/async`) |
| ------------------------- | ----------------------------- |
| Quick edits and questions | Complex multi-step operations |
| Interactive chat UI | Background processing |
| Simple integrations | SSE streaming for progress |
| | HITL approval workflows |
## Async flow
### 1. Start the job
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat/async \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Restructure this entire document into 5 sections",
"session_id": "my-session",
"document_html": "..."
}'
```
Response:
```json theme={null}
{
"job_id": "job_abc123",
"session_id": "my-session",
"status": "pending",
"message": "Chat request queued for processing"
}
```
### 2. Poll for status
```bash theme={null}
curl https://api.superdocs.app/v1/jobs/job_abc123 \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
### 3. Get the result
When `status` is `"completed"`, the `result` field contains the AI response and document changes:
```json theme={null}
{
"job_id": "job_abc123",
"status": "completed",
"result": {
"response": "I've restructured the document into 5 sections...",
"session_id": "my-session",
"document_changes": {
"updated_html": "...
",
"version_id": "...",
"changes_summary": "Document updated by AI"
},
"usage": {
"monthly_used": 44,
"monthly_limit": 500,
"monthly_remaining": 456,
"was_billable": true,
"subscription_tier": "free"
}
}
}
```
## Job statuses
| Status | Meaning | What to do |
| ------------------- | ------------------------------------ | ------------------------------------------------------ |
| `pending` | Queued, waiting to start | Keep polling |
| `in_progress` | AI is processing | Keep polling |
| `awaiting_approval` | HITL mode — changes need your review | Check `metadata.pending_changes`, then call `/approve` |
| `completed` | Finished | Read `result` |
| `failed` | Error occurred | Read `error` field |
| `cancelled` | Cancelled by you | No action needed |
## Cancel a job
Only `pending` and `in_progress` jobs can be cancelled:
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/jobs/job_abc123/cancel \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## List all jobs
```bash theme={null}
curl https://api.superdocs.app/v1/jobs \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
## Polling example
```python theme={null}
import time
import requests
API_KEY = "sk_YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# Start async job
response = requests.post("https://api.superdocs.app/v1/chat/async",
headers={**HEADERS, "Content-Type": "application/json"},
json={"message": "Summarize this document", "session_id": "my-session", "document_html": "..."}
)
job_id = response.json()["job_id"]
# Poll until complete
while True:
job = requests.get(f"https://api.superdocs.app/v1/jobs/{job_id}", headers=HEADERS).json()
if job["status"] == "completed":
print("AI response:", job["result"]["response"])
break
elif job["status"] == "failed":
print("Error:", job["error"])
break
elif job["status"] == "awaiting_approval":
print("Changes need approval:", job["metadata"]["pending_changes"])
break
time.sleep(2)
```
Jobs are automatically cleaned up 1 hour after completion, failure, or cancellation. Jobs in `awaiting_approval` status are also cleaned up after 1 hour — approve or deny changes within this window.
# Human-in-the-Loop
Source: https://superdocs.mintlify.app/guides/human-in-the-loop
Review and approve AI-proposed document changes before they're applied, using the HITL approval workflow.
# Human-in-the-Loop
By default, the AI applies changes immediately. Set `approval_mode` to `"ask_every_time"` to review changes before they take effect.
HITL requires the async workflow (`/v1/chat/async`) because the job pauses to wait for your approval.
## End-to-end workflow
### 1. Send a request with approval mode
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat/async \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Update section 3 to include GDPR compliance language",
"session_id": "contract-review",
"document_html": "...",
"approval_mode": "ask_every_time"
}'
```
### 2. Poll for approval status
```bash theme={null}
curl https://api.superdocs.app/v1/jobs/JOB_ID \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
When `status` is `"awaiting_approval"`, check `metadata.pending_changes`:
```json theme={null}
{
"status": "awaiting_approval",
"metadata": {
"pending_changes": [
{
"change_id": "ch_1",
"operation": "edit",
"chunk_id": "550e8400-e29b-41d4-a716-446655440000",
"old_html": "Original section 3 content...
",
"new_html": "Updated content with GDPR compliance...
",
"ai_explanation": "Added GDPR data processing requirements"
}
]
}
}
```
### 3. Approve or deny changes
**Approve a single change:**
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat/contract-review/approve \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "JOB_ID",
"change_id": "ch_1",
"approved": true
}'
```
**Approve all changes at once:**
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat/contract-review/approve \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "JOB_ID",
"approved": true,
"changes": [
{"change_id": "ch_1", "approved": true},
{"change_id": "ch_2", "approved": false}
]
}'
```
**Deny with feedback:**
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat/contract-review/approve \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_id": "JOB_ID",
"change_id": "ch_1",
"approved": false,
"feedback": "Keep the original language but add a GDPR reference link"
}'
```
### 4. Continue polling
After approval, the job resumes processing. Poll until `status` is `"completed"` to get the final result.
If you deny a change with feedback, the AI receives your feedback and may propose a revised change. Your polling loop should handle multiple rounds of `awaiting_approval` — not just one.
## Understanding proposed changes
### Operation types
Each proposed change has an `operation` field that determines what the AI wants to do and which fields are populated:
| Operation | `old_html` | `new_html` | `insert_after_chunk_id` | Meaning |
| --------- | --------------------- | -------------------- | ----------------------- | ---------------------------------- |
| `edit` | Current content | Proposed replacement | — | Modify an existing section |
| `create` | null | New content to add | Section to insert after | Add a new section to the document |
| `delete` | Content being removed | null | — | Remove a section from the document |
### Building a diff view
To show users what the AI wants to change, compare `old_html` and `new_html`:
* **For `edit`**: Use a diff library (like `diff-match-patch` or `jsdiff`) to highlight additions and removals between `old_html` and `new_html`. Show a before/after view or inline diff.
* **For `create`**: Display `new_html` with a visual indicator that this is a new section being added (e.g., a green border or "New section" label). The `insert_after_chunk_id` value corresponds to a `data-chunk-id` attribute on an element in the document HTML — find that element and insert the new content after it.
* **For `delete`**: Display `old_html` with a visual indicator that this section will be removed (e.g., red strikethrough or "Will be deleted" label).
Always display the `ai_explanation` alongside the diff — it tells the user why the AI proposed the change.
### Batch changes
When the AI proposes multiple changes at once, each change includes:
* `batch_id` — Groups related changes. All changes in a batch share the same `batch_id`.
* `batch_total` — How many changes are in this batch.
If you're receiving changes via SSE, wait for `batch_total` events with the same `batch_id` before showing the review UI. You can then offer "Accept All" and "Deny All" buttons alongside individual change controls.
For polling, all changes appear together in the `metadata.pending_changes` array.
## Alternative: SSE streaming workflow
The polling workflow above works but requires repeated API calls. For a real-time UI, use SSE to receive proposed changes as they're generated:
```javascript theme={null}
// 1. Start async request with approval mode
const response = await fetch("https://api.superdocs.app/v1/chat/async", {
method: "POST",
headers: { "Authorization": "Bearer sk_YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
message: "Rewrite the liability section",
session_id: "contract-review",
document_html: "...",
approval_mode: "ask_every_time"
})
});
const { job_id } = await response.json();
// 2. Open SSE connection
const es = new EventSource(
`https://api.superdocs.app/v1/chat/contract-review/stream?job_id=${job_id}&api_key=sk_YOUR_API_KEY`
);
// 3. Collect proposed changes
const pendingChanges = [];
es.addEventListener("proposed_change", (event) => {
const data = JSON.parse(event.data);
const change = JSON.parse(data.content); // content is JSON-stringified
pendingChanges.push(change);
// Show the change to the user with a diff view
console.log(`Change ${change.change_id}: ${change.operation}`);
console.log(` Explanation: ${change.ai_explanation}`);
console.log(` Old: ${change.old_html}`);
console.log(` New: ${change.new_html}`);
// If batch, wait for all changes before showing review UI
if (change.batch_total && pendingChanges.length < change.batch_total) {
return; // Wait for more changes
}
// Show approve/deny UI to the user here
// When user decides, call the approve endpoint (see step 3 above)
});
es.addEventListener("final", (event) => {
const data = JSON.parse(event.data);
console.log("Done:", data.result.response);
// Apply data.result.document_changes.updated_html to your editor
es.close();
});
es.addEventListener("error", (event) => {
if (event.data) {
const data = JSON.parse(event.data);
console.error("Error:", data.error);
}
es.close();
});
```
After calling `/approve`, the AI resumes processing. If approved changes were applied, the SSE connection will eventually emit a `final` event with the updated document. If you denied with feedback, you may receive new `proposed_change` events as the AI tries again.
## Complete Python example
```python theme={null}
import time
import requests
API_KEY = "sk_YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
BASE = "https://api.superdocs.app"
# 1. Start with approval mode
response = requests.post(f"{BASE}/v1/chat/async", headers=HEADERS, json={
"message": "Rewrite the liability section",
"session_id": "contract-review",
"document_html": "...",
"approval_mode": "ask_every_time"
})
job_id = response.json()["job_id"]
# 2. Poll and handle approvals
while True:
job = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS).json()
if job["status"] == "completed":
print("Done:", job["result"]["response"])
break
elif job["status"] == "failed":
print("Error:", job["error"])
break
elif job["status"] == "awaiting_approval":
changes = job["metadata"]["pending_changes"]
for change in changes:
print(f"\nChange {change['change_id']}:")
print(f" Operation: {change['operation']}")
print(f" Explanation: {change.get('ai_explanation', 'N/A')}")
print(f" Old: {change.get('old_html', 'N/A')[:100]}")
print(f" New: {change.get('new_html', 'N/A')[:100]}")
# Approve all changes
requests.post(f"{BASE}/v1/chat/contract-review/approve", headers=HEADERS, json={
"job_id": job_id,
"approved": True,
"changes": [{"change_id": c["change_id"], "approved": True} for c in changes]
})
print("\nApproved all changes, continuing...")
time.sleep(2)
```
# Model Selection
Source: https://superdocs.mintlify.app/guides/model-selection
Choose from four AI model tiers and three thinking depths to balance speed, capability, and cost.
# Model Selection
SuperDocs offers four model tiers and three thinking depths. All tiers are available on every plan.
## Model tiers
Set `model_tier` in your request to choose a model:
| Tier | Best for | Speed | Thinking depth control |
| ------- | ------------------------------------ | -------- | ---------------------- |
| `core` | Everyday editing, quick tasks | Fast | Yes |
| `turbo` | Speed-critical workflows | Fastest | No — always optimized |
| `pro` | Complex analysis, multi-step edits | Moderate | No — always optimized |
| `max` | Challenging documents, nuanced tasks | Slower | Yes |
Default: `core`
## Thinking depth
Set `thinking_depth` to control how much reasoning the AI applies:
| Depth | Behavior |
| ---------- | ------------------------------------------ |
| `fast` | Quick responses, minimal reasoning |
| `balanced` | AI decides when to reason deeply (default) |
| `deep` | Extended reasoning for complex problems |
Default: `balanced`
Thinking depth control is available for the `core` and `max` tiers. The `turbo` and `pro` tiers use their own optimized reasoning — the `thinking_depth` parameter is ignored for these models. You don't need to configure it; they always use the best reasoning depth for the task.
## Usage
```bash theme={null}
# Core with custom thinking depth
curl -X POST https://api.superdocs.app/v1/chat \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Analyze this contract for potential risks",
"session_id": "my-session",
"document_html": "...",
"model_tier": "core",
"thinking_depth": "deep"
}'
# Pro — no thinking_depth needed, reasoning is always optimized
curl -X POST https://api.superdocs.app/v1/chat \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Analyze this contract for potential risks",
"session_id": "my-session",
"document_html": "...",
"model_tier": "pro"
}'
```
## Recommendations
| Task | Suggested tier | Suggested depth |
| ------------------------------- | --------------- | ----------------- |
| Fix a typo | `core` | `fast` |
| Rewrite a paragraph | `core` | `balanced` |
| Draft a multi-section document | `core` or `max` | `deep` |
| Analyze a complex contract | `pro` or `max` | `deep` (max only) |
| Batch processing many documents | `turbo` | — |
## Default model preference
You can set a default model tier in your account preferences (via the web app). Per-request `model_tier` overrides your default.
# SSE Streaming
Source: https://superdocs.mintlify.app/guides/streaming
Stream real-time progress updates from the AI using Server-Sent Events (SSE).
# SSE Streaming
For long-running AI operations, use Server-Sent Events (SSE) to receive real-time progress updates instead of waiting for the full response.
## How it works
1. Start an async chat request to get a `job_id`
2. Open an SSE connection to stream progress
3. Receive events as the AI processes your request
## Setup
```bash theme={null}
# 1. Start an async request
curl -X POST https://api.superdocs.app/v1/chat/async \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Rewrite all sections to be more concise",
"session_id": "my-session",
"document_html": "..."
}'
# Response: { "job_id": "job_abc123", "session_id": "my-session", ... }
# 2. Stream progress (auth via query parameter)
curl -N "https://api.superdocs.app/v1/chat/my-session/stream?job_id=job_abc123&api_key=sk_YOUR_API_KEY"
```
SSE uses EventSource, which doesn't support custom headers. Pass your API key as the `api_key` query parameter.
## Event types
The stream emits 5 event types:
### `intermediate`
Progress updates during AI processing.
```
event: intermediate
data: {"type": "intermediate", "content": "Analyzing document structure...", "sequence": 1, "timestamp": "2026-03-07T10:00:01Z"}
```
### `proposed_change`
In HITL mode (`approval_mode: "ask_every_time"`), the AI proposes a document change for review. One event is emitted per proposed change.
```
event: proposed_change
data: {"type": "proposed_change", "content": "{\"change_id\": \"ch_1\", ...}", "sequence": 2}
```
The `content` field is a JSON string. Parse it to get the change details:
```json theme={null}
{
"change_id": "ch_1",
"operation": "edit",
"chunk_id": "550e8400-e29b-41d4-a716-446655440000",
"old_html": "Original section content...
",
"new_html": "Updated content with GDPR compliance...
",
"ai_explanation": "Added GDPR data processing requirements",
"batch_id": "ch_1",
"batch_total": 3,
"insert_after_chunk_id": null
}
```
| Field | Type | Description |
| ----------------------- | -------------- | ------------------------------------------------------------------------------------------- |
| `change_id` | string | Unique ID for this change. Use when calling `/approve`. |
| `operation` | string | `"edit"`, `"create"`, or `"delete"`. |
| `chunk_id` | string \| null | The document section being modified or deleted. Null for creates. |
| `old_html` | string \| null | Current HTML content. Present for updates and deletes. Null for creates. |
| `new_html` | string \| null | Proposed new HTML content. Present for updates and creates. Null for deletes. |
| `ai_explanation` | string | Why the AI proposed this change. Show this to the user. |
| `batch_id` | string \| null | Groups related changes. All changes in a batch share the same `batch_id`. |
| `batch_total` | number \| null | How many changes are in this batch. Wait for this many events before showing the review UI. |
| `insert_after_chunk_id` | string \| null | For `create`: where to insert the new section in the document. |
See the [Human-in-the-Loop guide](/guides/human-in-the-loop) for the complete approval workflow.
### `final`
Job completed successfully. Contains the full result.
```
event: final
data: {"content": "I've made all sections more concise.", "result": {"response": "...", "document_changes": {...}, "usage": {...}}}
```
### `usage`
Emitted after `final` with usage consumption data.
```
event: usage
data: {"monthly_used": 43, "monthly_limit": 500, "monthly_remaining": 457, "was_billable": true, "subscription_tier": "free"}
```
### `error`
Job failed, was cancelled, or an auth error occurred.
```
event: error
data: {"error": "Request timed out"}
```
## JavaScript example
```javascript theme={null}
const eventSource = new EventSource(
`https://api.superdocs.app/v1/chat/my-session/stream?job_id=${jobId}&api_key=${apiKey}`
);
eventSource.addEventListener("intermediate", (event) => {
const data = JSON.parse(event.data);
console.log("Progress:", data.content);
});
eventSource.addEventListener("final", (event) => {
const data = JSON.parse(event.data);
console.log("Done:", data.result.response);
// Update your editor with data.result.document_changes.updated_html
eventSource.close();
});
eventSource.addEventListener("usage", (event) => {
const data = JSON.parse(event.data);
console.log(`Used ${data.monthly_used}/${data.monthly_limit} operations`);
});
eventSource.addEventListener("error", (event) => {
if (event.data) {
const data = JSON.parse(event.data);
console.error("Error:", data.error);
}
eventSource.close();
});
```
## Python example
```python theme={null}
import json
import requests
url = f"https://api.superdocs.app/v1/chat/my-session/stream?job_id={job_id}&api_key={api_key}"
with requests.get(url, stream=True) as response:
for line in response.iter_lines():
if not line:
continue
decoded = line.decode("utf-8")
if decoded.startswith("data: "):
data = json.loads(decoded[6:])
if "content" in data:
print(f"Progress: {data['content']}")
elif "error" in data:
print(f"Error: {data['error']}")
break
```
# Overview
Source: https://superdocs.mintlify.app/introduction/overview
SuperDocs is an AI document editing platform. Edit, create, search, and manage documents through a REST API or MCP.
# SuperDocs
SuperDocs is an AI-powered document editing platform. Send a document and a natural language instruction, and the AI edits the document directly — adding sections, rewriting content, restructuring, or analyzing what's there.
## Three ways to use SuperDocs
Open the editor at use.superdocs.app. Write, paste, or upload a document. Chat with the AI to edit it.
18 endpoints for chat, sessions, attachments, jobs, and templates. Any language, any platform.
Connect from Claude Desktop, Cursor, VS Code, or Claude Code. The AI tools appear natively in your editor.
## What you can do
* **Edit documents** — "Add a confidentiality clause to section 3"
* **Create content** — "Draft a project proposal for a mobile app"
* **Search and analyze** — "Find all sections that mention liability"
* **Work with attachments** — Upload PDFs or documents for AI context
* **Review changes** — Approve or deny AI-proposed edits before they're applied
* **Choose your AI model** — Four model tiers from fast to most capable
## Next steps
Get your API key and make your first request in under 5 minutes.
# Quickstart
Source: https://superdocs.mintlify.app/introduction/quickstart
Get your API key and make your first SuperDocs API call in under 5 minutes.
# Quickstart
Go from zero to your first AI-powered document edit in 5 minutes.
## 1. Create an account
Sign up at [use.superdocs.app](https://use.superdocs.app) with Google or email/password. Free plan includes 500 operations per month.
## 2. Create an API key
1. Click the **gear icon** in the app to open Settings
2. Go to the **API Keys** tab
3. Click **Create API Key** and give it a name
4. **Copy the key immediately** — it's only shown once
Your key looks like: `sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4`
## 3. Make your first request
```bash curl theme={null}
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 paragraph about data privacy at the end",
"session_id": "my-first-session",
"document_html": "Company Policy
Welcome to our company.
"
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.superdocs.app/v1/chat",
headers={"Authorization": "Bearer sk_YOUR_API_KEY"},
json={
"message": "Add a paragraph about data privacy at the end",
"session_id": "my-first-session",
"document_html": "Company Policy
Welcome to our company.
"
}
)
data = response.json()
print(data["response"])
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.superdocs.app/v1/chat", {
method: "POST",
headers: {
"Authorization": "Bearer sk_YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
message: "Add a paragraph about data privacy at the end",
session_id: "my-first-session",
document_html: "Company Policy
Welcome to our company.
"
})
});
const data = await response.json();
console.log(data.response);
```
## 4. Read the response
```json theme={null}
{
"response": "I've added a data privacy paragraph at the end of the document.",
"session_id": "my-first-session",
"document_changes": {
"updated_html": "Company Policy
...",
"version_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"changes_summary": "Document updated by AI"
},
"usage": {
"monthly_used": 1,
"monthly_limit": 500,
"monthly_remaining": 499,
"was_billable": true,
"subscription_tier": "free"
}
}
```
Key fields:
* `response` — The AI's reply explaining what it did
* `document_changes.updated_html` — The full updated document HTML. Render this in your editor.
* `usage` — How many operations you've used this month
## 5. Continue the conversation
Use the same `session_id` to continue editing. Send back the updated HTML:
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/chat \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Make the data privacy section more formal",
"session_id": "my-first-session",
"document_html": "...the HTML from the previous response..."
}'
```
## Next steps
How session persistence works
How to handle document HTML
Upload files for AI context
Connect from Claude Desktop or Cursor
# Available Tools
Source: https://superdocs.mintlify.app/mcp/available-tools
All 16 MCP tools available when connecting to the SuperDocs MCP server.
# Available MCP Tools
When you connect to the SuperDocs MCP server, these 16 tools become available to your AI tool.
## Chat
| Tool | Description | Key parameters |
| ---------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `chat` | Send a message with optional document HTML. Returns AI response and document changes. | `message`, `session_id`, `document_html`, `model_tier`, `approval_mode` |
| `chat_async` | Start an async chat that processes in the background. Returns a job ID for polling. | `message`, `session_id`, `document_html`, `model_tier`, `approval_mode` |
| `approve_change` | Approve or deny AI-proposed document changes (HITL workflow). | `job_id`, `change_id`, `approved`, `feedback`, `changes` |
## Sessions
| Tool | Description | Key parameters |
| --------------------- | ---------------------------------------------------------- | -------------- |
| `list_sessions` | List all sessions with message counts and timestamps. | `limit` |
| `get_session_history` | Get conversation history and document state for a session. | `session_id` |
| `get_session_jobs` | List jobs for a specific session. | `session_id` |
## Attachments
| Tool | Description | Key parameters |
| ----------------------- | ------------------------------------------------------- | ----------------------------- |
| `upload_attachment` | Upload a file (PDF, DOCX, TXT, RTF, MD) for AI context. | `file`, `session_id` |
| `delete_attachment` | Remove an attachment from a session. | `attachment_id`, `session_id` |
| `get_attachment_status` | Check processing status of session attachments. | `session_id` |
## Jobs
| Tool | Description | Key parameters |
| ------------ | ----------------------------------------- | ----------------- |
| `list_jobs` | List all jobs for the authenticated user. | `status`, `limit` |
| `get_job` | Get status and result of a specific job. | `job_id` |
| `cancel_job` | Cancel a pending or in-progress job. | `job_id` |
## Templates
| Tool | Description | Key parameters |
| ---------------------- | ------------------------------------ | -------------- |
| `upload_user_template` | Upload a reusable document template. | `file` |
| `list_user_templates` | List all uploaded templates. | — |
| `delete_user_template` | Delete a user template. | `template_id` |
## Health
| Tool | Description | Key parameters |
| -------- | -------------------------------------- | -------------- |
| `health` | Check if the SuperDocs API is healthy. | — |
For full request/response schemas, see the [API Reference](/api-reference).
# Claude Code
Source: https://superdocs.mintlify.app/mcp/claude-code
Connect SuperDocs to Claude Code (CLI) with a single command.
# Claude Code
Connect SuperDocs to Claude Code with one CLI command.
## Setup
```bash theme={null}
claude mcp add --transport http superdocs https://api.superdocs.app/mcp \
--header "Authorization: Bearer sk_YOUR_API_KEY"
```
That's it. SuperDocs tools are now available in your Claude Code session.
## Test it
```bash theme={null}
claude
# Then type: "Use the SuperDocs health tool to check the API"
```
## Example usage
Once connected, you can ask Claude Code to:
* "Create a technical specification document using SuperDocs"
* "Edit my SuperDocs session and update the introduction"
* "Upload this file as an attachment to my SuperDocs session"
## Remove the server
```bash theme={null}
claude mcp remove superdocs
```
# Claude Desktop
Source: https://superdocs.mintlify.app/mcp/claude-desktop
Step-by-step guide to connect SuperDocs to Claude Desktop via MCP.
# Claude Desktop
Connect SuperDocs to Claude Desktop so you can edit documents through conversation.
## 1. Find your config file
| OS | Path |
| ------- | ----------------------------------------------------------------- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
Create the file if it doesn't exist.
## 2. Add the SuperDocs config
```json claude_desktop_config.json theme={null}
{
"mcpServers": {
"superdocs": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"https://api.superdocs.app/mcp",
"--header",
"Authorization:${SUPERDOCS_AUTH}"
],
"env": {
"SUPERDOCS_AUTH": "Bearer sk_YOUR_API_KEY"
}
}
}
}
```
Replace `sk_YOUR_API_KEY` with your actual API key.
Claude Desktop uses `mcp-remote` to bridge to the SuperDocs Streamable HTTP server. This requires Node.js installed on your machine.
If you already have other MCP servers configured, add the `"superdocs"` entry inside the existing `"mcpServers"` object.
## 3. Restart Claude Desktop
Close and reopen Claude Desktop. The SuperDocs tools will appear in the tools menu.
## 4. Test it
Type in Claude Desktop:
> "Use the SuperDocs health tool to check if the API is running"
You should see a response confirming the API is healthy.
## Example usage
> "Create a new NDA document for a consulting engagement using SuperDocs"
> "Search my SuperDocs session for any mentions of payment terms"
See [Available Tools](/mcp/available-tools) for the full list of what you can do.
# Cursor & VS Code
Source: https://superdocs.mintlify.app/mcp/cursor-vscode
Connect SuperDocs to Cursor, VS Code, or Windsurf via MCP configuration.
# Cursor, VS Code & Windsurf
Connect SuperDocs to your code editor for AI-powered document editing alongside your development workflow.
## Cursor
### 1. Create the config file
Create `.cursor/mcp.json` in your project root (or global config):
```json .cursor/mcp.json theme={null}
{
"mcpServers": {
"superdocs": {
"url": "https://api.superdocs.app/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer sk_YOUR_API_KEY"
}
}
}
}
```
### 2. Restart Cursor
The SuperDocs tools will appear in Cursor's AI capabilities.
## VS Code
### 1. Open MCP settings
Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and search for "MCP: Add Server" or edit your `settings.json`:
```json settings.json theme={null}
{
"mcp.servers": {
"superdocs": {
"url": "https://api.superdocs.app/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer sk_YOUR_API_KEY"
}
}
}
}
```
### 2. Restart VS Code
## Windsurf
Add the same configuration to Windsurf's MCP settings:
```json theme={null}
{
"mcpServers": {
"superdocs": {
"url": "https://api.superdocs.app/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer sk_YOUR_API_KEY"
}
}
}
}
```
## Test your connection
In your editor's AI chat, type:
> "Check the SuperDocs API health"
If configured correctly, the AI will call the `health` tool and report the API status.
# MCP Overview
Source: https://superdocs.mintlify.app/mcp/setup
Connect AI tools like Claude Desktop, Cursor, and VS Code to SuperDocs using the Model Context Protocol (MCP).
# MCP Integration
The Model Context Protocol (MCP) lets AI tools connect to external services. SuperDocs exposes an MCP server with 16 tools for document editing, session management, attachments, and more.
When connected, SuperDocs tools appear natively in your AI tool — no API client code needed.
## Prerequisites
* A SuperDocs account ([sign up free](https://use.superdocs.app))
* An API key (see [API Keys](/account/api-keys) or [MCP Setup](/account/mcp-setup))
## Connection details
| Field | Value |
| --------------- | --------------------------------------- |
| **Endpoint** | `https://api.superdocs.app/mcp` |
| **Transport** | Streamable HTTP |
| **Auth header** | `Authorization: Bearer sk_YOUR_API_KEY` |
## Supported clients
Add to claude\_desktop\_config.json
Add to .cursor/mcp.json or VS Code settings
One CLI command
These are just the most popular clients. **Any application with an MCP client** can connect to SuperDocs — including your own custom AI agents, internal business tools, or startup products. If it speaks MCP, it works with SuperDocs. Just point it at the endpoint and auth details above.
## Quick test
After connecting, ask your AI tool:
> "Use the SuperDocs health tool to check the API status"
If the connection is working, you'll get back `{"status": "healthy"}`.