CloudEvents Subscriptions API

openapi: 3.1.0
info:
  title: CloudEvents Subscriptions API
  description: The CloudEvents Subscriptions API provides a vendor-neutral REST interface for managing subscriptions to event streams. Clients can create, list, retrieve, update, and delete subscriptions with filter criteria that select which events to deliver and where to deliver them. The API enables consistent event delivery configuration across different event brokers, message buses, and cloud event services without lock-in to a specific provider's interface.
  version: '1.0'
  contact:
    name: CloudEvents Community
    url: https://cloudevents.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{broker-host}/subscriptions
  description: CloudEvents-compliant event broker subscriptions endpoint
  variables:
    broker-host:
      default: example.com
      description: Hostname of the CloudEvents-compatible event broker
tags:
- name: Subscriptions
  description: Operations for creating and managing event delivery subscriptions. Each subscription specifies a source of events, optional filter criteria, and a sink where matched events are delivered.
paths:
  /subscriptions:
    get:
      operationId: listSubscriptions
      summary: CloudEvents List subscriptions
      description: Returns a list of all subscriptions currently managed by this endpoint. Each subscription entry includes its identifier, sink, source, and current filter configuration. The response may be paginated for brokers with large numbers of subscriptions.
      tags:
      - Subscriptions
      responses:
        '200':
          description: List of subscriptions returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createSubscription
      summary: CloudEvents Create a subscription
      description: Creates a new subscription to an event stream. The request body specifies the sink (delivery endpoint), the source of events, optional event type filters, and protocol settings. Upon successful creation, the broker begins delivering matching events to the specified sink. The response returns the fully populated subscription object including its assigned identifier.
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
      responses:
        '201':
          description: Subscription created successfully
          headers:
            Location:
              description: URL of the newly created subscription
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /subscriptions/{id}:
    parameters:
    - $ref: '#/components/parameters/SubscriptionId'
    get:
      operationId: getSubscription
      summary: CloudEvents Get a subscription
      description: Returns the details of a specific subscription identified by its unique identifier. The response includes the current configuration including sink, source, filters, and any protocol settings. Returns 404 if the subscription does not exist or is not accessible to the caller.
      tags:
      - Subscriptions
      responses:
        '200':
          description: Subscription details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateSubscription
      summary: CloudEvents Update a subscription
      description: Replaces the configuration of an existing subscription. The entire subscription object must be provided; partial updates are not supported by this operation. Updating a subscription may temporarily interrupt event delivery while the new configuration takes effect.
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
      responses:
        '200':
          description: Subscription updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteSubscription
      summary: CloudEvents Delete a subscription
      description: Deletes an existing subscription. Once deleted, the broker stops delivering events to the subscription's sink. In-flight events at the time of deletion may or may not be delivered depending on broker implementation. Returns 404 if the subscription does not exist.
      tags:
      - Subscriptions
      responses:
        '200':
          description: Subscription deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ProtocolSettings:
      type: object
      description: Protocol-specific delivery settings for the subscription. The applicable properties depend on the 'protocol' field of the subscription.
      properties:
        contentMode:
          type: string
          description: CloudEvents content mode for HTTP delivery. 'structured' places all event data in the body; 'binary' maps attributes to headers.
          enum:
          - structured
          - binary
          default: structured
        headers:
          type: object
          description: Additional HTTP headers to include when delivering events over HTTP.
          additionalProperties:
            type: string
        method:
          type: string
          description: HTTP method to use when delivering events. Defaults to POST.
          default: POST
    Subscription:
      type: object
      description: A CloudEvents subscription describing an event stream source, delivery sink, and filter criteria. Once created, the broker delivers all matching events from the specified source to the sink endpoint.
      required:
      - id
      - sink
      - protocol
      properties:
        id:
          type: string
          description: Unique identifier for this subscription assigned by the broker. Immutable once set.
        sink:
          type: string
          format: uri
          description: The URL of the event consumer. Events matching the filter are delivered here using the protocol specified by the 'protocol' field.
        protocol:
          type: string
          description: The protocol used to deliver events to the sink, such as HTTP or AMQP. Must match a protocol the sink endpoint supports.
          enum:
          - HTTP
          - AMQP
          - MQTT
          - NATS
          - Kafka
        protocolSettings:
          $ref: '#/components/schemas/ProtocolSettings'
        source:
          type: string
          format: uri-reference
          description: Identifies the origin of events this subscription applies to. Matches the 'source' attribute of CloudEvents. If omitted, events from any source are eligible.
        types:
          type: array
          description: List of CloudEvent types this subscription is interested in. If omitted or empty, all event types from the source are delivered.
          items:
            type: string
        filters:
          type: array
          description: A list of filter expressions in CloudEvents CESQL or dialect format that further narrow which events are delivered. All filters must match for an event to be delivered.
          items:
            $ref: '#/components/schemas/Filter'
        config:
          type: object
          description: Additional implementation-specific configuration for the subscription. The properties accepted here are defined by the specific broker implementation.
          additionalProperties: true
    Filter:
      type: object
      description: A filter expression that constrains event delivery to events matching specific criteria. Filters can use attribute equality, CESQL expressions, or composite logic (all, any, not).
      properties:
        dialect:
          type: string
          description: Identifies the filter dialect. Use 'cesql' for CloudEvents SQL expressions, or 'exact'/'prefix'/'suffix' for simple attribute matching.
          enum:
          - cesql
          - exact
          - prefix
          - suffix
          - all
          - any
          - not
        expression:
          type: string
          description: The filter expression in the specified dialect. For CESQL, this is a SQL-like expression referencing CloudEvent attribute names.
        filters:
          type: array
          description: For composite filter dialects (all, any, not), the nested filters to evaluate.
          items:
            $ref: '#/components/schemas/Filter'
    SubscriptionRequest:
      type: object
      description: Request body for creating or updating a CloudEvents subscription. Specifies the sink, protocol, and optional filter criteria.
      required:
      - sink
      - protocol
      properties:
        sink:
          type: string
          format: uri
          description: The URL of the event consumer where matching events will be delivered.
        protocol:
          type: string
          description: The protocol to use when delivering events to the sink.
          enum:
          - HTTP
          - AMQP
          - MQTT
          - NATS
          - Kafka
        protocolSettings:
          $ref: '#/components/schemas/ProtocolSettings'
        source:
          type: string
          format: uri-reference
          description: Constrains the subscription to events from this source URI. If omitted, events from all sources are eligible for delivery.
        types:
          type: array
          description: List of CloudEvent types to subscribe to. Events with a 'type' attribute matching any entry in this list are eligible for delivery.
          items:
            type: string
        filters:
          type: array
          description: Additional filter expressions using CloudEvents filter dialects or CESQL to select which events are delivered.
          items:
            $ref: '#/components/schemas/Filter'
        config:
          type: object
          description: Additional broker-specific configuration properties for this subscription.
          additionalProperties: true
    Error:
      type: object
      description: Standard error response body returned for API failures.
      properties:
        code:
          type: integer
          description: HTTP status code of the error.
        message:
          type: string
          description: Human-readable error message describing what went wrong.
  responses:
    BadRequest:
      description: Invalid request body or parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Subscription not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Caller does not have permission to perform this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    SubscriptionId:
      name: id
      in: path
      required: true
      description: Unique identifier of the subscription
      schema:
        type: string
externalDocs:
  description: CloudEvents Subscriptions API Specification
  url: https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md