Ably rules API

openapi: 3.0.1
info:
  title: Control API v1 apps rules API
  version: 1.0.32
  description: 'Use the Control API to manage your applications, namespaces, keys, queues, rules, and more.


    Detailed information on using this API can be found in the Ably <a href="https://ably.com/docs/account/control-api">Control API docs</a>.


    Control API is currently in Preview.

    '
servers:
- url: https://control.ably.net/v1
tags:
- name: rules
paths:
  /apps/{app_id}/rules:
    get:
      summary: Lists rules
      description: Lists the <a href="https://ably.com/docs/general/webhooks">rules</a> for the application specified by the application ID.
      tags:
      - rules
      parameters:
      - name: app_id
        description: The application ID.
        in: path
        required: true
        schema:
          type: string
      security:
      - bearer_auth: []
      responses:
        '200':
          description: Rule list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/rule_response'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: App not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    post:
      summary: Creates a rule
      description: Creates a <a href="https://ably.com/docs/general/webhooks">rule</a> for the application with the specified application ID.
      tags:
      - rules
      parameters:
      - name: app_id
        description: The application ID.
        in: path
        required: true
        schema:
          type: string
      security:
      - bearer_auth: []
      responses:
        '201':
          description: Rule created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rule_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: App not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        description: The rule properties.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rule_post'
  /apps/{app_id}/rules/{rule_id}:
    get:
      summary: Gets a rule using a rule ID
      description: Returns the <a href="https://ably.com/docs/general/webhooks">rule</a> specified by the rule ID, for the application specified by application ID.
      tags:
      - rules
      parameters:
      - name: app_id
        description: The application ID.
        in: path
        required: true
        schema:
          type: string
      - name: rule_id
        description: The rule ID.
        in: path
        required: true
        schema:
          type: string
      security:
      - bearer_auth: []
      responses:
        '200':
          description: Rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rule_response'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    patch:
      summary: Updates a Rule
      description: Updates the <a href="https://ably.com/docs/general/webhooks">rule</a> specified by the rule ID, for the application specified by application ID.
      tags:
      - rules
      parameters:
      - name: app_id
        description: The application ID.
        in: path
        required: true
        schema:
          type: string
      - name: rule_id
        description: The rule ID.
        in: path
        required: true
        schema:
          type: string
      security:
      - bearer_auth: []
      responses:
        '200':
          description: Rule updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rule_response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: App not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        description: Properties for the rule.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rule_patch'
    delete:
      summary: Deletes a rule
      description: Deletes the <a href="https://ably.com/docs/general/webhooks">rule</a> specified by the rule ID, for the application specified by application ID.
      tags:
      - rules
      parameters:
      - name: app_id
        description: The application ID.
        in: path
        required: true
        schema:
          type: string
      - name: rule_id
        description: The rule ID.
        in: path
        required: true
        schema:
          type: string
      security:
      - bearer_auth: []
      responses:
        '204':
          description: Rule deleted
          content: {}
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: App not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    aws_lambda_rule_post:
      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:
          - aws/lambda
          description: The type of rule. In this case AWS Lambda. See the Ably <a href="https://ably.com/docs/general/integrations">integrations docs</a> for further information.
          example: aws/lambda
        requestMode:
          type: string
          description: Single request mode sends each event separately to the endpoint specified by the rule. You can read more about single request mode events in the <a href="https://ably.com/docs/general/webhooks#batching">batching docs</a>.
          example: single
        source:
          $ref: '#/components/schemas/rule_source'
        target:
          type: object
          additionalProperties: false
          properties:
            region:
              type: string
              description: The region is which your AWS Lambda Function is hosted. See the <a href="https://docs.aws.amazon.com/general/latest/gr/rande.html#lambda_region">AWS documentation</a> for more detail.
              example: us-west-1
            functionName:
              type: string
              description: The name of your AWS Lambda Function.
              example: myFunctionName
            authentication:
              oneOf:
              - $ref: '#/components/schemas/aws_access_keys'
              - $ref: '#/components/schemas/aws_assume_role'
              discriminator:
                propertyName: authenticationMode
                mapping:
                  credentials: '#/components/schemas/aws_access_keys'
                  assumeRole: '#/components/schemas/aws_assume_role'
            enveloped:
              type: boolean
              nullable: true
              description: Delivered messages are wrapped in an Ably envelope by default that contains metadata about the message and its payload. The form of the envelope depends on whether it is part of a Webhook/Function or a Queue/Firehose rule. For everything besides Webhooks, you can ensure you only get the raw payload by unchecking "Enveloped" when setting up the rule.
              example: true
          required:
          - region
          - functionName
          - authentication
      required:
      - ruleType
      - requestMode
      - source
      - target
    aws_access_keys_response:
      type: object
      additionalProperties: false
      properties:
        authenticationMode:
          type: string
          enum:
          - credentials
          description: Authentication method is using AWS credentials (AWS key ID and secret key).
          example: credentials
        accessKeyId:
          type: string
          description: The AWS key ID for the AWS IAM user. See the Ably <a href="https://ably.com/docs/general/aws-authentication/">AWS authentication docs</a> for details.
          example: AKIAIOSFODNN7EXAMPLE
    unsupported_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 <a href="https://ably.com/docs/general/webhooks">webhooks docs</a>.
          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: This rule type is currently unsupported.
          enum:
          - unsupported
          example: unsupported
        requestMode:
          type: string
          description: This is Single Request mode or Batch Request mode. Single Request mode sends each event separately to the endpoint specified by the rule. Batch Request mode rolls up multiple events into the same request. You can read more about the difference between single and batched events in the Ably <a href="https://ably.com/docs/general/webhooks#batching">batching docs</a>.
          example: single
        source:
          $ref: '#/components/schemas/rule_source'
        target:
          type: object
          additionalProperties: false
          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
    cloudflare_worker_rule_post:
      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:
          - http/cloudflare-worker
          description: The type of rule. In this case Cloudflare Worker. See the Ably <a href="https://ably.com/docs/general/integrations">integrations docs</a> for further information.
          example: http/cloudflare-worker
        requestMode:
          type: string
          description: This is Single Request mode or Batch Request mode. Single Request mode sends each event separately to the endpoint specified by the rule. Batch Request mode rolls up multiple events into the same request. You can read more about the difference between single and batched events in the Ably <a href="https://ably.com/docs/general/webhooks#batching">batching docs</a>.
          example: single
        source:
          $ref: '#/components/schemas/rule_source'
        target:
          type: object
          additionalProperties: false
          properties:
            url:
              type: string
              description: The webhook URL that Ably will POST events to.
              example: https://example.com/webhooks
            headers:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: The name of the header.
                    example: User-Agent
                  value:
                    type: string
                    description: The value of the header.
                    example: user-agent-string
              description: If you have additional information to send, you'll need to include the relevant headers.
              example:
              - name: User-Agent
                value: user-agent-string
              - name: headerName
                value: headerValue
            signingKeyId:
              type: string
              nullable: true
              description: The signing key ID for use in `batch` mode. Ably will optionally sign the payload using an API key ensuring your servers can validate the payload using the private API key. See the <a href="https://ably.com/docs/general/webhooks#security">webhooks security docs</a> for more information.
              example: bw66AB
          required:
          - url
      required:
      - ruleType
      - requestMode
      - source
      - target
    kafka_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 <a href="https://ably.com/docs/general/webhooks">webhooks docs</a>.
          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 Kafka (using Firehose). See the <a href="https://ably.com/docs/general/firehose">Firehose docs</a> for further information.
          enum:
          - kafka
        requestMode:
          type: string
          description: This is Single Request mode or Batch Request mode. Single Request mode sends each event separately to the endpoint specified by the rule. Batch Request mode rolls up multiple events into the same request. You can read more about the difference between single and batched events in the Ably <a href="https://ably.com/docs/general/webhooks#batching">batching docs</a>.
          example: single
        source:
          $ref: '#/components/schemas/rule_source'
        target:
          type: object
          additionalProperties: false
          properties:
            routingKey:
              type: string
              description: The Kafka partition key. This is used to determine which partition a message should be routed to, where a topic has been partitioned. `routingKey` should be in the format `topic:key` where `topic` is the topic to publish to, and `key` is the value to use as the message key.
              example: partitionKey
            brokers:
              type: array
              description: This is an array of brokers that host your Kafka partitions. Each broker is specified using the format `host`, `host:port` or `ip:port`.
              example:
              - kafka.ci.ably.io:19092
              - kafka.ci.ably.io:19093
              items:
                type: string
                example: kafka.ci.ably.io:19092
            auth:
              type: object
              description: The Kafka <a href="https://docs.confluent.io/platform/current/kafka/overview-authentication-methods.html">authentication mechanism</a>.
              additionalProperties: false
              properties:
                sasl:
                  type: object
                  description: SASL (Simple Authentication Security Layer) / SCRAM (Salted Challenge Response Authentication Mechanism) uses usernames and passwords stored in ZooKeeper. Credentials are created during installation. See documentation on <a href="https://docs.confluent.io/platform/current/kafka/authentication_sasl/authentication_sasl_scram.html#kafka-sasl-auth-scram">configuring SCRAM</a>.
                  additionalProperties: false
                  properties:
                    mechanism:
                      type: string
                      description: The hash type to use. SCRAM supports either SHA-256 or SHA-512 hash functions.
                      example: scram-sha-256
                      enum:
                      - plain
                      - scram-sha-256
                      - scram-sha-512
                    username:
                      type: string
                      description: Kafka login credential.
                      example: username
                    password:
                      type: string
                      description: Kafka login credential.
                      example: password
            enveloped:
              type: boolean
              nullable: true
              description: Delivered messages are wrapped in an Ably envelope by default that contains metadata about the message and its payload. The form of the envelope depends on whether it is part of a Webhook/Function or a Queue/Firehose rule. For everything besides Webhooks, you can ensure you only get the raw payload by unchecking "Enveloped" when setting up the rule.
              example: true
            format:
              type: string
              description: JSON provides a simpler text-based encoding, whereas MsgPack provides a more efficient binary encoding.
              example: json
          required:
          - routingKey
          - brokers
          - auth
      required:
      - ruleType
      - requestMode
      - source
      - target
    amqp_external_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 <a href="https://ably.com/docs/general/webhooks">webhooks docs</a>.
          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
          enum:
          - amqp/external
          description: The type of rule. In this case AMQP external (using Firehose). See the <a href="https://ably.com/docs/general/firehose">Firehose docs</a> for further information.
          example: amqp/external
        requestMode:
          type: string
          description: Single request mode sends each event separately to the endpoint specified by the rule. You can read more about single request mode events in the <a href="https://ably.com/docs/general/webhooks#batching">batching docs</a>.
          example: single
        source:
          $ref: '#/components/schemas/rule_source'
        target:
          type: object
          additionalProperties: false
          properties:
            url:
              type: string
              description: The webhook URL that Ably will POST events to.
              example: https://example.com/webhooks
            routingKey:
              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 <a href="https://faqs.ably.com/what-is-the-format-of-the-routingkey-for-an-amqp-or-kinesis-reactor-rule">Ably FAQs</a> for details.
              example: 'message name: #{message.name}, clientId: #{message.clientId}'
            mandatoryRoute:
              type: boolean
              description: Reject delivery of the message if the route does not exist, otherwise fail silently.
              example: true
            persistentMessages:
              type: boolean
              description: Marks the message as persistent, instructing the broker to write it to disk if it is in a durable queue.
              example: true
            messageTtl:
              type: integer
              description: You can optionally override the default TTL on a queue and specify a TTL in minutes for messages to be persisted. It is unusual to change the default TTL, so if this field is left empty, the default TTL for the queue will be used.
              example: 60
            headers:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: The name of the header.
                    example: User-Agent
                  value:
                    type: string
                    description: The value of the header.
                    example: user-agent-string
              description: If you have additional information to send, you'll need to include the relevant headers.
              example:
              - name: User-Agent
                value: user-agent-string
              - name: headerName
                value: headerValue
            enveloped:
              type: boolean
              nullable: true
              description: Delivered messages are wrapped in an Ably envelope by default that contains metadata about the message and its payload. The form of the envelope depends on whether it is part of a Webhook/Function or a Queue/Firehose rule. For everything besides Webhooks, you can ensure you only get the raw payload by unchecking "Enveloped" when setting up the rule.
              example: true
            format:
              type: string
              description: JSON provides a simpler text-based encoding, whereas MsgPack provides a more efficient binary encoding.
              example: json
          required:
          - url
          - routingKey
          - mandatoryRoute
          - persistentMessages
      required:
      - ruleType
      - requestMode
      - source
      - target
    pulsar_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 <a href="https://ably.com/docs/general/webhooks">webhooks docs</a>.
          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 Pulsar (using Firehose). See the <a href="https://ably.com/docs/general/firehose">Firehose docs</a> for further information.
          enum:
          - pulsar
        requestMode:
          type: string
          description: This is Single Request mode or Batch Request mode. Single Request mode sends each event separately to the endpoint specified by the rule. Batch Request mode rolls up multiple events into the same request. You can read more about the difference between single and batched events in the Ably <a href="https://ably.com/docs/general/webhooks#batching">batching docs</a>.
          example: single
        source:
          $ref: '#/components/schemas/rule_source'
        target:
          type: object
          additionalProperties: false
          properties:
            routingKey:
              type: string
              description: The optional routing key (partition key) used to publish messages. Supports interpolation as described in the <a href="https://faqs.ably.com/what-is-the-format-of-the-routingkey-for-an-amqp-or-kinesis-reactor-rule">Ably FAQs</a>.
              example: test-key
            topic:
              type: string
              description: 'A Pulsar topic. This is a named channel for transmission of messages between producers and consumers. The topic has the form: `{persistent|non-persistent}://tenant/namespace/topic`'
              example: persistent://my-tenant/my-namespace/my-topic
            serviceUrl:
              type: string
              description: The URL of the Pulsar cluster in the form `pulsar://host:port` or `pulsar+ssl://host:port`.
              example: pulsar://pulsar.us-west.example.com:6650/
            tlsTrustCerts:
              type: array
              description: All connections to a Pulsar endpoint require TLS. The `tlsTrustCerts` option allows you to configure different or additional trust anchors for those TLS connections. This enables server verification. You can specify an optional list of trusted CA certificates to use to verify the TLS certificate presented by the Pulsar cluster. Each certificate should be encoded in PEM format.
              items:
                type: string
                example: '-----BEGIN CERTIFICATE----- MIIFiTCCA3GgAwIBAgIUYO1Lomxzj7VRawWwEFiQht9OLpUwDQYJKoZIhvcNAQEL BQAwTDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE1pY2hpZ2FuMQ8wDQYDVQQHDAZX ...snip... TOfReTlUQzgpXRW5h3n2LVXbXQhPGcVitb88Cm2R8cxQwgB1VncM8yvmKhREo2tz 7Y+sUx6eIl4dlNl9kVrH1TD3EwwtGsjUNlFSZhg= -----END CERTIFICATE-----'
              nullable: true
            authentication:
              type: object
              description: Pulsar supports authenticating clients using security tokens that are based on JSON Web Tokens.
              oneOf:
              - $ref: '#/components/schemas/pulsar_token_auth'
              discriminator:
                propertyName: authenticationMode
                mapping:
                  token: '#/components/schemas/pulsar_token_auth'
            enveloped:
              type: boolean
              nullable: true
              description: Delivered messages are wrapped in an Ably envelope by default that contains metadata about the message and its payload. The form of the envelope depends on whether it is part of a Webhook/Function or a Queue/Firehose rule. For everything besides Webhooks, you can ensure you only get the raw payload by unchecking "Enveloped" when setting up the rule.
              example: true
            format:
              type: string
              description: JSON provides a simpler text-based encoding, whereas MsgPack provides a more efficient binary encoding.
              example: json
      required:
      - ruleType
      - requestMode
      - source
      - target
    amqp_rule_patch:
      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:
          - amqp
          description: The type of rule. In this case AMQP. See the Ably <a href="https://ably.com/docs/general/integrations">integrations docs</a> for further information.
          example: amqp
        requestMode:
          type: string
          description: Single request mode sends each event separately to the endpoint specified by the rule. You can read more about single request mode events in the <a href="https://ably.com/docs/general/webhooks#batching">batching docs</a>.
          example: single
        source:
          $ref: '#/components/schemas/rule_source_patch'
        target:
          type: object
          additionalProperties: false
          properties:
            queueId:
              type: string
            headers:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: The name of the header.
               

# --- truncated at 32 KB (161 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ably/refs/heads/main/openapi/ably-rules-api-openapi.yml