annotation docs

Author: franrob-projects

src/pages/docs/api/rest-api.mdx

@@ -595,6 +595,135 @@ In each case a successful result is a [paginated response](#pagination) with an
 ```
 </Code>
 
+### Retrieve metadata for a channel <a id="metadata-rest" />
+
+#### GET rest.ably.io/channels/\{channelId\}
+
+This returns a [ChannelDetails](/docs/api/realtime-sdk/channel-metadata#channel-details) for the given channel, indicating global [occupancy](/docs/api/rest-sdk/channel-status#occupancy). A side-effect of this request, in the current version of this API, is that it will cause the channel in question to become activated; therefore it is primarily intended to be used in conjunction with the [enumeration API](#enumeration-rest) or in situations where the application has another means to know whether or not a given channel is active.
+
+### Enumerate all active channels <a id="enumeration-rest" />
+
+#### GET rest.ably.io/channels
+
+This enumerates all active channels in the application. This is a paginated API following the same API conventions as other paginated APIs in the [REST interface](/docs/api/rest-sdk).
+
+### Publish annotations for a message <a id="annotations-publish" />
+
+#### POST rest.ably.io/channels/\{channelId\}/messages/\{messageSerial\}/annotations
+
+Publish one or more [annotations](/docs/messages/annotations) for a specific message identified by its serial in the `messageSerial` url param. All annotations in a single request are published atomically and must be for the same message.
+
+See [our main annotation docs](/docs/messages/annotations) for more information on annotations.
+
+The request body contains an array of annotation objects:
+
+<Code>
+```json
+[{
+  action: <number; 0 is create, 1 is delete>,
+  type: <string, specifies how this annotation should be aggregated>,
+  name: <optional string, arbitrary string that many aggregation types use to group by>,
+  count: <optional number, used with the 'multiple' aggregation type>,
+  id: <optional string, client-specified idempotency key>,
+  clientId: <optional string, explicit client identifier>,
+  data: <optional JSON-encodable data>,
+  encoding: <optional string, encoding if specifying manually>,
+  extras: <optional extras object>
+}]
+```
+</Code>
+
+In JSON format, the accepted types for the `data` payload are:
+
+* string
+* any JSON-encodable Array or Object.
+
+MessagePack additionally [supports byte arrays](https://github.com/msgpack/msgpack/blob/master/spec.md#formats-bin)
+
+For annotation types and aggregation details, see [annotation types](/docs/messages/annotations#annotation-types).
+
+The message extras object is the same as for a message publish, see [message extras](#message-extras).
+
+The id is the same as for a message publish, see [idempotent publishing](#idempotent-publish)
+
+Example request:
+
+<Code>
+```shell
+curl -X POST https://rest.ably.io/channels/mutable:channel/messages/01726585978590-001@abcdefghij:001/annotations \
+ -u "{'{{API_KEY}}'}"{""}  \
+ -H "Content-Type: application/json" \
+ --data '[{ "action": 0, "type": "reaction:distinct.v1", "name": ":thumbsup:" }]'
+```
+</Code>
+
+##### Parameters
+
+None
+
+##### Options
+
+| Option | Value |
+|--------|-------|
+| Content-Type | `application/json` or `application/x-msgpack` |
+| Accept | `application/json` (the default), `application/x-msgpack` |
+| Auth required | yes ([basic](#basic-authentication) or [token](#token-authentication)) |
+
+##### Returns
+
+When successful, returns status code 201 and an object with annotation details. When unsuccessful, returns an error as an [ErrorInfo](/docs/api/rest-sdk/types#error-info) object.
+
+### Retrieve all annotations for a message <a id="annotations-list" />
+
+#### GET rest.ably.io/channels/\{channelId\}/messages/\{messageSerial\}/annotations
+
+Retrieve all annotations that have been published for a specific message identified by its serial, starting from the earliest.
+
+Example request:
+
+<Code>
+```shell
+curl https://rest.ably.io/channels/rest-example/messages/01726585978590-001@abcdefghij:001/annotations?limit=100 \
+ -u "{'{{API_KEY}}'}"{""}
+```
+</Code>
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| limit | The maximum number of records to return per page. A limit greater than 1,000 is invalid. Default: _100_ | integer |
+
+##### Options
+
+| Option | Value |
+|--------|-------|
+| Accept | `application/json` by default, or `application/x-msgpack` |
+| Auth required | yes ([basic](#basic-authentication) or [token](#token-authentication)) |
+
+##### Returns
+
+A successful request returns a [paginated response](#pagination) with an array containing the annotations for the specified message, starting from the first one to have been published for that message. If there are no annotations, an empty collection is returned.
+
+<Code>
+```json
+[{
+  action: <number; 0 for create, 1 for delete>,
+  serial: <unique serial of this annotation>,
+  id: <idempotency key>,
+  timestamp: <annotation timestamp in ms since epoch>
+  messageSerial: <the serial of the message that is being annotated>
+  type: <annotation type>,
+  name: <optional string>,
+  count: <optional number>,
+  clientId: <optional client identifier>,
+  data: <optional annotation payload>,
+  encoding: <optional encoding of the payload>,
+  extras: <optional extras object>,
+}]
+```
+</Code>
+
 ### Retrieve instantaneous presence status for a channel <a id="presence" />
 
 #### GET main.realtime.ably.net/channels/\{channelId\}/presence