Highlights

Retrieve a highlight

Read one highlight. It answers 404 whenever its article would, so a highlight cannot be used to read a passage of an article the credential is not entitled to.

get/highlights/{highlight}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/highlights/{highlight}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: content:read)

Query parameters

expandstring

Comma-separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only id and object. Each operation documents the paths it accepts, and an unknown path answers 400. Nested paths use a dot, for example article.newsletter.

fieldsstring

Comma-separated allow-list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.

Response

The highlight.

object'highlight' required

Always highlight.

idstring uuid required

Stable identifier.

quotestring required

The marked text itself, as plain text.

prefixstring

Up to two hundred characters of the text immediately before the quote. Together with suffix this re anchors the highlight when the body changed and the offsets no longer line up.

suffixstring

Up to two hundred characters of the text immediately after the quote.

start_offsetinteger required

Where the passage starts, as a character offset into the article's plain text. Always less than end_offset.

end_offsetinteger required

Where the passage ends, as a character offset into the plain text.

owner_keystring required

An opaque, stable per highlighter value, scoped to this one article. Group by it to tell one reader's marks apart from another's, and count distinct values for a distinct highlighter count. It cannot be resolved to a person and does not correlate across articles: Commune does not attribute a highlight to a named reader.

created_atstring date-time required

When the passage was marked.

Example response

{
  "article": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "owner_key": "4f2a9c1e7b3d6a05",
  "message": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  }
}

Changes

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