Skip to main content
Scribe supports Notion-style discussions — comment threads anchored to text — and a Google-Docs-style suggesting mode: pick Suggesting from the mode switcher at the top-right of the document (or press Cmd+Alt+S) and your edits become tracked changes that reviewers accept or reject.

​
Threads

Every thread is anchored to a range of document text and carries:
  • A kind: comment or suggestion.
  • A message history — anyone with comment access can reply.
  • A status: open, resolved (comments), or accepted / rejected (suggestions).
Start a thread with POST /api/docs/{id}/threads, reply with POST /api/threads/{id}/messages, and resolve or reopen it as the discussion concludes. In the editor, the text highlight itself is the affordance: click a highlighted range to open its thread in the comments panel. To start a comment from the editor, select the text you want to discuss and either click Comment in the selection toolbar or press Alt+C (Option+C on macOS). A composer opens in the margin — type your comment and press Enter to post it, or dismiss it without commenting by pressing Esc or clicking anywhere outside it.

​
Anchors that survive edits

Thread anchors are not character offsets or line numbers — they are attached to the text itself. As collaborators insert and delete text around (or inside) a commented range, the anchor keeps following the text it was attached to, even through simultaneous edits and edits made offline. Text typed right after a commented range never bleeds into it.

​
Anchoring by quote (API callers and agents)

The editor computes a thread’s anchor (anchorJson — serialized Yjs relative positions) from the live document, which an API caller has no way to reproduce. So POST /api/docs/{id}/threads accepts a plain quotedText instead: give the exact text you want to comment on and — when anchorJson is omitted — the server locates that text in the live document and computes the anchor for you.
The quote must match the document text exactly and fall within a single paragraph or line; a quote that spans a block boundary or a hard line break does not match. By default the first occurrence is anchored. If the text is not found, the request returns 422 quote_not_found and no thread is created — re-read the content and copy the substring verbatim. A thread must be anchored, so every create supplies either anchorJson (the editor) or quotedText (API callers). To suggest a replacement over the quote, add kind: "suggestion" and proposedText.

​
Suggesting mode

While suggesting mode is on, insertions render as underlined pending text and deletions stay in the document struck through — nothing actually changes until review. Each contiguous editing burst becomes one suggestion, identified by its sid, and suggestions sync and merge exactly like any other edit — several people can suggest at once. Each burst also auto-creates a suggestion thread (its sid field links the two) that shows up in the comments panel with Accept and Reject buttons. For API callers both are resolved against the live document, so the outcome appears instantly in every open editor and merges cleanly with concurrent typing. The editor itself resolves client-first: it applies the transform as a local edit (making the accept undoable with Ctrl+Z like any other change) and passes clientApplied: true so the server only records the status change. One caveat: undoing an accept restores the suggestion’s marks and text in the document, but the thread itself stays accepted. Exported markdown (GET /api/docs/{id}/content, snapshots, search) always represents the document without pending suggestions applied: insert-marked text is omitted, delete-marked text is kept. Users with comment access but no write access edit in forced suggesting mode — that is exactly what commenting on a document means for them. One honest caveat: the suggesting-only restriction is enforced by the editor, not the server.

​
Legacy replacement suggestions

Agents and API callers can still create the older suggestion form: a thread with proposedText (“replace this range with that text”) and no sid. Accepting one splices the replacement over the anchored range in the live document. If the anchored text has been deleted (the anchor no longer resolves, or resolves to an empty range), the API returns a conflict and the thread stays open rather than applying the edit somewhere wrong. Rejecting a legacy suggestion never touches the document.

​
Sharing model

Access to a document is resolved from three layers:
Every document (and folder) has a scope. Workspace documents are readable and editable by every member of the organization. Private documents belong to their owner and are invisible to everyone else until shared.
A document can be shared with individual organization members in one of three roles:Shares are managed with the Shares endpoints — by user ID or by email. This is how a private document reaches specific teammates without making it workspace-wide.
Roles are enforced live: a viewer who opens a document sees every update as it happens but cannot change a single character. A commenter can edit only in suggesting mode — that is what powers forced suggesting mode — with the suggesting-only restriction enforced by the editor (see the caveat above).