chat
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. If a call times out or drops, do not send it again: the turn keeps running and its reply is kept for 1 hour. Call get_session_jobs (same session_id), pick the 'sync_chat' job whose created_at matches when you sent the call, and poll it with get_job until completed (read its result), awaiting_approval (approve or reject its pending changes; if its metadata.awaiting_kind is 'continue_prompt', call continue_chat instead), or failed/cancelled (read its error).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"message": "<message>",
"session_id": "<session_id>"
},
"name": "chat"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | Your message to the AI assistant. | |
| upload_id | No | Optional upload_id from request_upload_url (after the PUT): the file is loaded into this session (replacing its focused document) before the turn, so one call loads and edits it. Needs upload_filename. | |
| model_tier | No | AI model to use: 'core' (default, fast), 'turbo' (fastest), 'pro' (advanced reasoning), 'max' (most capable). | |
| session_id | Yes | Unique session identifier. Reuse to continue a conversation. | |
| document_id | No | 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. | |
| approval_mode | No | Change review mode: 'approve_all' (default, auto-applies changes) or 'ask_every_time' (pauses for your review). | |
| document_html | No | 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. | |
| export_format | No | Optional: the reply also carries `download` (a short-lived URL and curl_example) for the document in this format, so no request_download_url call is needed. While changes are held, it is the document before this turn. | |
| response_mode | No | 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. 'summary' (agent jobs): no HTML or diffs, only the reply, change counts, ids of held changes and turn_index; its size does not grow with the document. | full |
| thinking_depth | No | Reasoning depth: 'fast', 'balanced' (default), or 'deep'. Controls how much analysis the AI performs. | |
| upload_filename | No | The filename given to request_upload_url for upload_id. | |
| image_attachments | No | Inline images for vision-based analysis (base64-encoded). | |
| cross_session_scope | No | 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. | |
| cross_session_memory | No | 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 | No | 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. | |
| deleted_part_chunk_ids | No | 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. | |
| cross_session_memory_key | No | 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). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | 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. | |
| usage | No | Operation usage data. Present for authenticated users with usage tracking. | |
| download | No | Present whenever export_format was set (not on a failed turn): download_url, curl_example, filename, format, expires_at, expires_in_seconds (or error, saying why no link could be made). While changes are held for review, it is the document as it was before this turn (before_this_turn is true): nothing from this turn is in it yet. | |
| response | Yes | AI assistant's response text. | |
| model_tier | No | Present only when part of this turn ran on a different model tier than requested: tier_requested, tier_used and reason. reason 'context_overflow' = the document is too large for the requested tier's context window, so that part of the turn ran on the tier named in tier_used instead (billing is per operation and unchanged). | |
| session_id | Yes | Session identifier for this conversation. | |
| turn_index | No | This turn's position in the session history. Pass it to revert_session_to_message to put the document back to just before this turn. Absent while the turn waits for review (find it later with get_session_history). | |
| document_changes | No | Document modifications made by the AI. Present only when the document was changed. |