Skip to main content
POST
Start a long-running or HITL-approved AI edit; returns a job_id to poll for results.

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

Start an async chat request that processes in the background.

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. 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.

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
async_mode
boolean
default:true

Must be true for async processing. Included for backward compatibility.

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) 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.

Available options:
full,
compact
cursor_context
Cursor Context · object | null

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

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
string | null

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
boolean | null

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
boolean | null

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
string | null

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).

Maximum string length: 256
cross_session_scope
string[] | null

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.

Maximum array length: 2000
touched_chunk_ids
string[] | null

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).

Maximum array length: 50000
deleted_part_chunk_ids
string[] | null

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.

Maximum array length: 50000

Response

Successful Response

Response from starting an async chat request.

job_id
string
required

Job identifier. Poll GET /v1/jobs/{job_id} for status and results.

session_id
string
required

Session identifier for this conversation.

status
string
required

Initial job status (always 'pending').

message
string
default:Chat request queued for processing

Human-readable status message.