curl Examples

Replace sk_YOUR_API_KEY with your actual API key in all commands.

Chat

Send a message with document

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": "<h1>Report</h1><p>Q4 revenue increased 15%.</p>"
  }'

Send a message without document

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

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

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

curl https://api.superdocs.app/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

List all jobs

curl https://api.superdocs.app/v1/jobs \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Cancel a job

curl -X POST https://api.superdocs.app/v1/jobs/JOB_ID/cancel \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Sessions

List sessions

curl https://api.superdocs.app/v1/sessions \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Get session history

curl https://api.superdocs.app/v1/sessions/SESSION_ID/history \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Get session jobs

curl https://api.superdocs.app/v1/sessions/SESSION_ID/jobs \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Delete a session

Session deletion lives under /v1/users/me/sessions/{id} — that endpoint is part of the web-app account surface and accepts Firebase tokens only, not sk_ API keys. To clear sessions programmatically with an API key, simply stop using the session_id (sessions persist server-side but are not billed unless used). To delete from the UI, use Settings > Sessions in use.superdocs.app.

Documents

Upload a document to the editor

curl -X POST https://api.superdocs.app/v1/documents/upload \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -F "file=@contract.docx" \
  -F "session_id=my-session"

Export a document

# From session — DOCX (default format)
curl -X POST https://api.superdocs.app/v1/documents/export \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "my-session", "format": "docx"}' \
  --output document.docx

# From HTML — PDF with paper and watermark options
curl -X POST https://api.superdocs.app/v1/documents/export \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Title</h1><p>Content</p>",
    "format": "pdf",
    "options": {"paper_size": "A4", "watermark_text": "DRAFT"}
  }' \
  --output document.pdf

Formats: docx (default), pdf, html, markdown, txt. See Exporting documents for the full options reference.

Attachments

Upload a file

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

curl https://api.superdocs.app/v1/attachments/status/SESSION_ID \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Delete an attachment

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

curl -X POST https://api.superdocs.app/v1/templates/upload \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -F "file=@template.docx"

List templates

curl https://api.superdocs.app/v1/templates \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Delete a template

curl -X DELETE https://api.superdocs.app/v1/templates/TEMPLATE_ID \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

HITL approval

Approve a single change

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

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

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

The /v1/users/* endpoints (profile, usage, limits, sessions, programmatic API-key management) belong to the web-app account surface and accept web-app session tokens only — sk_ / lce_ API keys are rejected with a 401. View profile, usage, and tier limits from use.superdocs.app → Settings. To check usage from an API-key context, the usage block is included in every /v1/chat and /v1/chat/async response (monthly_used, monthly_limit, monthly_remaining, was_billable, subscription_tier) and in every SSE usage event — see SSE Streaming.

Verify your API key

The cheapest way to confirm an sk_ key works:

curl https://api.superdocs.app/v1/sessions \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

A 200 with a JSON list of sessions (possibly empty) confirms the key. A 401 means the key is wrong, revoked, or the header didn’t reach the server. Do not use /v1/users/me to verify an API key — it’s web-app-only and will return 401 even for a valid sk_ key, which makes the key look bad when it isn’t.

Health check

curl https://api.superdocs.app/health

REST GET /health requires no authentication. The MCP health tool is different: it runs over the authenticated /mcp/ connection like every MCP tool, so a 401 there signals an API-key problem rather than downtime.

​curl Examples

​Chat

​Send a message with document

​Send a message without document

​Chat with model selection

​Async chat

​Start an async request

​Jobs

​Check job status

​List all jobs

​Cancel a job

​Sessions

​List sessions

​Get session history

​Get session jobs

​Delete a session

​Documents

​Upload a document to the editor

​Export a document

​Attachments

​Upload a file

​Check attachment status

​Delete an attachment

​Templates

​Upload a template

​List templates

​Delete a template

​HITL approval

​Approve a single change

​Approve multiple changes

​Deny with feedback

​User management

​Verify your API key

​Health check