Typebar (formerly SuperDocs)

Decide changes held for review (chat or chat_async). Single: change_id + approved=true|false (+ optional feedback for the AI to revise on). Batch: a 'changes' array of per-change decisions. Approved changes apply atomically; denied ones are discarded. When a decision completes the batch (batch_complete=true), the job resumes and this call waits until the resumed turn settles, then returns job_status and applied: applied=true means the approved changes are in the document (an export or the next chat includes them); job_status awaiting_approval means the turn proposed more changes (decide them the same way); failed means they were not applied. With wait_for_result=false it returns at once (applied=false) and you wait with get_job.

Soft-archive a saved document — it leaves the Files view but is recoverable server-side. Presence-aware: if the document is currently open in ANOTHER session and force is not set, the request FAILS honestly with HTTP 409 (code:"document_in_use" + open_in_sessions:N + suggested_action) so callers can confirm "open in N other session(s) — delete anyway?" and re-call with force=true. On force=true it archives, unlinks every session, and notifies the other sessions (which then prompt the user to keep editing or honor the deletion).

A no-op never wears a success status: if nothing was archived you get the 409 above, so a 2xx always means the archive actually happened.

Stops a running turn, or ends a turn that is waiting for your review by discarding its staged changes. Already-applied changes are preserved in the document; anything still pending is discarded. Use to abort work that is no longer wanted (e.g. the user changed their mind, or you want to retry with different parameters or model_tier). The response tells you whether the work was stopped here and now (stop_state: "stopped_here") or the stop was ACCEPTED and is being carried out by the instance running the turn (stop_state: "accepted") — in the accepted case poll get_job until metadata.stopped_unwound is true or the job reaches a terminal status. A turn that already finished cannot be stopped and returns 409 naming its status.

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

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.

