> ## Documentation Index > Fetch the complete documentation index at: https://docs.typebar.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Typebar, formerly SuperDocs. Same product, same API, same keys: nothing changes for your integration. > Typebar, formerly SuperDocs, is not related to SuperDoc (superdoc.dev). # Start a long-running or HITL-approved AI edit; returns a job_id to poll for results. > 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. ## OpenAPI ````yaml /openapi.json post /v1/chat/async 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: - url: https://api.superdocs.app security: [] paths: /v1/chat/async: post: tags: - v1 - mcp - chat summary: >- Start a long-running or HITL-approved AI edit; returns a job_id to poll for results. description: >- 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. operationId: chat_async 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/AsyncChatRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AsyncChatResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: AsyncChatRequest: 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). async_mode: type: boolean title: Async Mode description: >- Must be true for async processing. Included for backward compatibility. default: true 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) 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. 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: AsyncChatRequest description: Start an async chat request that processes in the background. AsyncChatResponse: properties: job_id: type: string title: Job Id description: Job identifier. Poll GET /v1/jobs/{job_id} for status and results. session_id: type: string title: Session Id description: Session identifier for this conversation. status: type: string title: Status description: Initial job status (always 'pending'). message: type: string title: Message description: Human-readable status message. default: Chat request queued for processing type: object required: - job_id - session_id - status title: AsyncChatResponse description: Response from starting an async chat request. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ImageAttachmentData: properties: id: type: string maxLength: 256 title: Id description: Unique identifier for this image. name: type: string maxLength: 512 title: Name description: Original filename of the image. base64Data: type: string maxLength: 50000000 title: Base64Data description: Base64-encoded image data. mimeType: type: string maxLength: 128 title: Mimetype description: MIME type (e.g., 'image/png', 'image/jpeg'). size: type: integer maximum: 50000000 title: Size description: File size in bytes. type: object required: - id - name - base64Data - mimeType - size title: ImageAttachmentData description: Inline image attachment for vision-based analysis. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.