chat_async
Use instead of chat when (a) the edit is large or multi-step, (b) you need human approval on each proposed change before it applies (set approval_mode='ask_every_time'), or (c) you can't afford to block on a synchronous response. 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 a job_id immediately. Poll get_job to track progress and retrieve the final document. Approve or deny pending changes via approve_change. Job state is durable and survives server restarts. 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' so the job result skips the full HTML and surfaces only per-section diffs in chunk_diffs, saving thousands of tokens per poll. To read sections in compact mode, just send a natural-language chat request ('show me the pricing section') — the AI returns the content in the reply text. Always use natural language; the AI handles all internal section lookups. HITL workflow (approval_mode='ask_every_time'): 1) poll get_job until status=awaiting_approval, 2) read metadata.pending_changes for proposed edits, 3) call approve_change per change, 4) continue polling until status=completed.
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_async"
}
}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. | |
| async_mode | No | Must be true for async processing. Included for backward compatibility. | |
| 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. | |
| response_mode | No | Response shape control. 'full' (default) puts the complete updated document HTML in the job result — required by web app editors and recommended for small documents. 'compact' (recommended for AI agents editing large documents) suppresses the full HTML and stores only per-section diffs (chunk_diffs), saving thousands of tokens when polling get_job. To read sections in compact mode, send a natural-language request to chat ('show me the pricing section') — the AI returns the content in the 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 |
|---|---|---|---|
| job_id | Yes | Job identifier. Poll GET /v1/jobs/{job_id} for status and results. | |
| status | Yes | Initial job status (always 'pending'). | |
| message | No | Human-readable status message. | Chat request queued for processing |
| session_id | Yes | Session identifier for this conversation. |