Revise

Scrub a document before it is shared externally ("clean this document before I send it"): remove comments, resolve ALL pending tracked-change suggestions (accept or reject — everyone's, not just yours), remove hidden text (Word w:vanish), anonymize revision/comment author names to "Author", and clear document properties (title/author/company metadata from the original file). Destructive and not undoable — confirm with the user before running it. Options all default to off; enable only what the user asked to strip. Returns a summary of what was removed.

Create a Revise document without a Revise account, seeded with markdown. Returns: url (give this to your user — they open it to view the document and create a free account to keep it, in one step) and edit_token (keep it; use it as your Authorization Bearer token in future requests to read and edit this document). The document is private and deleted after 7 days if unclaimed.

Apply targeted edits to a document using Markdown or HTML content. Edits land as pending tracked changes ("suggest" mode) that the owner reviews and accepts or rejects in the editor — this is the default and the right choice unless your user explicitly asks for direct edits. Pass mode "apply" only on explicit instruction (e.g. "apply it directly", "don't leave suggestions"); it writes immediately with no review step, recorded in the revision history. One exception needs no instruction: on a short/new document (under 20 words) the default is already "apply", since there is nothing meaningful to review. Get block ids from read_document with with_block_ids: true.

Export a document by id to markdown, txt, html, docx, pdf. Markdown is returned inline. Every other format (txt, html, docx, pdf) is hosted at a temporary download URL (expires in ~24h) returned in the response, not streamed back inline.

Get a document's metadata: title, sharing state, URLs, timestamps, and word count.

Get a document's heading outline with block ids and per-section word counts. Cheap way to orient in a long document before reading specific sections.

See what changed in a document since YOU last looked at it — e.g. edits the human (or another collaborator) made in between. Returns added, removed, and changed blocks (with block ids), all in the accepted/projected state. Great for catching up before continuing work ("how does it look now?"). The first call on a document just establishes a baseline. Each call advances your baseline to the current state.

Create a Revise document from a file at a public http(s) URL (.md, .markdown, .txt, .html, .htm, .docx, .rtf, .odt; PDFs/images not yet supported). The server fetches the URL — file bytes are never passed inline. For a LOCAL file, use upload_document instead (it streams the file to the server). Returns the new document id and URL. Returns url (give it to your user — they view the document and create a free account to keep it, in one step) and edit_token (your Bearer token for future edits). The document is private and deleted after 7 days if unclaimed.

Insert a footnote: a numbered superscript reference placed immediately after the anchor text inside a paragraph, plus the footnote body (shown at the bottom of the page, or as an endnote in pageless documents). On substantial documents this lands as a pending tracked change by default, like edit_document. Footnote bodies appear in read_document as [^n]: definitions with their own block ids — edit or remove them with the normal editing tools (removing a footnote body also removes its reference, and vice versa).

Leave a review comment in a document WITHOUT changing its text — either a new thread anchored to one block, or a reply to an existing thread. Comments appear in the editor's margin attributed to you, where the owner can reply or resolve. Prefer this for passage-specific critique or questions; to propose an actual text change, use edit_document in "suggest" mode instead. To START a thread: target one block (from read_document with_block_ids: true) and exactly one anchor form — anchor_text (short text occurring exactly once in the block), anchor_start_text + anchor_end_text (boundaries of a longer range, without reproducing it), or whole_block: true (structural or empty blocks). To REPLY: pass reply_to_comment_id (a comment id from a <comment-thread> element in read_document format "html", or from an earlier leave_comment result) and no block/anchor fields. Text that already carries an unresolved <comment-thread> is already under discussion: reply to that thread rather than starting a second one over the same words, which is rejected unless you pass acknowledge_existing_thread_ids.

Read a Revise document's content. Format "markdown" (default) is the simple dialect — best for plain prose; set with_block_ids to true to interleave <!-- block:xxxxxx --> anchors usable with edit_document. Format "html" is the full-fidelity dialect: compact HTML-like markup with a block id on every element plus everything markdown cannot express — rich marks, <latex> math, code block languages, merged table cells, page layout, and each comment thread inline as a <comment-thread transcript="..."> wrapper around its anchored text. Prefer html when a document uses rich features or has comments; edit_document accepts the same dialect in replacements. "text" is plain text. (For a styled, self-contained HTML file, use export_document instead.) view controls how pending tracked-change suggestions read: "final" (default, as if accepted) or "original" (as if rejected). Long documents are paginated: when a read exceeds the character budget it is cut at a block boundary and the response carries truncated: true, next_start_block, and a ready-to-run example call — repeat with start_block to continue. For a targeted read of a large document, prefer get_document_outline + search_within_document over paging through everything.

Change a document's title.

Replace the ENTIRE content of a document with new markdown. Destructive: existing content is removed (it remains recoverable via the document's revision history). Prefer edit_document for targeted changes.

Accept or reject the tracked-change suggestions YOU made on a document — only your own, never the user's edits or another agent's suggestions. Use this when the user approves your suggested changes (e.g. they say "lgtm" / "looks good") to apply them on their behalf, or asks you to withdraw them. Covers the whole document by default; pass block_ids to limit to specific blocks. (Edits made with edit_document in "apply" mode are already applied — this is for edits left as suggestions in "suggest" mode.)

Find where a query matches inside one document. Returns the matching blocks as markdown with <!-- block:xxxxxx --> anchors (usable with edit_document), each with a few neighboring blocks for context. Case-insensitive.

Set a document's page layout: page size, orientation, margins, page numbers, line/paragraph spacing, pageless mode, or the APA-7 preset. Length values are strings with explicit units (e.g. "1in", "2.54cm", "72px").

Style existing content with forgiving CSS-lite selectors and values. Use this for bulk formatting instead of rewriting text. Block selectors include *, #blockId, p, h1-h6, li, lists, tables, and descendants. Inline selectors such as b/strong, i/em, u, s/strike/del, code, sup, sub, mark, and a target only matching formatted text ranges. Examples: set the entire document to Georgia with selectors="*" and attrs=[{"name":"fontFamily","value":"Georgia"}]; bold headings with selectors=["h1","h2","h3"] and attrs=[{"name":"fontWeight","value":"bold"}]. Formatting lands as pending tracked changes by default on substantial documents.

Create a Revise document from a LOCAL file (docx, md, txt, html; PDFs/images not yet supported) without a Revise account and without putting its bytes in your context. Returns a one-time upload_url and a ready-to-run curl command — run the curl to stream the file. The curl response contains url (give it to your user — they view the document and create a free account to keep it, in one step) and edit_token (your Bearer token for future edits). For a public http(s) URL or a tiny inline file, use import_document instead. The document is private and deleted after 7 days if unclaimed.