Async Chat

Start an asynchronous chat request and return a job ID for polling.

Use this for long-running document operations. The request is processed in the background. Poll the job status using GET /v1/jobs/ until status is ‘completed’ or ‘failed’. The result contains the AI response and any document changes, same as the sync chat endpoint.

Optional parameters:

model_tier: AI model to use (‘core’, ‘turbo’, ‘pro’, ‘max’). Default: ‘core’.
thinking_depth: Reasoning depth (‘fast’, ‘balanced’, ‘deep’). Default: auto-selected.
approval_mode: Change review mode (‘approve_all’ or ‘ask_every_time’). Default: ‘approve_all’.
image_attachments: Inline images for vision-based analysis.

HITL workflow (approval_mode=‘ask_every_time’):

Poll GET /v1/jobs/ — status transitions to ‘awaiting_approval’
Read metadata.pending_changes for proposed edits (change_id, operation, old_html, new_html)
POST /v1/chat//approve with approved=true/false per change
Continue polling — job resumes and eventually reaches ‘completed’

POST

chat

async

Async Chat

curl --request POST \
  --url https://api.superdocs.app/v1/chat/async \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "session_id": "<string>",
  "document_html": "<string>",
  "user_id": "<string>",
  "image_attachments": [
    {
      "id": "<string>",
      "name": "<string>",
      "base64Data": "<string>",
      "mimeType": "<string>",
      "size": 123
    }
  ],
  "async_mode": true,
  "model_tier": "<string>",
  "thinking_depth": "<string>",
  "approval_mode": "<string>"
}
'

{
  "job_id": "<string>",
  "session_id": "<string>",
  "status": "<string>",
  "message": "Chat request queued for processing"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

authorization

string | null

Body

application/json

Start an async chat request that processes in the background.

message

string

required

Your message to the AI assistant.

session_id

string

required

Unique session identifier. Reuse to continue a conversation.

document_html

string | null

Current document HTML. Include data-chunk-id attributes on elements to enable targeted AI edits.

user_id

string | null

User identifier. Automatically set from authentication — typically omit this.

image_attachments

ImageAttachmentData · object[] | null

Inline images for vision-based analysis (base64-encoded).

Show child attributes

async_mode

boolean

default:true

Must be true for async processing. Included for backward compatibility.

model_tier

string | null

AI model to use: 'core' (default, fast), 'turbo' (fastest), 'pro' (advanced reasoning), 'max' (most capable).

thinking_depth

string | null

Reasoning depth: 'fast', 'balanced' (default), or 'deep'. Controls how much analysis the AI performs.

approval_mode

string | null

Change review mode: 'approve_all' (default, auto-applies changes) or 'ask_every_time' (pauses for your review).

Response

Successful Response

Response from starting an async chat request.

job_id

string

required

Job identifier. Poll GET /v1/jobs/{job_id} for status and results.

session_id

string

required

Session identifier for this conversation.

status

string

required

Initial job status (always 'pending').

message

string

default:Chat request queued for processing

Human-readable status message.

Stream Chat ProgressStream real-time progress for a chat job using Server-Sent Events (SSE). Opens an SSE connection that streams events as the AI processes your request. Use this with the job_id returned from POST /v1/chat/async. Event types: - 'intermediate': Progress updates during processing (content, sequence, timestamp). - 'proposed_change': A document change proposed for review (when approval_mode is 'ask_every_time'). - 'final': Processing complete. Contains the full result with AI response and document changes. - 'usage': Billing data emitted after 'final' (monthly_used, monthly_limit, monthly_remaining). - 'error': An error occurred (job failed, cancelled, or not found). Authentication: Pass a token or api_key as a query parameter (required for EventSource which cannot set headers).

⌘I

Async Chat

curl --request POST \
  --url https://api.superdocs.app/v1/chat/async \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "session_id": "<string>",
  "document_html": "<string>",
  "user_id": "<string>",
  "image_attachments": [
    {
      "id": "<string>",
      "name": "<string>",
      "base64Data": "<string>",
      "mimeType": "<string>",
      "size": 123
    }
  ],
  "async_mode": true,
  "model_tier": "<string>",
  "thinking_depth": "<string>",
  "approval_mode": "<string>"
}
'

{
  "job_id": "<string>",
  "session_id": "<string>",
  "status": "<string>",
  "message": "Chat request queued for processing"
}

v1

users

mcp

Async Chat

Authorizations

Headers

Body

Response