Edit, draft, or restructure a document using natural language. Preserves tables, styling, and formatting.

Synchronous AI chat that can rewrite specific paragraphs, add or remove table rows, restructure sections, generate new content from templates, or transform an entire document. Pass document_html only to load or replace the document; once a session holds a document the server persists it across turns, so omit it on follow-up turns. To replace the whole document with EXACT content you already hold, pass that content in document_html (a verbatim load — the AI never re-types it) or upload it via upload_document_base64; describing the content only in message makes the AI author it, which can drift from your text. Returns AI response text plus structural document changes (HTML edits, additions, deletions) with chunk IDs. One billable operation per document-modifying turn; very large multi-section edits bill one operation per 25 sections changed. For long-running edits or human-in-the-loop approval, use chat_async. Optional: model_tier (core/turbo/pro/max), thinking_depth (fast/balanced/deep), image_attachments for multimodal vision. RECOMMENDED for AI agents working with large documents (>20 pages): set response_mode='compact' to skip the full HTML in the response (the AI returns only per-section diffs in chunk_diffs) and save 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 reply text. Always use natural language to describe what you want; the AI handles all internal section lookups.

post/v1/chat

Request

Base URL: https://api.superdocs.app
URL: https://api.superdocs.app/v1/chat
Auth: HTTP bearer

Headers

authorizationstring nullable

Request body

messagestring required

Your message to the AI assistant.

session_idstring required

Unique session identifier. Reuse to continue a conversation.

document_htmlstring nullable

Current document HTML. OMIT this when the session already holds the document — the server persists it across turns, so you don't re-send it every turn; pass it only to load new content or replace the document wholesale (a verbatim load — the AI never re-types content passed here). Include data-chunk-id attributes on elements to enable targeted AI edits.

user_idstring nullable

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

model_tierstring nullable

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

thinking_depthstring nullable

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

approval_modestring nullable

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

response_mode'full' | 'compact' nullable

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.

cursor_contextobject nullable

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_idstring nullable

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.

window_idstring nullable

Optional identifier for the client window (set by the web app) so concurrent edits from two windows of the same chat are merged rather than overwritten. Agents/API may omit.

cross_session_memoryboolean nullable

When true, the AI carries a private rolling memory of context across THIS account's chats (off by default). Per-request override of your saved Settings default.

cross_session_searchboolean nullable

When true, the AI may search your PAST chats and documents on demand to reuse prior work and open a found document (off by default). Per-request override of your saved Settings default; never affects the always-on search of the open document.

cross_session_memory_keystring nullable

Optional per-request id of YOUR end-customer so the cross-session memory note is kept in a separate file per end-customer. Omit for one account-level note (the default / B2C).

cross_session_scopestring[] nullable

Optional list of session ids to restrict cross-session SEARCH to (e.g. one end-customer's sessions). Omit to search all of this account's sessions. Only narrows within the API-key owner; ignored unless cross_session_search is on.

touched_chunk_idsstring[] nullable

Optional list of chunk ids (data-chunk-id values) the user actually edited since the last sync, sent alongside document_html. When present, a chunk NOT in this list whose text is unchanged keeps its stored formatting byte-for-byte even if the client serialized it differently (protects styling from editor round-trip loss). Chunks in the list — and any chunk whose text changed — always take the submitted content. Omit for the default behavior (any differing chunk is treated as an edit).

deleted_part_chunk_idsstring[] nullable

Optional list of chunk ids (data-chunk-id values) of OUT-OF-FLOW part sections (page headers/footers, footnote/endnote bodies, comments) to delete explicitly, sent alongside document_html. Out-of-flow parts absent from document_html are always KEPT — an editor view not containing them is their normal state, never a deletion — so removing one requires naming its id here. Ids that are not stored out-of-flow parts are ignored (in-flow content keeps the default behavior). Omit when deleting nothing.

Example request

{
  "approval_mode": "approve_all",
  "document_html": "<div data-chunk-id=\"550e8400-e29b-41d4-a716-446655440000\"><h2>Section 3</h2><p>Terms and conditions...</p></div>",
  "message": "Add a confidentiality clause to section 3",
  "model_tier": "core",
  "session_id": "session_abc123"
}

Response

Successful Response

responsestring required

AI assistant's response text.

session_idstring required

Session identifier for this conversation.

hintobject nullable

Advisory guidance for API callers (additive; absent on most responses). Currently: prefer_chat_async_for_large_generations — this turn ran long enough that the same work submitted via POST /v1/chat/async would be safer (no gateway timeout risk) and reports progress.

Example response

{
  "document_changes": {
    "changes_summary": "1 section edited, rest untouched",
    "updated_html": "<div data-chunk-id=\"550e8400-e29b-41d4-a716-446655440000\"><h2>Section 3</h2><p>Updated content...</p></div>",
    "version_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  },
  "response": "I've added a confidentiality clause to section 3 covering non-disclosure obligations.",
  "session_id": "session_abc123",
  "usage": {
    "monthly_limit": 500,
    "monthly_remaining": 458,
    "monthly_used": 42,
    "subscription_tier": "free",
    "was_billable": true
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.