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

# curl Examples

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

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

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](https://use.superdocs.app).

## Documents

### Upload a document to the editor

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

```bash theme={null}
# 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](/concepts/documents#exporting-documents) for the full options reference.

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

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](https://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](/guides/streaming).

## Verify your API key

The cheapest way to confirm an `sk_` key works:

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

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