Annotations

Annotations let your readers draw a box around any region of a page and attach a note to it. This is useful for document review, feedback, and markup workflows where you need point-specific comments tied to exact locations rather than whole-page reactions.

How annotations work

When annotations are enabled, a reader clicks Annotate on the page they are reading and drags a box over any region of it. The region is stored as a normalized rectangle—x, y, w and h as proportions of the page (0 to 1 on both axes) rather than pixel coordinates—so the box stays on the same spot when the reader zooms, resizes the window, or opens the document on another screen. A rectangle must have positive width and height and lie inside the page; a request whose coordinates fall outside that is rejected. The reader can then attach an optional note (up to 2000 characters) before saving.

Visibility and access control

Each reader sees only their own annotations—never another reader's, and never any identity. When you open the same document while signed in as its owner, you see every reader's annotations, and your reports group them by page and label each one with the reader's identity: the email address for readers who arrived through an email invite, otherwise an anonymous reader label built from a short opaque key. This is the distinction from comments, which are threads a commenter can choose to make public, and from page marks, which record one verdict per page with no free text.

A reader's own annotation appears immediately after they save it, and it is reloaded on their next visit, where they can open the note and delete it. Only the reader who created an annotation and the document owner can delete it.

Annotations key to the same durable viewer identity as page marks: readers who arrive through an email invite keep their annotations across devices, while readers on a plain share link keep theirs for as long as their browsing session lasts.

Exporting and reporting

The Proofing section of the Readership page lists every annotation grouped by page, and a Download CSV button exports the same data. The CSV columns are viewer, page, note, x, y, w, h and created_at; identities and note text are escaped against spreadsheet formula injection. See CSV export for the other exports.

Rate limits and webhooks

Each reader is limited to 300 annotations per document in any rolling hour. Further saves are refused until earlier annotations fall outside the one-hour window.

A reader's first annotation on a document also fires the proofing.updated webhook event, shared with page marks—once per reader per document, whichever proofing action came first.

Availability and setup

Annotations are Pro only and are enabled per document, with the "Annotations" toggle (annotationsEnabled) in the Proofing settings on the Configure & Share page. Once enabled, an Annotate button appears over the page in the viewer.

Turning the toggle off stops the button being served and deletes nothing. The same is true of a downgrade: annotations are served only while the owner still holds Pro, so on a downgrade readers stop seeing the control and no new annotations are accepted, while existing ones are preserved and return if you go back to Pro.

Learn more about Pro features and plan limits on the plans and limits page.