Skip to content

Add message/client-summary endpoint docs #2872

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: annotations-rest-api
Choose a base branch
from
Open

Add message/client-summary endpoint docs #2872

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions content/api/rest-api.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -675,6 +675,32 @@ bc[json]. [{
extras: <optional extras object>,
}]

h3(#annotations-client-summary). Retrieve annotation summary for a specific clientId

h6. GET rest.ably.io/channels/@<channelId>@/messages/@<messageSerial>@/client-summary
Copy link
Contributor

@m-hulbert m-hulbert Oct 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The base branch likely needs rebasing as well, but I recently updated all endpoints to the new format (main.realtime.ably.net)


Retrieve the annotation summary for a specific clientId for a specific message identified by its serial.

Example request:

bc[sh]. curl https://rest.ably.io/channels/rest-example/messages/01726585978590-001@abcdefghij:001/client-summary?forClientId=client1 \
-u "{{API_KEY}}"

h5. Parameters

- forClientId := _client1_ The clientId to retrieve the annotation summary for. It defaults to the clientId of the authenticated client.
Copy link
Member

@SimonWoolf SimonWoolf Oct 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can I ask why we ended up with forClientId on this endpoint? Every other rest endpoint that accepts a client id parameter uses clientId

Copy link
Contributor Author

@vladvelici vladvelici Oct 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought clientId is used for authentication, to act on behalf of the given clientId. This endpoint should allow you to fetch the summary of any client, not just yours.

I mean if you don't have access to act on behalf of another clientId you can still fetch a sliced summary for that clientId.


h5. Options

- Accept := @application/json@ by default, or @application/x-msgpack@
- Auth required := yes ("basic":#basic-authentication or "token":#token-authentication)

h5. Returns

A successful request returns an object containing the annotation summary for the specified message, clipped to only include the summary for the requested clientId.

The summary is an object whose keys are annotation types, and the values are aggregated summaries for that annotation type.

h2(#push). Push

h3(#post-device-registration). Register a device for receiving push notifications
Expand Down