Knative Brokers API

openapi: 3.2.0
info:
  title: Knative Eventing Brokers API
  description: 'The Knative Eventing API extends Kubernetes with custom resources for building event-driven architectures. It provides two main patterns: Broker and Trigger for cloud-native event routing with filtering, and Channel and Subscription for pub/sub messaging. Event sources such as ApiServerSource, PingSource, and SinkBinding connect external event producers to the eventing mesh. All events conform to the CloudEvents specification. Resources are served through the Kubernetes API server under the eventing.knative.dev and messaging.knative.dev API groups.'
  version: '1.0'
  contact:
    name: Knative Community
    url: https://knative.dev/community/
servers:
- url: https://kubernetes.default.svc
  description: Kubernetes API Server (in-cluster)
security:
- bearerAuth: []
tags:
- name: Brokers
  description: Knative Broker resources collect pools of events that can be consumed using Triggers. Brokers provide event routing with filtering, guaranteed delivery, and dead-letter sink support. The default broker implementation uses an in-memory channel.
paths:
  /apis/eventing.knative.dev/v1/namespaces/{namespace}/brokers:
    get:
      operationId: listBrokers
      summary: Knative List Brokers
      description: Returns a list of all Broker resources in the specified namespace. Brokers act as event ingestion points and route events to matching Triggers based on CloudEvent attribute filters.
      tags:
      - Brokers
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/continueToken'
      responses:
        '200':
          description: Successfully listed Brokers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrokerList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBroker
      summary: Knative Create a Broker
      description: Creates a new Broker resource. Brokers collect events sent to them and deliver events to all Triggers associated with the Broker whose filters match the event. Optionally configure delivery settings for dead-letter sinks and retry policies.
      tags:
      - Brokers
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Broker'
      responses:
        '201':
          description: Broker successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Broker'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
  /apis/eventing.knative.dev/v1/namespaces/{namespace}/brokers/{name}:
    get:
      operationId: getBroker
      summary: Knative Get a Broker
      description: Returns details of a specific Broker resource including its delivery configuration and status conditions reflecting whether it is Ready and its ingress address.
      tags:
      - Brokers
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Successfully retrieved the Broker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Broker'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteBroker
      summary: Knative Delete a Broker
      description: Deletes a Broker. All associated Triggers must be deleted first or they will fail to find their target Broker. In-flight events may be lost upon deletion.
      tags:
      - Brokers
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Broker deletion initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DeliverySpec:
      type: object
      description: Delivery configuration for event sources and Brokers.
      properties:
        deadLetterSink:
          $ref: '#/components/schemas/Destination'
          description: Destination for events that cannot be delivered after retries.
        retry:
          type: integer
          minimum: 0
          description: Minimum number of retries before sending to the dead-letter sink.
        backoffPolicy:
          type: string
          enum:
          - linear
          - exponential
          description: Backoff policy for retries.
        backoffDelay:
          type: string
          description: Delay between retries in ISO 8601 duration format, for example PT2S.
        timeout:
          type: string
          description: Timeout per delivery attempt in ISO 8601 duration format.
    Broker:
      type: object
      description: A Knative Broker that collects a pool of events and routes them to matching Triggers. Brokers provide event filtering, guaranteed delivery, and dead-letter sink support conforming to the CloudEvents specification.
      required:
      - apiVersion
      - kind
      - metadata
      properties:
        apiVersion:
          type: string
          const: eventing.knative.dev/v1
          description: API version for the Broker.
        kind:
          type: string
          const: Broker
          description: Resource kind identifier.
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          type: object
          description: Specification for the Broker.
          properties:
            config:
              type: object
              description: Reference to a ConfigMap that configures the Broker implementation.
              properties:
                apiVersion:
                  type: string
                  description: API version of the configuration resource.
                kind:
                  type: string
                  description: Kind of the configuration resource.
                name:
                  type: string
                  description: Name of the configuration resource.
                namespace:
                  type: string
                  description: Namespace of the configuration resource.
            delivery:
              $ref: '#/components/schemas/DeliverySpec'
        status:
          type: object
          description: Status of the Broker.
          properties:
            address:
              type: object
              description: URL to which events should be sent for this Broker.
              properties:
                url:
                  type: string
                  format: uri
                  description: Addressable URL for the Broker ingress.
            conditions:
              type: array
              description: Status conditions for the Broker.
              items:
                $ref: '#/components/schemas/Condition'
    Condition:
      type: object
      description: A status condition on a Knative resource.
      required:
      - type
      - status
      properties:
        type:
          type: string
          description: Type of condition such as Ready or Addressable.
        status:
          type: string
          enum:
          - 'True'
          - 'False'
          - Unknown
          description: Status of the condition.
        reason:
          type: string
          description: Machine-readable reason for the last transition.
        message:
          type: string
          description: Human-readable message for the condition.
        lastTransitionTime:
          type: string
          format: date-time
          description: Time of the last condition transition.
    Status:
      type: object
      description: Kubernetes API Status response.
      properties:
        apiVersion:
          type: string
          description: API version of the Status object.
        kind:
          type: string
          const: Status
          description: Always Status.
        status:
          type: string
          description: Success or Failure.
        message:
          type: string
          description: Human-readable description.
        reason:
          type: string
          description: Machine-readable reason.
        code:
          type: integer
          description: HTTP status code.
    BrokerList:
      type: object
      description: A list of Broker resources.
      required:
      - apiVersion
      - kind
      - items
      properties:
        apiVersion:
          type: string
          description: API version for the list.
        kind:
          type: string
          const: BrokerList
          description: List kind identifier.
        metadata:
          type: object
          properties:
            resourceVersion:
              type: string
              description: Resource version of the list.
            continue:
              type: string
              description: Pagination continuation token.
        items:
          type: array
          description: List of Broker resources.
          items:
            $ref: '#/components/schemas/Broker'
    Destination:
      type: object
      description: A destination for delivering CloudEvents. Can reference a Kubernetes service, a Knative Service, a Broker, or a Channel via ref, or specify a direct URI.
      properties:
        ref:
          type: object
          description: Reference to a Kubernetes resource that is a destination.
          required:
          - apiVersion
          - kind
          - name
          properties:
            apiVersion:
              type: string
              description: API version of the destination resource.
            kind:
              type: string
              description: Kind of the destination resource.
            name:
              type: string
              description: Name of the destination resource.
            namespace:
              type: string
              description: Namespace of the destination resource.
        uri:
          type: string
          format: uri
          description: Direct URI to deliver events to. Mutually exclusive with ref.
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata.
      required:
      - name
      properties:
        name:
          type: string
          description: Unique name of the resource within its namespace.
        namespace:
          type: string
          description: Namespace the resource belongs to.
        labels:
          type: object
          description: Key-value labels for organizing and selecting resources.
          additionalProperties:
            type: string
        annotations:
          type: object
          description: Non-identifying metadata for the resource.
          additionalProperties:
            type: string
        resourceVersion:
          type: string
          description: Opaque string identifying the resource version.
        uid:
          type: string
          description: Unique identifier assigned by the API server.
        generation:
          type: integer
          description: Sequence number incremented on each spec change.
        creationTimestamp:
          type: string
          format: date-time
          description: Time the resource was created.
  parameters:
    continueToken:
      name: continue
      in: query
      required: false
      description: Pagination token returned by a previous list call.
      schema:
        type: string
    name:
      name: name
      in: path
      required: true
      description: Name of the Knative resource.
      schema:
        type: string
    namespace:
      name: namespace
      in: path
      required: true
      description: Kubernetes namespace containing the resource.
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return in a single response.
      schema:
        type: integer
        minimum: 1
    labelSelector:
      name: labelSelector
      in: query
      required: false
      description: Selector to filter resources by label key-value pairs.
      schema:
        type: string
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    Conflict:
      description: A resource with this name already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Kubernetes service account token or user bearer token. RBAC policies control access to Knative Eventing resources.
externalDocs:
  description: Knative Eventing API Reference
  url: https://knative.dev/docs/eventing/reference/eventing-api/