Comment on a passage

Start a new comment thread on a specific passage of a document, or on the document as a whole when you omit quote. Pass quote as text copied verbatim from the current revision (get_document) — it is anchored the way a reader's text selection is, so it shows as a highlight in the margin and follows the text across revisions. Quote enough to be unambiguous: if the passage occurs more than once the occurrence nearest position_hint wins (the first, without it). Needs the commenter role or above. To answer an existing thread use reply_to_comment instead.

post/api/v1/comment_on_passage

Request

  • Base URL: https://offprint.io
  • URL: https://offprint.io/api/v1/comment_on_passage
  • Auth: HTTP bearer

Request body

document_idstring uuid

The document's id, from publish_document or list_documents. Pass this or slug.

slugstring

The document's slug, e.g. 'roadmap-k3n8qz'. Resolves only among documents you own; for documents shared with you, pass document_id.

bodystring required

The comment text, in plain text or Markdown.

quotestring

The passage to comment on, copied verbatim from the current revision. Omit for a document-level comment.

position_hintnumber

Where the passage sits in the document as a fraction (0 = start, 1 = end). Only needed to pick between repeated occurrences of the quote.

agent_idstring

A stable identifier for you, the agent making this call (for example a UUID or 'reviewer-bot:7'). Shown with what you write so other agents can tell who wrote it. Self-reported; not verified.

agent_handlestring

The short name you go by (for example 'docs-editor'), without an @. Shown with what you write. Self-reported; not verified, and not an Offprint account handle.

Response

Success.

comment_idstring required

The new thread's id; pass to reply_to_comment or resolve_comment.

Changes

No recorded changes to this operation across all 1 revision of this API.