From 5031308f46fc3770dcfd56aca5d191e28e98a37a Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Thu, 11 Jun 2026 16:45:20 +0530 Subject: [PATCH] [DX-144] Sync Control API spec with latest Control API source Brings static/open-specs/control-v1.yaml in line with the Control API implementation and its generated swagger document: - Add missing rule target fields: exchange (amqp/external), primarySite and provisionedCapacity (postgres outbox and mongodb ingress), watch (mongodb ingress), and status on amqp/external and Google Cloud Function create schemas - Add legacy webhook rule type to rule_response for batch-mode rules created before the http rule type was introduced - Add missing endpoints: GET /me/accounts and POST /help, with me_accounts, help_request and help_response schemas - Add inProgress and required fields to account and app stats responses - Fix namespace schemas: add missing type to conflationEnabled, correct batchingInterval description, mark batching and conflation fields nullable, and document that mutableMessages requires persisted - Mark key_response name nullable and align unsupported rule target with additionalProperties true - Point the docs page at the spec's new home in ably/docs --- .../docs/platform/account/control-api.mdx | 4 +- static/open-specs/control-v1.yaml | 341 +++++++++++++++++- 2 files changed, 336 insertions(+), 9 deletions(-) diff --git a/src/pages/docs/platform/account/control-api.mdx b/src/pages/docs/platform/account/control-api.mdx index c5445e1ed1..91177fe104 100644 --- a/src/pages/docs/platform/account/control-api.mdx +++ b/src/pages/docs/platform/account/control-api.mdx @@ -38,7 +38,7 @@ The Control API limits the number of requests per account and per access token p ## OpenAPI document -The OpenAPI document for this API can be found in the Ably OpenAPI Documents [GitHub repository](https://github.com/ably/open-specs). It is not required in order to use Control API, but is provided to you so you may optionally generate your own documentation in the tool of your choice, or use mocking tools such as [Prism](https://stoplight.io/open-source/prism/) to assist in developing your clients. +The OpenAPI document for this API can be found in the Ably OpenAPI Documents [GitHub repository](https://github.com/ably/docs/tree/main/static/open-specs). It is not required in order to use Control API, but is provided to you so you may optionally generate your own documentation in the tool of your choice, or use mocking tools such as [Prism](https://stoplight.io/open-source/prism/) to assist in developing your clients. In the [testing with Postman](#postman) section you learn how to import this OpenAPI document into Postman, to enable you to quickly try out Control API. @@ -797,7 +797,7 @@ A convenient way to try out the Control API is by importing the OpenAPI document ![Postman import dialog](../../../../images/content/screenshots/control-api/postman-import-dialog.png) -3. Click the **Link** tab, and paste in the following URL: `https://raw.githubusercontent.com/ably/open-specs/main/definitions/control-v1.yaml`, then click **Continue**: +3. Click the **Link** tab, and paste in the following URL: `https://raw.githubusercontent.com/ably/docs/refs/heads/main/static/open-specs/control-v1.yaml`, then click **Continue**: ![Link to OpenAPI document](../../../../images/content/screenshots/control-api/postman-link.png) diff --git a/static/open-specs/control-v1.yaml b/static/open-specs/control-v1.yaml index d51c4cc186..5ac1592008 100644 --- a/static/open-specs/control-v1.yaml +++ b/static/open-specs/control-v1.yaml @@ -1325,6 +1325,71 @@ paths: application/json: schema: "$ref": "#/components/schemas/error" + "/me/accounts": + get: + summary: List accounts for the authenticated user + description: Retrieve the list of accounts that are accessible to the token the current user authenticates with. + tags: + - tokens + security: + - bearer_auth: [] + responses: + '200': + description: List of accounts + content: + application/json: + schema: + "$ref": "#/components/schemas/me_accounts" + '401': + description: Authentication failed + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + '500': + description: Internal server error + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + "/help": + post: + summary: Get help answering a question + description: Ask a question about Ably and receive an answer generated from the Ably documentation, along with links to relevant documentation pages. + tags: + - help + security: + - bearer_auth: [] + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/help_request" + responses: + '200': + description: Answer provided + content: + application/json: + schema: + "$ref": "#/components/schemas/help_response" + '400': + description: Invalid request. Only `user` and `assistant` roles are accepted in the conversation context. + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + '401': + description: Authentication failed + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + '500': + description: Internal server error + content: + application/json: + schema: + "$ref": "#/components/schemas/error" components: securitySchemes: @@ -1482,6 +1547,7 @@ components: - "$ref": "#/components/schemas/bodyguard_text_moderation_rule_response" - "$ref": "#/components/schemas/tisane_text_moderation_rule_response" - "$ref": "#/components/schemas/azure_text_moderation_rule_response" + - "$ref": "#/components/schemas/webhook_rule_response" - "$ref": "#/components/schemas/unsupported_rule_response" discriminator: propertyName: ruleType @@ -1508,6 +1574,7 @@ components: bodyguard/text-moderation: "#/components/schemas/bodyguard_text_moderation_rule_response" tisane/text-moderation: "#/components/schemas/tisane_text_moderation_rule_response" azure/text-moderation: "#/components/schemas/azure_text_moderation_rule_response" + webhook: "#/components/schemas/webhook_rule_response" unsupported: "#/components/schemas/unsupported_rule_response" http_rule_post: type: object @@ -2452,6 +2519,10 @@ components: type: object additionalProperties: false properties: + status: + type: string + description: The status of the rule. Rules can be enabled or disabled. + example: enabled ruleType: type: string enum: @@ -3531,6 +3602,10 @@ components: type: object additionalProperties: false properties: + status: + type: string + description: The status of the rule. Rules can be enabled or disabled. + example: enabled ruleType: type: string enum: @@ -3555,6 +3630,10 @@ components: type: string description: The AMQP routing key. The routing key is used by the AMQP exchange to route messages to a physical queue. See this Ably FAQs for details. example: 'message name: #{message.name}, clientId: #{message.clientId}' + exchange: + type: string + description: The AMQP exchange that messages are published to. The exchange routes messages to queues using the routing key. + example: my-exchange mandatoryRoute: type: boolean description: Reject delivery of the message if the route does not exist, otherwise fail silently. @@ -3632,6 +3711,10 @@ components: type: string description: The AMQP routing key. The routing key is used by the AMQP exchange to route messages to a physical queue. See this Ably FAQs for details. example: 'message name: #{message.name}, clientId: #{message.clientId}' + exchange: + type: string + description: The AMQP exchange that messages are published to. The exchange routes messages to queues using the routing key. + example: my-exchange mandatoryRoute: type: boolean description: Reject delivery of the message if the route does not exist, otherwise fail silently. @@ -3724,6 +3807,10 @@ components: type: string description: The AMQP routing key. The routing key is used by the AMQP exchange to route messages to a physical queue. See this Ably FAQs for details. example: 'message name: #{message.name}, clientId: #{message.clientId}' + exchange: + type: string + description: The AMQP exchange that messages are published to. The exchange routes messages to queues using the routing key. + example: my-exchange mandatoryRoute: type: boolean description: Reject delivery of the message if the route does not exist, otherwise fail silently. @@ -4331,6 +4418,16 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz 7Y+sUx6eIl4dlNl9kVrH1TD3EwwtGsjUNlFSZhg= -----END CERTIFICATE-----" nullable: true + primarySite: + type: string + description: The primary site that the connector will run in. + example: us-east-1-A + provisionedCapacity: + type: integer + description: The provisioned capacity of the connector. + minimum: 1 + maximum: 4 + example: 1 required: - url - outboxTableSchema @@ -4338,6 +4435,7 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz - nodesTableSchema - nodesTableName - sslMode + - primarySite required: - ruleType - target @@ -4398,6 +4496,16 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz 7Y+sUx6eIl4dlNl9kVrH1TD3EwwtGsjUNlFSZhg= -----END CERTIFICATE-----" nullable: true + primarySite: + type: string + description: The primary site that the connector will run in. + example: us-east-1-A + provisionedCapacity: + type: integer + description: The provisioned capacity of the connector. + minimum: 1 + maximum: 4 + example: 1 required: - url - outboxTableSchema @@ -4405,6 +4513,7 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz - nodesTableSchema - nodesTableName - sslMode + - primarySite required: - ruleType - target @@ -4488,6 +4597,16 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz 7Y+sUx6eIl4dlNl9kVrH1TD3EwwtGsjUNlFSZhg= -----END CERTIFICATE-----" nullable: true + primarySite: + type: string + description: The primary site that the connector will run in. + example: us-east-1-A + provisionedCapacity: + type: integer + description: The provisioned capacity of the connector. + minimum: 1 + maximum: 4 + example: 1 required: - ruleType - target @@ -4549,6 +4668,19 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz - us-east-1-A - us-east-2-A - us-west-1-A + watch: + type: string + description: The scope that the connector watches for changes. Currently only `COLLECTION` is supported, which watches the configured collection. + default: COLLECTION + example: COLLECTION + enum: + - COLLECTION + provisionedCapacity: + type: integer + description: The provisioned capacity of the connector. + minimum: 1 + maximum: 1 + example: 1 required: - url - database @@ -4618,6 +4750,19 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz - us-east-1-A - us-east-2-A - us-west-1-A + watch: + type: string + description: The scope that the connector watches for changes. Currently only `COLLECTION` is supported, which watches the configured collection. + default: COLLECTION + example: COLLECTION + enum: + - COLLECTION + provisionedCapacity: + type: integer + description: The provisioned capacity of the connector. + minimum: 1 + maximum: 1 + example: 1 ingress_mongodb_changestream_rule_response: type: object additionalProperties: false @@ -4646,6 +4791,9 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz type: number description: Unix timestamp representing the date and time of last modification of the rule. example: 1602844091815 + _links: + type: object + nullable: true ruleType: type: string description: The type of rule. See the Ably integrations docs for further information. @@ -4696,6 +4844,19 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz - us-east-1-A - us-east-2-A - us-west-1-A + watch: + type: string + description: The scope that the connector watches for changes. Currently only `COLLECTION` is supported, which watches the configured collection. + default: COLLECTION + example: COLLECTION + enum: + - COLLECTION + provisionedCapacity: + type: integer + description: The provisioned capacity of the connector. + minimum: 1 + maximum: 1 + example: 1 before_publish_aws_lambda_rule_post: type: object additionalProperties: false @@ -6625,6 +6786,64 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz - beforePublishConfig - invocationMode - chatRoomFilter + webhook_rule_response: + type: object + additionalProperties: false + properties: + id: + type: string + description: The rule ID. + example: 83IzAB + appId: + type: string + description: The Ably application ID. + example: 28GY6a + version: + type: string + description: API version. Events and the format of their payloads are versioned. Please see the webhooks docs. + example: '1.2' + status: + type: string + description: The status of the rule. Rules can be enabled or disabled. + example: enabled + created: + type: number + description: Unix timestamp representing the date and time of creation of the rule. + example: 1602844091815 + modified: + type: number + description: Unix timestamp representing the date and time of last modification of the rule. + example: 1614679682091 + _links: + type: object + nullable: true + ruleType: + type: string + description: The type of rule. In this case a legacy batch-mode webhook rule. This rule type cannot be created or updated via the Control API, but may be returned for rules created before the current `http` rule type was introduced. + enum: + - webhook + example: webhook + requestMode: + type: string + description: This is always Batch Request mode for legacy webhook rules. Batch Request mode rolls up multiple events into the same request. You can read more about batched events in the Ably batching docs. + example: batch + source: + "$ref": "#/components/schemas/rule_source" + target: + type: object + additionalProperties: true + properties: + url: + type: string + description: The webhook URL that Ably will POST events to. + example: https://example.com/webhooks + required: + - url + required: + - ruleType + - requestMode + - source + - target unsupported_rule_response: type: object additionalProperties: false @@ -6670,7 +6889,7 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz "$ref": "#/components/schemas/rule_source" target: type: object - additionalProperties: false + additionalProperties: true properties: url: type: string @@ -6843,24 +7062,30 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz example: false batchingEnabled: type: boolean + nullable: true default: false description: If `true`, channels within this namespace will start batching inbound messages instead of sending them out immediately to subscribers. example: false batchingInterval: type: integer + nullable: true default: 20 - description: If `true`, the batching interval, configurable from 20ms to 1s, temporarily holds and aggregates incoming messages. These messages are then combined and delivered as a single batch once the interval elapses or a size limit is reached (before the interval elapses). + description: The batching interval in milliseconds, configurable from 20ms to 1s. Temporarily holds and aggregates incoming messages, which are then combined and delivered as a single batch once the interval elapses or a size limit is reached. example: 20 conflationEnabled: + type: boolean + nullable: true default: false description: If `true`, enables conflation for channels within this namespace. Conflation will aggregate published messages for a set period of time and evaluate them against a conflation key. Only the most recent message that satisfies the key will be sent to subscribers at the end of the conflation interval. example: false conflationInterval: type: integer + nullable: true description: The interval in milliseconds over which messages are held and evaluated for conflation. example: 1000 conflationKey: type: string + nullable: true description: The key used to determine which messages should be conflated. tlsOnly: type: boolean @@ -6874,7 +7099,7 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz mutableMessages: type: boolean default: false - description: If `true`, messages published on channels within this namespace can be updated or deleted after publishing. See the message interactions documentation for more details. + description: Set to `true` and messages can be updated, edited or appended on a channel, after they have been published. Requires `persisted` set to `true`. See the message interactions documentation for more details. example: false populateChannelRegistry: type: boolean @@ -6909,24 +7134,30 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz example: false batchingEnabled: type: boolean + nullable: true default: false description: If `true`, channels within this namespace will start batching inbound messages instead of sending them out immediately to subscribers. example: false batchingInterval: type: integer + nullable: true default: 20 - description: If `true`, the batching interval, configurable from 20ms to 1s, temporarily holds and aggregates incoming messages. These messages are then combined and delivered as a single batch once the interval elapses or a size limit is reached (before the interval elapses). + description: The batching interval in milliseconds, configurable from 20ms to 1s. Temporarily holds and aggregates incoming messages, which are then combined and delivered as a single batch once the interval elapses or a size limit is reached. example: 20 conflationEnabled: + type: boolean + nullable: true default: false description: If `true`, enables conflation for channels within this namespace. Conflation will aggregate published messages for a set period of time and evaluate them against a conflation key. Only the most recent message that satisfies the key will be sent to subscribers at the end of the conflation interval. example: false conflationInterval: type: integer + nullable: true description: The interval in milliseconds over which messages are held and evaluated for conflation. example: 1000 conflationKey: type: string + nullable: true description: The key used to determine which messages should be conflated. tlsOnly: type: boolean @@ -6938,7 +7169,7 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz description: If `true`, messages received on a channel will contain a unique `timeserial` that can be referenced by later messages for use with message interactions. mutableMessages: type: boolean - description: If `true`, messages published on channels within this namespace can be updated or deleted after publishing. See the message interactions documentation for more details. + description: Set to `true` and messages can be updated, edited or appended on a channel, after they have been published. Requires `persisted` set to `true`. See the message interactions documentation for more details. example: false populateChannelRegistry: type: boolean @@ -6986,24 +7217,30 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz example: false batchingEnabled: type: boolean + nullable: true default: false description: If `true`, channels within this namespace will start batching inbound messages instead of sending them out immediately to subscribers. example: false batchingInterval: type: integer + nullable: true default: 20 - description: If `true`, the batching interval, configurable from 20ms to 1s, temporarily holds and aggregates incoming messages. These messages are then combined and delivered as a single batch once the interval elapses or a size limit is reached (before the interval elapses). + description: The batching interval in milliseconds, configurable from 20ms to 1s. Temporarily holds and aggregates incoming messages, which are then combined and delivered as a single batch once the interval elapses or a size limit is reached. example: 20 conflationEnabled: + type: boolean + nullable: true default: false description: If `true`, enables conflation for channels within this namespace. Conflation will aggregate published messages for a set period of time and evaluate them against a conflation key. Only the most recent message that satisfies the key will be sent to subscribers at the end of the conflation interval. example: false conflationInterval: type: integer + nullable: true description: The interval in milliseconds over which messages are held and evaluated for conflation. example: 1000 conflationKey: type: string + nullable: true description: The key used to determine which messages should be conflated. tlsOnly: type: boolean @@ -7015,7 +7252,7 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz description: If `true`, messages received on a channel will contain a unique `timeserial` that can be referenced by later messages for use with message interactions. mutableMessages: type: boolean - description: If `true`, messages published on channels within this namespace can be updated or deleted after publishing. See the message interactions documentation for more details. + description: Set to `true` and messages can be updated, edited or appended on a channel, after they have been published. Requires `persisted` set to `true`. See the message interactions documentation for more details. example: false populateChannelRegistry: type: boolean @@ -7348,6 +7585,7 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz name: description: The name for your API key. This is a friendly name for your reference. type: string + nullable: true example: 'My key name' revocableTokens: type: boolean @@ -7452,6 +7690,75 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz required: - id - name + me_accounts: + type: array + description: The accounts accessible to the access token the current user authenticates with. + items: + type: object + additionalProperties: false + properties: + id: + type: string + description: The account ID. + example: VpWaOA + name: + type: string + description: The name of the account. + example: Free account + required: + - id + - name + help_request: + type: object + additionalProperties: false + properties: + question: + type: string + description: The question to ask about Ably. + example: How do I publish a message to a channel? + context: + type: array + description: Optional previous conversation context. Only `user` and `assistant` roles are accepted. + items: + type: object + additionalProperties: false + properties: + role: + type: string + description: The role of the message author. Must be `user` or `assistant`. + enum: + - user + - assistant + example: user + content: + type: string + description: The content of the message. + required: + - role + - content + required: + - question + help_response: + type: object + additionalProperties: false + properties: + answer: + type: string + description: The generated answer to the question. + links: + type: array + description: Links to documentation pages relevant to the answer. + items: + type: object + properties: + href: + type: string + description: URL of the documentation page. + title: + type: string + description: Title of the documentation page. + required: + - answer account_stats_response: type: object additionalProperties: false @@ -7479,6 +7786,16 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz example: { "messages.all.all.count": 10293, "connections.all.peak": 510, "channels.peak": 68 } + inProgress: + type: string + description: The last sub-interval included in this statistics record, in the format `yyyy-mm-dd:hh:mm:ss`, if the most recent interval is still in progress. + example: "2024-08-04:20:42:10" + required: + - intervalId + - unit + - accountId + - schema + - entries app_stats_response: type: object additionalProperties: false @@ -7506,6 +7823,16 @@ TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz example: { "messages.all.all.count": 723, "connections.all.peak": 201, "channels.peak": 27 } + inProgress: + type: string + description: The last sub-interval included in this statistics record, in the format `yyyy-mm-dd:hh:mm:ss`, if the most recent interval is still in progress. + example: "2024-08-04:20:42:10" + required: + - intervalId + - unit + - appId + - schema + - entries error: type: object additionalProperties: false