Delete the caller's cross-session memory note. Owner-scoped: a caller can only clear its OWN note. With no key this clears the account-level note; with a memory_key it clears that one end-customer's note. Idempotent (removed=0 if it didn't exist).

Remove document_id from the session's open documents (the tab close button). If it's the focused document, focus another open document — next_focus if it's still open (so the client can pick the adjacent tab), else the next remaining one; closing the last document leaves the session empty. Returns the updated document roster + the now-focused document's HTML.

The close takes effect immediately and is persisted, so a later reconnect or session restore won't bring the closed document back. Persistence is best-effort — a failure is logged, not fatal (the close still holds for the active session).

Used with chat_async when a large edit paused to ask whether to keep going. Poll get_job until status=awaiting_approval AND metadata.awaiting_kind='continue_prompt'; then POST here with continue=true to resume (the AI picks up where it left off with a fresh time/step budget) or continue=false to stop (everything applied so far is kept). The job then resumes/finishes and reaches status=completed. This is NOT the change- approval endpoint (that is approve_change) — it can only act on a continue-prompt pause.

Removes the attachment from the session; the AI will no longer reference it in subsequent chat turns. If processing is still in progress, also cancels the underlying job. Use to free up context, remove sensitive files mid-session, or replace a stale reference document. The attachment_id can be either the final attachment ID or the job ID (during processing).

Soft-deletes the template; only the owner (user or organization) can delete. Once deleted, the template no longer appears in list_user_templates and cannot be referenced by the AI for new documents. Existing documents already drafted from the template are unaffected.

Round-trips the document through the original docx renderer, preserving tables, borders, shading, alternating row colors, headers, footers, fonts, inline styling, and embedded images. Two modes: pass html directly to export ad-hoc content, OR pass session_id to export the session's current state. Format options: 'docx' (default, native Open XML, best for programmatic processing or mail merge), 'pdf', 'html', 'markdown', or 'txt' ('doc' is a legacy Word-compatible HTML alias). Fidelity is the differentiator vs naive HTML to docx converters. When called as an MCP tool, binary formats (docx/pdf/doc) are returned as a short-lived signed download_url in a JSON envelope (fetch it to get the file); text formats (html/markdown/txt) are returned inline.

Make document_id the focused document (the editor's active document and the default edit target). Accepts either the session slot id OR the permanent document id (the UUID shown by list_documents/Files, returned as durable_document_id by list_session_documents). Persists the outgoing focused document into the session's document map and returns the now-focused document's HTML.

Check your Typebar account status: tier, monthly operations used/remaining, and (for agent accounts) whether a human has adopted it.

Call this with your sk_ key. Useful before doing work (to confirm you have operations left) and before signing up again (to reuse your account).

Nearing your monthly cap and need to keep going? Hand the account to a human: POST /v1/agents/handoff with their email returns a one-time takeover code to give them; they open the emailed link, enter the code, and adopt the account in place (your work and this API key keep working) so they can upgrade and pay. No human? POST /v1/agents/request-upgrade instead. Full flow: https://docs.superdocs.app/introduction/agent-signup

Returns each attachment's processing state (pending/processing/completed/failed) plus extracted text length and chunk count once ready. Poll this after upload_attachment_base64 to know when an attachment becomes queryable by the AI. Surfaces processing errors with actionable messages.

One saved document's metadata plus a STRUCTURE outline and the chat sessions that have it open (prior-chats-per-file). Owner-scoped — 404 if the document isn't yours.

structure (always included, token-light, NON-BILLABLE) is the cheap verify step after any edit: headings (level + text + position), section_count (heading-anchored), block_count (editable chunks), media (image/diagram counts). It answers "did my edit land?" for free — never export a whole document just to check its structure. Pass include_html=true only when you need the body.

structure.parts (present when the document has headers, footers, notes or comments) lists each part with part_type, chunk_id and preview: whole is true when preview is the part's entire text, and full_len is that text's full length in characters (when whole is false the preview is abridged; pass include_html=true to read it all).

Returns the job's current state (pending, in_progress, awaiting_approval, completed, failed, or cancelled), intermediate AI responses streamed during execution, the final document HTML once complete, and any pending changes awaiting user approval (with chunk IDs and proposed HTML diffs in metadata.pending_changes). Poll this after chat_async to track progress and retrieve results. When status is awaiting_approval, call POST /v1/chat/{session_id}/approve to approve or deny each pending change. Headless/MCP clients get the same typed progress events the web SSE stream delivers via metadata.intermediate_responses (e.g. documents_changed, continue_prompt, model_fallback, proposed_change_batch); cross-session document updates from OTHER sessions are reported separately by polling GET /v1/sessions/{session_id}/doc-events.

Returns complete message history (user and AI), final document HTML with chunk IDs preserved, attachment list, and editor actions (font, color, alignment changes). Use to continue editing a document you started in a prior session. The AI rehydrates with full context of all prior decisions, chunk IDs, and attachments. Pass include_document_html=false to skip the full document body when you only need the conversation.

Returns the full job history of one document. Useful for auditing what the AI did to a document over time, or finding a specific job that's waiting for HITL approval. Same shape as list_jobs but scoped to one session.

Returns 200 with {"status":"healthy"} when the API is up. Call this once after MCP install to confirm the connection works before invoking other tools. No authentication required.

Create a session AND open N saved documents into it in ONE call (the documents are SHARED, never copied — the same cross-session behavior as /documents/open). The web UI passes its own session_id so its session model stays consistent; an MCP/API integrator can omit it and the server mints one — the one-call way to start a session with documents already open. With no document_ids it just returns a fresh, empty session. The open semantics (first document focused, durable binding, returned roster) are identical to /documents/open.

List the authenticated user/org's saved documents, most-recently-updated first (metadata only — no document content). Each carries a session_count ("N chats"). Documents become durable + reusable automatically as you create or edit them; on the FIRST call we also one-time import the documents of pre-Files-view chats so prior work appears here too. Pass archived=true to browse the soft-deleted set (the Files "Archived" filter).

Returns jobs sorted by most recent, optionally filtered by status. Use to monitor long-running AI edits started via chat_async, see which jobs are paused waiting for human approval, or audit completed work. Each job tracks the chat that started it, the changes made, and any HITL decisions logged.

Returns the editable documents open in this session (focused first), each with its id, chunk count, and focused flag — so a client can render document tabs. The response is token-light by default; pass include_html=true to also get each document's reassembled HTML.

ID MAPPING: document_id is the SESSION-LOCAL slot id ("doc_primary", "doc_ab12…"); durable_document_id is the PERMANENT document id (a UUID) — the SAME id list_documents (Files) shows and get_document_detail / rename_document / archive_document / open_documents take (null until the document's first save). focus_session_document, close_session_document, and chat's document_id accept EITHER form, so you can drive a session entirely with durable ids.

Returns sessions sorted by most recent activity, with message counts and last-updated timestamps. Each session represents one document with full edit history and AI conversation persisted server-side. Use to find a previous editing context to resume (then call get_session_history) or to audit your workspace.

Returns active (non-deleted) templates with name, format, size, and creation date metadata. Use to show the AI what reusable document structures are available for drafting new documents. Templates are scoped to the authenticated entity: users via the web app or sk_ key see only their own templates; organizations via lce_ key see theirs.

Load one or more SAVED documents into a session as editable tabs. The SAME durable document is attached (never copied), so edits flow back to the one shared row with cross-session soft-collaboration. The first listed document is focused. Returns the refreshed document roster so the client can render tabs immediately.

Fetches the file uploaded via request_upload_url and runs the same parsing pipeline as upload_document_base64: every paragraph, heading, table, row, and cell gets a unique chunk ID, enabling targeted structural edits via chat ("remove row 3 of the pricing table" works), with tables, borders, shading, alternating row colors, fonts, and inline styling preserved on edit and export. By default the response is compact (metadata only, no document body) to keep your context small — the document is loaded into the session and you edit it via chat; pass return_html=true if you need the parsed HTML inline. Uploading and parsing is NOT itself a billable operation — you are charged only when the AI edits the document. Specify parse_mode='document' to load as the active editable document, or parse_mode='attachment' to load as a read-only AI-searchable reference. A long document can take minutes to load; the call reports progress while it runs. If the call times out or its connection drops, do not upload again: call process_uploaded_document again with the same upload_id and session_id (it joins the load already running and returns its result), or call get_session_jobs and poll the 'document_ingest' job with get_job until it is completed (its result is this call's response) or failed.

Revert is non-destructive: this restores the session FORWARD to the pre-revert state (returned by the revert as redo_checkpoint_id), restores the document to that state while still merging any concurrent edits from other sessions (keeping both where they conflict), and un-archives exactly the chat turns the revert hid. Intended for use immediately after a revert; once a new message is sent the timeline diverges and the web app stops offering it.

Rename one of your saved documents and/or update its out-of-flow parts. Parts are the document's out-of-flow content — headers/footers, footnote and endnote bodies, comments, and per-section page geometry. Every fragment is sanitized on write, writes are versioned and safe under concurrent editors, and parts revert with the document. A title-only call behaves exactly as the original rename (response status:"renamed"). Part content lives in the document body and is edited exactly like any other document content (via chat or the document write endpoints); a legacy parts payload returns 400 parts_moved_to_chunks pointing you there.

Returns a short-lived (15-minute) GET URL plus a ready-to-run curl_example. An agent with shell access can run the curl_example directly to save the exported file to the working directory, so the bytes never pass through its context window; clients without shell execution (or callers who only want the link) can use the signed URL directly. Generates the document in the requested format and returns a time-limited signed download URL. Specify format as 'pdf', 'docx', 'html', 'markdown', or 'txt' (legacy 'doc' also accepted).

Request a higher scale limit for your account in ONE call.

WHEN TO USE: after any 413 with error_code DOCUMENT_TOO_COMPLEX (a single document crossed the standard per-document page limit) or SESSION_TOO_FULL (the documents open in one chat crossed the standard per-chat limit). These are stability limits, not hard caps: the platform supports larger deployments, and limits are raised per account on request.

WHAT HAPPENS: the Typebar team is notified immediately with your account identity and the numbers you send; limits are typically expanded within a day and you are contacted at your account email. No email writing needed — though hello@superdocs.app also works if you prefer.

ALTERNATIVES while you wait: split the file into smaller documents, upload it as an attachment (reference/search, not editing), start another session for additional documents (init_session), or close documents you no longer need (close_session_document).

Returns a short-lived (5-minute) PUT URL plus a ready-to-run curl_example. An agent with shell access can run the curl_example directly to push the file to cloud storage, so the bytes never pass through its context window (a client without a shell can hand the command to its user). After the upload, pass upload_id and filename to chat to load the file and edit it in the same call (or call process_uploaded_document to load it alone). For files <100KB where token cost is trivial, upload_document_base64 still works inline. Max file size: 100 MB. Supported formats: .pdf, .docx, .txt, .rtf, .md, .html, .htm, .tex (plus .zip LaTeX project archives).

Rewinds a chat session, document and conversation, to just before a specific user message. The reverted message's text comes back as compose_text, to edit and resend. Messages from the reverted turn forward are soft-archived: hidden but kept (redo_revert restores them). Pass the turn_index a chat reply returned. Rejects with 409 while a chat job is in progress or awaiting approval. Returns 422 (code 'turn_has_no_restore_point') when the turn recorded no restore point (usually the message before it did not finish); the response lists revertable_turns (possibly empty) that can be rewound to.

Restore (un-archive) a saved document by its id — the mirror of archive_document. The document re-enters your Files view and can be opened/edited again (open it into a chat with open_documents). document_id is the same id used by list_documents / archive_document. Idempotent: restoring an already-active (or unknown) document is a no-op. Non-billable.

Files are processed asynchronously and become AI-searchable once ready. The AI can then reference the attachment's content during chat (e.g., "rewrite section 3 to match the style guide PDF I attached"). Images are queryable via multimodal vision. Poll get_attachment_status to know when ready. Distinct from upload_document_base64: attachments are read-only context for the AI to reference, not the editable working document. Supported formats: .pdf, .docx, .txt, .rtf, .md, .html, .htm, .tex (plus .zip LaTeX project archives). Max 50 MB validated; note the hosted transport layer caps any REQUEST BODY at ~32 MB and rejects larger ones at the gateway with an HTML (not JSON) error — base64 inflates content ~33%, so inline uploads are reliable up to ~20 MB of file bytes; beyond that use request_upload_url (pre-signed flow, up to 100 MB). Requires session_id.

Parses the file into structured HTML where every paragraph, heading, table, row, and cell has a unique chunk ID, enabling the AI to make targeted structural edits via chat ("remove row 3 of the pricing table" works). Tables, borders, shading, alternating row colors, fonts, and inline styling are preserved on edit and export. Also works for AI-generated content: if you've drafted an outline or partial document in your context, upload it here as the working doc, then use chat to fill in the rest. This is also the reliable way to REPLACE a session's document with exact content you already hold — the upload is a verbatim load, so it can never come back paraphrased or placeholder-shaped the way asking chat to re-type it can. When you pass a session_id the response is compact by default (metadata only — pass return_html=true for the full parsed HTML); the document is loaded into the session and you edit it via chat. For files >100KB, prefer request_upload_url (pre-signed URL flow) to avoid token bloat from base64 through the agent context. Supported formats: .pdf, .docx, .txt, .rtf, .md, .html, .htm, .tex (plus .zip LaTeX project archives). Max 50 MB validated; note the hosted transport layer caps any REQUEST BODY at ~32 MB and rejects larger ones at the gateway with an HTML (not JSON) error — base64 inflates content ~33%, so inline uploads are reliable up to ~20 MB of file bytes; beyond that use request_upload_url (pre-signed flow, up to 100 MB).

Upload an image (base64-encoded) and get a stable URL to reference in a document via .

Accepts PNG/JPEG/WebP/GIF/SVG, up to 10 MB decoded. Send raw base64 or a data: URL in image_base64. This is the agent-friendly counterpart to the browser multipart upload — use it to save a generated or fetched image so a document can embed it.

Embed the returned url (the stable canonical reference — it never expires and every document read serves it as a fresh time-limited signed link). view_url is such a signed link for immediately viewing/downloading the image outside a document; it expires, so never embed it.

Templates persist across sessions and can be referenced by the AI when drafting new documents (e.g., "draft an NDA using my standard template"). Stored at user or organization scope. Ideal for boilerplate, branded letterheads, recurring document structures, or compliance-required templates. Supports the same formats as document upload: .docx, .pdf, .txt, .rtf, .md, .html, .htm, .tex. Max 50 MB validated; note the hosted transport layer caps any REQUEST BODY at ~32 MB and rejects larger ones at the gateway with an HTML (not JSON) error — base64 inflates content ~33%, so inline uploads are reliable up to ~20 MB of file bytes; beyond that use request_upload_url (pre-signed flow, up to 100 MB).