Universal Chat

Send a message to SuperDocs AI and receive an AI response with optional document edits.

The AI agent can edit, search, create, and delete document sections based on your message. Provide document_html to give the AI context about the current document state. Returns the AI response text and any document changes (HTML updates, creates, deletes). Each message that triggers a document action counts as one billable operation.

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.

When approval_mode is ‘ask_every_time’, the response includes pending changes requiring review via the async workflow (use chat_async instead for full HITL support).

POST

chat

Universal Chat

curl --request POST \
  --url https://api.superdocs.app/v1/chat \
  --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
    }
  ],
  "model_tier": "<string>",
  "thinking_depth": "<string>",
  "approval_mode": "<string>"
}
'

{
  "response": "<string>",
  "session_id": "<string>",
  "document_changes": {
    "updated_html": "<string>",
    "version_id": "<string>",
    "changes_summary": "<string>",
    "requires_approval": true,
    "pending_changes": [
      {
        "change_id": "<string>",
        "operation": "<string>",
        "chunk_id": "<string>",
        "old_html": "<string>",
        "new_html": "<string>",
        "ai_explanation": "<string>"
      }
    ],
    "changes": [
      {}
    ]
  },
  "usage": {
    "monthly_used": 123,
    "monthly_limit": 123,
    "monthly_remaining": 123,
    "was_billable": true,
    "subscription_tier": "<string>"
  }
}

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

Send a message to the AI assistant with optional document context.

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

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

AI response with optional document changes and usage data.

response

string

required

AI assistant's response text.

session_id

string

required

Session identifier for this conversation.

document_changes

DocumentChanges · object

Document modifications made by the AI. Present only when the document was changed.

Show child attributes

usage

UsageInfo · object

Operation usage data. Present for authenticated users with usage tracking.

Show child attributes

List SessionsList all document editing sessions for the authenticated user. Returns session IDs, message counts, timestamps, and preview text. Use a session_id from this list when calling the chat or history endpoints.

⌘I

Universal Chat

curl --request POST \
  --url https://api.superdocs.app/v1/chat \
  --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
    }
  ],
  "model_tier": "<string>",
  "thinking_depth": "<string>",
  "approval_mode": "<string>"
}
'

{
  "response": "<string>",
  "session_id": "<string>",
  "document_changes": {
    "updated_html": "<string>",
    "version_id": "<string>",
    "changes_summary": "<string>",
    "requires_approval": true,
    "pending_changes": [
      {
        "change_id": "<string>",
        "operation": "<string>",
        "chunk_id": "<string>",
        "old_html": "<string>",
        "new_html": "<string>",
        "ai_explanation": "<string>"
      }
    ],
    "changes": [
      {}
    ]
  },
  "usage": {
    "monthly_used": 123,
    "monthly_limit": 123,
    "monthly_remaining": 123,
    "was_billable": true,
    "subscription_tier": "<string>"
  }
}

v1

users

mcp

Authorizations

Headers

Body

Response