ably · m-hulbert · Dec 12, 2025 · Dec 12, 2025 · Dec 12, 2025 · Dec 12, 2025
diff --git a/src/data/nav/platform.ts b/src/data/nav/platform.ts
@@ -238,7 +238,7 @@ export default {
       pages: [
         {
           name: 'Overview',
-          link: '/docs/account',
+          link: '/docs/platform/account',
           index: true,
         },
         {

diff --git a/src/pages/docs/api/index.mdx b/src/pages/docs/api/index.mdx
@@ -1,11 +1,10 @@
 ---
 title: API Reference
+intro: "This section of the documentation contains the API references for Ably."
 meta_description: "API reference section of the Ably developer documentation."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, REST SDK, REST API, SSE API, Control API"
 ---
 
-This section of the documentation contains the API references for Ably.
-
 The following API references are available:
 
 * [Client library Realtime SDK](/docs/api/realtime-sdk)

diff --git a/src/pages/docs/api/realtime-sdk.mdx b/src/pages/docs/api/realtime-sdk.mdx
@@ -1,5 +1,6 @@
 ---
 title: Constructor
+intro: "The realtime interface of Ably SDKs establishes and maintains a persistent connection the Ably service. You can publish and subscribe to messages on channels over this connection."
 meta_description: "Realtime Client Library SDK API reference section for the constructor object."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, constructor, instantiate"
 redirect_from:

diff --git a/src/pages/docs/api/realtime-sdk/authentication.mdx b/src/pages/docs/api/realtime-sdk/authentication.mdx
@@ -1,28 +1,14 @@
 ---
 title: Authentication
+intro: "Authenticate with Ably using API keys, JWTs, or tokens."
 meta_description: "Realtime Client Library SDK API reference section for authentication."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, auth, authentication, token, JWT, basic auth"
-jump_to:
-  Help with:
-    - Tokens#tokens
-    - Auth object#auth-object
-  Auth API properties:
-    - clientId#client-id
-  Auth API methods:
-    - authorize
-    - createTokenRequest#create-token-request
-    - requestToken#request-token
-    - revokeTokens#revoke-tokens
-  Types:
-    - Related Types#related-types
 redirect_from:
   - /docs/api/versions/v1.1/realtime-sdk/authentication
   - /docs/api/versions/v1.0/realtime-sdk/authentication
   - /docs/api/versions/v0.8/realtime-sdk/authentication
 ---
 
-This is the Authentication API Reference.
-
 ## Tokens <a id="#tokens" />
 
 In the documentation, references to Ably-compatible tokens typically refer either to an Ably Token, or an [Ably JWT](#ably-jwt). For Ably Tokens, this can either be referring to the `TokenDetails` object that contain the `token` string or the token string itself. `TokenDetails` objects are obtained when [requesting an Ably Token](#request-token) from the Ably service and contain not only the `token` string in the `token` attribute, but also contain attributes describing the properties of the Ably Token. For [Ably JWT](#ably-jwt), this will be simply referring to a JWT which has been signed by an Ably private API key.

diff --git a/src/pages/docs/api/realtime-sdk/channel-metadata.mdx b/src/pages/docs/api/realtime-sdk/channel-metadata.mdx
@@ -1,5 +1,6 @@
 ---
 title: Channel Metadata
+intro: "Channel metadata provides information about the state and occupancy of channels."
 meta_description: "Realtime Client Library SDK API reference section for channel metadata."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, channel, metadata, channel metadata, occupancy"
 redirect_from:

diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx
@@ -1,5 +1,6 @@
 ---
 title: Channels
+intro: "Use the Channels object and Channel objects to interact with Ably channels."
 meta_description: "Realtime Client Library SDK API reference section for the channels and channel objects."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, channel, channel, channels, publish, subscribe"
 redirect_from:

diff --git a/src/pages/docs/api/realtime-sdk/connection.mdx b/src/pages/docs/api/realtime-sdk/connection.mdx
@@ -1,5 +1,6 @@
 ---
 title: Connection
+intro: "Use the Connection object to manage persistent connections to the Ably service."
 meta_description: "Realtime Client Library SDK API reference section for the connection object."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, connect, connection"
 redirect_from:

diff --git a/src/pages/docs/api/realtime-sdk/encryption.mdx b/src/pages/docs/api/realtime-sdk/encryption.mdx
@@ -1,14 +1,8 @@
 ---
 title: Encryption
+intro: "Use the Crypto object to encrypt and decrypt messages."
 meta_description: "Realtime Client Library SDK API reference section for the crypto object."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, encryption, crypto"
-jump_to:
-  API Reference:
-    - getDefaultParams#get-default-params
-    - generateRandomKey#generate-random-key
-  Related types:
-    - Channel Options
-    - CipherParams#cipher-params
 redirect_from:
   - /docs/api/versions/v1.1/realtime-sdk/encryption
   - /docs/api/versions/v1.0/realtime-sdk/encryption

diff --git a/src/pages/docs/api/realtime-sdk/history.mdx b/src/pages/docs/api/realtime-sdk/history.mdx
@@ -1,13 +1,8 @@
 ---
 title: History
+intro: "Use the history method to retrieve previously sent messages and presence events from a channel."
 meta_description: "Realtime Client Library SDK API reference section for the history methods."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, history, message, presence"
-jump_to:
-  API reference:
-    - Message history#channel-history
-    - Presence history#presence-history
-  Types:
-    - Related Types#related-types
 redirect_from:
   - /docs/api/versions/v1.1/realtime-sdk/history
   - /docs/api/versions/v1.0/realtime-sdk/history

diff --git a/src/pages/docs/api/realtime-sdk/messages.mdx b/src/pages/docs/api/realtime-sdk/messages.mdx
@@ -1,5 +1,6 @@
 ---
 title: Messages
+intro: "A Message represents an individual message that is sent to or received from Ably."
 meta_description: "Realtime Client Library SDK API reference section for the message object."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, message, messages"
 redirect_from:
@@ -10,8 +11,6 @@ redirect_from:
 
 ## <If lang="javascript,nodejs,flutter,csharp,objc,swift">Properties</If><If lang="ruby">Attributes</If><If lang="java">Members</If> <a id="properties" />
 
-A `Message` represents an individual message that is sent to or received from Ably.
-
 ### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">name</If><If lang="csharp">Name</If> <a id="name" />
 
 The event name, if provided. <br />_Type: `String`_

diff --git a/src/pages/docs/api/realtime-sdk/presence.mdx b/src/pages/docs/api/realtime-sdk/presence.mdx
@@ -1,23 +1,8 @@
 ---
 title: Presence
+intro: "Use the Presence object to manage and interact with presence on Ably channels."
 meta_description: "Realtime Client Library SDK API reference section for the presence object."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, presence"
-jump_to:
-  Presence API properties:
-    - syncComplete#sync-complete
-  Presence API methods:
-    - enter
-    - leave
-    - update
-    - get
-    - history
-    - subscribe
-    - unsubscribe
-    - enterClient#enter-client
-    - leaveClient#leave-client
-    - updateClient#update-client
-  Types:
-    - Related Types#related-types
 redirect_from:
   - /docs/api/versions/v1.1/realtime-sdk/presence
   - /docs/api/versions/v1.0/realtime-sdk/presence

diff --git a/src/pages/docs/api/realtime-sdk/push-admin.mdx b/src/pages/docs/api/realtime-sdk/push-admin.mdx
@@ -1,14 +1,8 @@
 ---
 title: Push Notifications - Admin
+intro: "Use the Push.Admin object to manage push notifications, including device registrations and channel subscriptions."
 meta_description: "Realtime Client Library SDK API reference section for push notifications admin."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, push, push notification, notification, push notifications, notifications, admin, push admin"
-jump_to:
-  API reference:
-    - publish#publish
-    - DeviceRegistrations#device-registrations-object
-    - PushChannelSubscriptions#push-channel-subscriptions
-  Types:
-    - Related Types#related-types
 redirect_from:
   - /docs/api/versions/v1.1/realtime-sdk/push-admin
 ---

diff --git a/src/pages/docs/api/realtime-sdk/push.mdx b/src/pages/docs/api/realtime-sdk/push.mdx
@@ -1,13 +1,8 @@
 ---
 title: Push Notifications - Device Activation and Subscription
+intro: "Use the Push object to activate push notification devices and manage push channel subscriptions."
 meta_description: "Realtime Client Library SDK API reference section for push notification device subscription."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, push, push notification, notification, push notifications, notifications, device subscription, activate device"
-jump_to:
-  API reference:
-    - activate#activate
-    - deactivate#deactivate
-  Types:
-    - Related Types#related-types
 redirect_from:
   - /docs/api/versions/v1.1/realtime-sdk/push
 ---

diff --git a/src/pages/docs/api/realtime-sdk/statistics.mdx b/src/pages/docs/api/realtime-sdk/statistics.mdx
@@ -1,5 +1,6 @@
 ---
 title: Statistics
+intro: "Use the stats method to retrieve your application's usage statistics."
 meta_description: "Realtime Client Library SDK API reference section for the stats object."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, stats, statistics"
 redirect_from:

diff --git a/src/pages/docs/api/realtime-sdk/types.mdx b/src/pages/docs/api/realtime-sdk/types.mdx
@@ -1,5 +1,6 @@
 ---
 title: Types
+intro: "Ably SDKs define both data types and option types. Data types are used to represent object such as messages. Option types are used in method arguments."
 meta_description: "Realtime Client Library SDK API reference section for types."
 meta_keywords: "Ably, Ably realtime, API Reference, Realtime SDK, types, objects, options"
 redirect_from:
@@ -12,9 +13,7 @@ redirect_from:
   - /docs/realtime/versions/v0.8/types
 ---
 
-The Ably client library defines both data types and option types. Data types are used to represent object such as messages. Option types are used in method arguments.
-
-Where client libraries support both Realtime and REST APIs, the types are shared between both clients.
+Where SDKs support both Realtime and REST interfaces, types are shared between both clients.
 
 All types are always classes or their respective equivalent for each language implementation. Options on the other hand, may often support both typed option classes or more flexible key value objects such as a Hash or plain JavaScript object.
 

diff --git a/src/pages/docs/api/rest-api.mdx b/src/pages/docs/api/rest-api.mdx
@@ -1,47 +1,8 @@
 ---
 title: REST API Reference
+intro: "The Ably REST API provides a way for a wide range of server and client devices to communicate with the Ably service over REST."
 meta_description: "Ably provides the raw REST API for situations where an Ably client library SDK is not available on the platform of choice, or due to resource constraints."
 meta_keywords: "REST API, REST, protocol, resource constraints"
-jump_to:
-  Intro:
-    - Common API behavior#common
-  Authentication:
-    - Authentication
-    - Basic Authentication
-    - Token Authentication
-  Channel API:
-    - publish
-    - message history#message-history
-    - get message#get-message
-    - update message#update-message
-    - delete message#delete-message
-    - message versions#message-versions
-    - presence
-    - presence history
-  Push API:
-    - register device#post-device-registration
-    - update a device registration#update-device-registration
-    - get registered device#get-device-registration
-    - list registered devices#list-device-registrations
-    - reset a device's update token#reset-update-token
-    - unregister device#delete-device-registration
-    - unregister devices#delete-device-registrations
-    - subscribe to a channel#post-channel-subscription
-    - unsubscribe from channels#delete-channel-subscription
-    - list channel subscriptions#list-channel-subscriptions
-    - list channels#list-channels
-    - publish directly to device#push-publish
-    - publish via batch push API#push-publish-batch
-  Authentication API:
-    - requestToken#request-token
-    - revokeTokens#revoke-tokens
-  Application API:
-    - stats
-  Batch API:
-    - batch publish#batch-publish
-    - batch presence#batch-presence
-  Utilities API:
-    - time
 redirect_from:
   - /docs/api/versions/v1.1/rest-api
   - /docs/api/versions/v1.0/rest-api
@@ -54,9 +15,7 @@ redirect_from:
   - /docs/rest-api/versions/v1.1/beta
 ---
 
-Welcome to the Ably REST API Reference documentation.
-
-The Ably REST API provides a way for a wide range of server and client devices to communicate with the Ably service over [REST](https://en.wikipedia.org/wiki/Representational_State_Transfer). The REST API does not provide a realtime long-lived connection to Ably, but in all other respects is a simple subset of the full [realtime messaging API](/docs/api/realtime-sdk).
+The REST API does not provide a realtime long-lived connection to Ably, but in all other respects is a simple subset of the full [realtime messaging API](/docs/api/realtime-sdk).
 
 The primary use-case for the REST API is for servers that are part of the back-end of an application such as a web application, that publish messages, issue access tokens (temporary and client-specific) for its various clients, obtain message and presence history, and retrieve statistics.
 

diff --git a/src/pages/docs/api/rest-sdk.mdx b/src/pages/docs/api/rest-sdk.mdx
@@ -1,5 +1,6 @@
 ---
 title: Constructor
+intro: "The REST interface of Ably SDKS provides a simple way to interact with the Ably service over standard HTTP methods. You can publish and retrieve messages, but you cannot subscribe to them."
 meta_description: "Client Library SDK REST API Reference constructor documentation."
 meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, constructor"
 redirect_from:

diff --git a/src/pages/docs/api/rest-sdk/authentication.mdx b/src/pages/docs/api/rest-sdk/authentication.mdx
@@ -1,20 +1,8 @@
 ---
 title: Authentication
+intro: "Authenticate with Ably using API keys, JWTs, or tokens."
 meta_description: "Client Library SDK REST API Reference Authentication documentation."
 meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Authentication"
-jump_to:
-  Help with:
-    - Tokens#tokens
-    - Auth object#auth-object
-  Auth API properties:
-    - clientId#client-id
-  Auth API methods:
-    - authorize
-    - createTokenRequest#create-token-request
-    - requestToken#request-token
-    - revokeTokens#revoke-tokens
-  Types:
-    - Related Types#related-types
 redirect_from:
   - /docs/api/versions/v1.1/rest-sdk/authentication
   - /docs/api/versions/v1.0/rest-sdk/authentication

diff --git a/src/pages/docs/api/rest-sdk/channel-status.mdx b/src/pages/docs/api/rest-sdk/channel-status.mdx
@@ -1,14 +1,8 @@
 ---
 title: Channel Status
+intro: "Channel status provides information about the state and occupancy of channels."
 meta_description: "Client Library SDK REST API Reference Channel Status documentation."
 meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Channel Status"
-section: api
-index: 30
-jump_to:
-  Channel API Types:
-    - ChannelDetails#channel-details
-    - ChannelStatus#channel-status
-    - Occupancy#occupancy
 redirect_from:
   - /docs/api/versions/v1.1/rest-sdk/channel-status
   - /docs/api/versions/v1.0/rest-sdk/channel-status

diff --git a/src/pages/docs/api/rest-sdk/channels.mdx b/src/pages/docs/api/rest-sdk/channels.mdx
@@ -1,5 +1,6 @@
 ---
 title: Channels
+intro: "The Channels object and Channel objects are used to interact with Ably channels."
 meta_description: "Client Library SDK REST API Reference Channels documentation."
 meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Channels"
 redirect_from:

diff --git a/src/pages/docs/api/rest-sdk/encryption.mdx b/src/pages/docs/api/rest-sdk/encryption.mdx
@@ -1,14 +1,8 @@
 ---
 title: Encryption
+intro: "Use the Crypto object to encrypt and decrypt messages."
 meta_description: "Client Library SDK REST API Reference Crypto documentation."
 meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Encryption, Crypto"
-jump_to:
-  API Reference:
-    - getDefaultParams#get-default-params
-    - generateRandomKey#generate-random-key
-  Related types:
-    - Channel Options
-    - CipherParams#cipher-params
 redirect_from:
   - /docs/api/versions/v1.1/rest-sdk/encryption
   - /docs/api/versions/v1.0/rest-sdk/encryption

diff --git a/src/pages/docs/api/rest-sdk/history.mdx b/src/pages/docs/api/rest-sdk/history.mdx
@@ -1,13 +1,8 @@
 ---
 title: History
+intro: "Use the history method to retrieve previously sent messages and presence events from a channel."
 meta_description: "Client Library SDK REST API Reference History documentation."
 meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, History"
-jump_to:
-  API reference:
-    - Message history#channel-history
-    - Presence history#presence-history
-  Types:
-    - Related Types#related-types
 redirect_from:
   - /docs/api/versions/v1.1/rest-sdk/history
   - /docs/api/versions/v1.0/rest-sdk/history

diff --git a/src/pages/docs/api/rest-sdk/messages.mdx b/src/pages/docs/api/rest-sdk/messages.mdx
@@ -1,5 +1,6 @@
 ---
 title: Messages
+intro: "A Message represents an individual message that is sent to or received from Ably."
 meta_description: "Client Library SDK REST API Reference Message documentation."
 meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Message"
 redirect_from:
@@ -8,8 +9,6 @@ redirect_from:
   - /docs/api/versions/v0.8/rest-sdk/messages
 ---
 
-A `Message` represents an individual message that is sent to or received from Ably.
-
 ### name <a id="name" />
 
 The event name, if provided. <br />_Type: `String`_

diff --git a/src/pages/docs/api/rest-sdk/presence.mdx b/src/pages/docs/api/rest-sdk/presence.mdx
@@ -1,13 +1,8 @@
 ---
 title: Presence
+intro: "Use the Presence object to retrieve information about the presence set of on Ably channel."
 meta_description: "Presence events provide clients with information about the status of other clients 'present' on a channel"
 meta_keywords: "Ably, presence, presence events, channel members, presence history."
-jump_to:
-  Presence API reference:
-    - get
-    - history
-  Types:
-    - Related Types#related-types
 redirect_from:
   - /docs/api/versions/v1.1/rest-sdk/presence
   - /docs/api/versions/v1.0/rest-sdk/presence

diff --git a/src/pages/docs/api/rest-sdk/push-admin.mdx b/src/pages/docs/api/rest-sdk/push-admin.mdx
@@ -1,15 +1,8 @@
 ---
 title: Push Notifications - Admin
+intro: "Use the Push.Admin object to manage push notifications, including device registrations and channel subscriptions."
 meta_description: "Client Library SDK REST API Reference Push documentation."
 meta_keywords: "Ably, Ably REST, API Reference, REST SDK, REST interface, REST API, Push"
-jump_to:
-  Push Admin API properties:
-    - deviceRegistrations#device-registrations
-    - channelSubscriptions#channel-subscriptions
-  Push Admin API methods:
-    - publish
-  Types:
-    - Related Types#related-types
 redirect_from:
   - /docs/api/rest-sdk/push
   - /docs/api/versions/v1.1/rest-sdk/push-admin