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
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": "..."
}'
{
"job_id": "job_abc123",
"session_id": "my-session",
"status": "pending",
"message": "Chat request queued for processing"
}
2. Poll for status
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:
{
"job_id": "job_abc123",
"status": "completed",
"result": {
"response": "I've restructured the document into 5 sections...",
"session_id": "my-session",
"document_changes": {
"updated_html": "<div data-chunk-id=\"...\">...</div>",
"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:
curl -X POST https://api.superdocs.app/v1/jobs/job_abc123/cancel \
-H "Authorization: Bearer sk_YOUR_API_KEY"
List all jobs
curl https://api.superdocs.app/v1/jobs \
-H "Authorization: Bearer sk_YOUR_API_KEY"
Polling example
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.
