Ably rules API

openapi: 3.2.0
info:
  title: Control API v1 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:
    amqp_external_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/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_patch'
        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.
            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
              - 'null'
              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
    http_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
          description: The type of rule. See the Ably <a href="https://ably.com/docs/general/integrations">integrations docs</a> for further information.
          example: http
        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
              - 'null'
              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">webhook security docs</a> for more information.
              example: bw66AB
            enveloped:
              type:
              - boolean
              - 'null'
              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
          - format
      required:
      - ruleType
      - requestMode
      - source
      - target
    http_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:
          - http
          description: The type of rule. See the Ably <a href="https://ably.com/docs/general/integrations">integrations docs</a> for further information.
          example: http
        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_patch'
        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
              - 'null'
              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">webhook security docs</a> for more information.
              example: bw66AB
            enveloped:
              type:
              - boolean
              - 'null'
              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
    http_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 Ably <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
          - 'null'
        ruleType:
          type: string
          enum:
          - http
          description: The type of rule. See the Ably <a href="https://ably.com/docs/general/integrations">integrations docs</a> for further information.
          example: http
        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
              - 'null'
              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
            enveloped:
              type:
              - boolean
              - 'null'
              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
          - format
      required:
      - ruleType
      - requestMode
      - source
      - target
    cloudflare_worker_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:
          - 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_patch'
        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
              - 'null'
              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:
      - ruleType
    aws_lambda_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:
          - 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_patch'
        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
              - 'null'
              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
    google_cloud_function_rule_post:
      type: object
      additionalProperties: false
      properties:
        ruleType:
          type: string
          enum:
          - http/google-cloud-function
          description: The type of rule. In this case Google Cloud Function. See the Ably <a href="https://ably.com/docs/general/integrations">integrations docs</a> for further information.
          example: http/google-cloud-function
        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:
            region:
              type: string
              description: The region in which your Google Cloud Function is hosted. See the <a href="https://cloud.google.com/compute/docs/regions-zones/">Google documentation</a> for more details.
              example: us-west1
            projectId:
              type: string
              description: The project ID for your Google Cloud Project that was generated when you created your project.
              example: my-sample-project-191923
            functionName:
              type: string
              description: The name of your Google Cloud Function.
              example: myFunctionName
            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
              - 'null'
              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
            enveloped:
              type:
              - boolean
              - 'null'
              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 text-based encoding.
              example: json
          required:
          - region
          - projectId
          - functionName
      required:
      - ruleType
      - requestMode
      - source
      - target
    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:

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