Skip to main content
POST
/
v1
/
chat
Edit, draft, or restructure a document using natural language. Preserves tables, styling, and formatting.
curl --request POST \
  --url https://api.example.com/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_mode": "full",
  "cursor_context": {},
  "document_id": "<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": [
      {}
    ],
    "chunk_diffs": [
      {
        "change_id": "<string>",
        "operation": "<string>",
        "chunk_id": "<string>",
        "old_html": "<string>",
        "new_html": "<string>",
        "ai_explanation": "<string>"
      }
    ]
  },
  "usage": {
    "monthly_used": 123,
    "monthly_limit": 123,
    "monthly_remaining": 123,
    "was_billable": true,
    "subscription_tier": "<string>",
    "bucket_used": "<string>",
    "redemption_id": "<string>",
    "promotions": [
      {
        "redemption_id": "<string>",
        "name": "<string>",
        "ops_remaining": 123,
        "ops_granted": 123,
        "expires_at": "<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.

Maximum string length: 100000
​
session_id
string
required

Unique session identifier. Reuse to continue a conversation.

Maximum string length: 256
Pattern: ^[a-zA-Z0-9_\-\.]+$
​
document_html
string | null

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

Maximum string length: 50000000
​
user_id
string | null

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

Maximum string length: 256
​
image_attachments
ImageAttachmentData · object[] | null

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

Maximum array length: 20
​
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_mode
enum<string> | null
default:full

Response shape control. 'full' (default) returns the complete updated document HTML — required by web app editors and recommended for small documents (<20 pages). 'compact' (recommended for AI agents editing large documents) suppresses the full HTML and returns only per-section diffs (chunk_diffs) for changed sections, saving thousands of tokens per turn. To read sections in compact mode, just send a natural-language request like 'show me the force majeure section' — the AI returns the content in the chat reply text.

Available options:
full,
compact
​
cursor_context
Cursor Context · object

Editor cursor context at message time, used to default the insert location for new images, diagrams, or sections when the user's prompt doesn't name a position. Shape: {chunk_id: str, pos_in_chunk?: int, text_before?: str, text_after?: str}. Omit when the user typed in chat without focusing the editor first.

​
document_id
string | null

Multi-document: target a specific open document by id (ids come from /v1/sessions/{session_id}/documents). Omit to target the focused document (default — unchanged single-document behaviour). When set, that document becomes the focus for this turn.

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.

​
usage
UsageInfo · object

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