Skip to main content
Scribe supports Notion-style discussions: comment threads for conversation and suggestion threads that carry a proposed replacement, which anyone with write access can accept or reject.
Comments, suggestions, and per-user sharing are fully supported by the REST API today and everything below works over HTTP — the in-app surfaces for them (the comment overlay and the full share menu) are still landing in the editor UI.

​
Threads

Every thread is anchored to a range of document text and carries:
  • A kind: comment or suggestion.
  • The quoted text the range covered when the thread was created.
  • 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.

​
Anchors that survive edits

Thread anchors are not character offsets — they are Yjs relative positions, identifiers that name a spot in the CRDT’s edit history. As collaborators insert and delete text around (or inside) a commented range, the anchor keeps resolving to the text it was attached to, concurrently and offline-tolerantly, with no server-side reconciliation step.

​
Suggestions

A suggestion is a thread with proposedText: “replace this range with that text.” Accepting one (POST /api/threads/{id}/accept) is not a text-file patch — the document’s Durable Object resolves the anchor against the live document and splices the replacement into the collaborative session, so the edit appears instantly in every open editor and merges cleanly with concurrent typing. If the anchored text has been deleted by the time someone accepts, the anchor no longer resolves: the API returns a conflict and the thread stays open rather than applying the edit somewhere wrong. Rejecting a suggestion marks the thread rejected without touching 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.
Role enforcement reaches all the way into the realtime layer: a viewer or commenter who opens a document gets a read-only WebSocket that receives every update live but cannot write a single character.