> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdocs.app/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
## OpenAPI
````yaml /openapi.json post /v1/chat
openapi: 3.1.0
info:
title: Universal Document AI API
description: AI-powered document editing with multi-tenant organization support
version: 2.0.0
servers: []
security: []
paths:
/v1/chat:
post:
tags:
- v1
- mcp
- chat
summary: >-
Edit, draft, or restructure a document using natural language. Preserves
tables, styling, and formatting.
description: >-
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.
operationId: chat
parameters:
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UniversalChatRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
UniversalChatRequest:
properties:
message:
type: string
maxLength: 100000
title: Message
description: Your message to the AI assistant.
session_id:
type: string
maxLength: 256
pattern: ^[a-zA-Z0-9_\-\.]+$
title: Session Id
description: Unique session identifier. Reuse to continue a conversation.
document_html:
anyOf:
- type: string
maxLength: 50000000
- type: 'null'
title: Document Html
description: >-
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_id:
anyOf:
- type: string
maxLength: 256
- type: 'null'
title: User Id
description: >-
User identifier. Automatically set from authentication — typically
omit this.
image_attachments:
anyOf:
- items:
$ref: '#/components/schemas/ImageAttachmentData'
type: array
maxItems: 20
- type: 'null'
title: Image Attachments
description: Inline images for vision-based analysis (base64-encoded).
model_tier:
anyOf:
- type: string
- type: 'null'
title: Model Tier
description: >-
AI model to use: 'core' (default, fast), 'turbo' (fastest), 'pro'
(advanced reasoning), 'max' (most capable).
thinking_depth:
anyOf:
- type: string
- type: 'null'
title: Thinking Depth
description: >-
Reasoning depth: 'fast', 'balanced' (default), or 'deep'. Controls
how much analysis the AI performs.
approval_mode:
anyOf:
- type: string
- type: 'null'
title: Approval Mode
description: >-
Change review mode: 'approve_all' (default, auto-applies changes) or
'ask_every_time' (pauses for your review).
response_mode:
anyOf:
- type: string
enum:
- full
- compact
- type: 'null'
title: Response Mode
description: >-
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.
default: full
cursor_context:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Cursor Context
description: >-
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:
anyOf:
- type: string
- type: 'null'
title: Document Id
description: >-
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_id:
anyOf:
- type: string
- type: 'null'
title: Window Id
description: >-
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_memory:
anyOf:
- type: boolean
- type: 'null'
title: Cross Session Memory
description: >-
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_search:
anyOf:
- type: boolean
- type: 'null'
title: Cross Session Search
description: >-
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_key:
anyOf:
- type: string
maxLength: 256
- type: 'null'
title: Cross Session Memory Key
description: >-
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_scope:
anyOf:
- items:
type: string
type: array
maxItems: 2000
- type: 'null'
title: Cross Session Scope
description: >-
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_ids:
anyOf:
- items:
type: string
type: array
maxItems: 50000
- type: 'null'
title: Touched Chunk Ids
description: >-
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_ids:
anyOf:
- items:
type: string
type: array
maxItems: 50000
- type: 'null'
title: Deleted Part Chunk Ids
description: >-
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.
type: object
required:
- message
- session_id
title: UniversalChatRequest
description: Send a message to the AI assistant with optional document context.
examples:
- approval_mode: approve_all
document_html: >-
Section
3
Terms and conditions...
Section
3
Updated content...