This contract belongs to the Worker development preview. It is not served by the public API yet.
Read an individual alert’s timeline
Supported targets are invoice, agreement, alert, claim, and topic. Each request targets
one resource in the authenticated organization. The response has data and next_cursor.
Each entry’s type is activity or comment. Activity includes its action, actor, structured
detail, and nullable entity version. Comments include their body, author, timestamps, and reply count.
Topics support activity only.
Results contain individual entries, newest first. Use next_cursor to load older entries with
the same entity and filters. The maximum limit is 100. Edits and replies do not move comments.
Only top-level comments appear in the timeline.
Set entry_type=activity or entry_type=comment to read one kind. For invoices, agreements,
claims, and topics, include_related_alerts=true also includes their current alerts’ activity.
Related comments are excluded. Released claim memberships do not contribute events.
alert_id filters events by direct alert identity or recorded alert references; optional
alert_operator=is_not excludes matching events. Alert filters return activity only and cannot
be combined with entry_type=comment. Filters apply before pagination. Unknown actions remain
readable, and unsupported historical detail is returned as null.
Post and reply
Comments support invoices, agreements, individual alerts, and claims. Bodies are trimmed and
must contain 1–5,000 characters. The authenticated user is the author, including personal API-key
requests. Creation returns 201, a Location header, and the comment. It is non-idempotent;
do not automatically retry when the result of a POST is uncertain.
To reply, include parent_comment_id. The parent must be a top-level comment on the same resource.
Use GET /v1/comments/{id}/replies to load replies oldest first, with independent cursor pagination.
Replies have the same comment shape, with reply_count: 0.
Edit and delete
GET /v1/comments/{id} retrieves a comment and its reply count.PATCH /v1/comments/{id} accepts { "body": "Updated text" } and returns the updated comment.DELETE /v1/comments/{id} returns 204 and permanently removes the comment.
Only the author can edit or delete a comment. Administrators have the same restriction.
Deleting a top-level comment also deletes every reply, including replies by other authors. Identical edits preserve the
update timestamp; other edits use last-write-wins semantics. Comment ownership cannot be changed.
Reads require Read access; mutations require Write. Inaccessible resources and non-owned mutation
targets return 404. Completed and cancelled claims remain commentable.
Grouped display and alert filters
Set group_changes=true to receive grouping metadata for the current page. Optional
value_blind_actions groups selected field-edit actions by field names without comparing values.
The cursor and limit still count individual entries. Groups may span pages; join only adjacent
fragments with the same key and at most five minutes between their boundary events, without an
intervening comment.
suppress_alert_scope_rollups overrides automatic suppression of redundant alert summaries.
Omit it to retain the existing related-alert behavior.
Populate alert filter values with the scoped GET /v1/alerts list, which already returns the title,
invoice number and topic/agreement context. Follow its pagination for additional values.
