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
externalDocs:
  description: CloudEvents Subscriptions API Specification
  url: https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md
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:
  parameters:
    SubscriptionId:
      name: id
      in: path
      required: true
      description: Unique identifier of the subscription
      schema:
        type: string
  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'
    Forbidden:
      description: Caller does not have permission to perform this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Subscription not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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
    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
    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
    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'
    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.