Body Required

• id string(uuid) Required

  Unique id for this event. Stable across redeliveries, so it is the dedupe key. It is the primary key of the row the publisher wrote, which means it is assigned when the state change is recorded, not when the message is dispatched.

• type string Required

  The topic name, identical to the channel address. Route on this.

  Value is highlight.created.

• api_version string Required

  The Commune-Version value this payload conforms to. Present on the message itself, not only on the request header, so an event persisted to a consumer's own store stays self-describing.

• occurred_at string(date-time) Required

  RFC 3339 timestamp of the state change, not of the delivery attempt. Use it to order events, since delivery order is not guaranteed.

• newsletter_id string(uuid) | null Required

  The newsletter the change belongs to. This is the tenant boundary: a consumer only ever receives events for newsletters its credential can read. Null only for events that are genuinely not newsletter-scoped, which none of the 21 topics currently are.

• actor object | null Required

  Who caused the change. ALWAYS null today and consumers must treat it that way: the public API is currently read-only, so nothing that reaches this catalog was triggered through it, and Commune does not backfill an actor for changes made in the product UI or by a cron. The field exists now so that populating it, once writes exist, is an additive change rather than a new envelope version.

  Additional properties are NOT allowed.

  Hide actor attributes Show actor attributes object | null

  • type string Required

    user for a change a person made through an authenticated session, api_key for a public API write, system for a cron or webhook ingest with no human behind it.

    Values are user, api_key, or system.

  • id string Required

    Identifier of the actor within its type. A user id for user, a key id (never the secret) for api_key, a stable job name for system.

  • label string | null

    Human-readable name for display. Best effort, may be null.

• idempotency_key string | null Required

  ALWAYS null today. Once the public API accepts writes this carries the Idempotency-Key header of the write that caused the change, so a consumer can tie an event back to its own request and collapse the duplicates a retried write would otherwise produce. Null stays a legitimate value even then: a change made in the product UI or by a cron has no originating request to key on.

  Maximum length is 255.

• data object Required

  Event-specific body. Narrowed by each concrete event schema below.

  Hide data attributes Show data attributes object

  • highlight_id string(uuid) Required

    The article_highlights row.

  • article_id string(uuid) Required
  • quote string Required

    The marked text itself, as plain text, capped at 5000 characters on write. The surrounding prefix and suffix that let a client re-anchor the range are not here; read the highlight back from the REST API for those.

    Maximum length is 5000.

  • start_offset integer Required

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

    Minimum value is 0.

  • end_offset integer Required

    Where the passage ends, in the same offsets.

    Minimum value is 1.

  • owner_key string Required

    An opaque, stable per highlighter value, scoped to this one article. The same value the REST resource returns. Group by it to tell one reader's marks apart from another's. It cannot be resolved to a person and does not correlate across articles.

  • message_id string(uuid) | null Required

    The chat message the reader wrote from this passage, when the highlight was created as a discussion. Null for a silent highlight, and it stays null on this topic: attaching a message later updates the row rather than creating one.

  • created_at string(date-time) Required