Knative Subscriptions API

openapi: 3.1.0
info:
  title: Knative Eventing Apis Subscriptions 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: Subscriptions
  description: Knative Subscription resources define a delivery destination for events sent to a Channel. Each Subscription routes events from a Channel to a subscriber destination with optional reply and dead-letter handling.
paths:
  /apis/messaging.knative.dev/v1/namespaces/{namespace}/subscriptions:
    get:
      operationId: listSubscriptions
      summary: Knative List Subscriptions
      description: Returns a list of all Subscription resources in the specified namespace. Subscriptions route events from a Channel to a subscriber destination with optional reply and dead-letter sink configuration.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/continueToken'
      responses:
        '200':
          description: Successfully listed Subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSubscription
      summary: Knative Create a Subscription
      description: Creates a new Subscription to a Channel. Events received by the Channel are independently delivered to each Subscription's subscriber destination. Reply events from the subscriber can be forwarded to another destination.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '201':
          description: Subscription successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
  /apis/messaging.knative.dev/v1/namespaces/{namespace}/subscriptions/{name}:
    get:
      operationId: getSubscription
      summary: Knative Get a Subscription
      description: Returns details of a specific Subscription including its Channel reference, subscriber destination, reply destination, and dead-letter sink configuration.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Successfully retrieved the Subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteSubscription
      summary: Knative Delete a Subscription
      description: Deletes a Subscription. The subscriber destination will stop receiving events from the associated Channel.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Subscription deletion initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Subscription:
      type: object
      description: A Knative Subscription that routes events from a Channel to a subscriber destination. Each Subscription maintains its own delivery state independently of other Subscriptions on the same Channel.
      required:
      - apiVersion
      - kind
      - metadata
      - spec
      properties:
        apiVersion:
          type: string
          const: messaging.knative.dev/v1
          description: API version for the Subscription.
        kind:
          type: string
          const: Subscription
          description: Resource kind identifier.
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          type: object
          description: Specification for the Subscription.
          required:
          - channel
          properties:
            channel:
              type: object
              description: Reference to the Channel to subscribe to.
              required:
              - name
              properties:
                apiVersion:
                  type: string
                  description: API version of the Channel.
                kind:
                  type: string
                  description: Kind of the Channel resource.
                name:
                  type: string
                  description: Name of the Channel.
            subscriber:
              $ref: '#/components/schemas/Destination'
            reply:
              $ref: '#/components/schemas/Destination'
            delivery:
              $ref: '#/components/schemas/DeliverySpec'
        status:
          type: object
          description: Status of the Subscription.
          properties:
            physicalSubscription:
              type: object
              description: Resolved physical subscription details set by the controller.
              properties:
                subscriberUri:
                  type: string
                  format: uri
                  description: Resolved subscriber URI.
                replyUri:
                  type: string
                  format: uri
                  description: Resolved reply URI.
                deadLetterSinkUri:
                  type: string
                  format: uri
                  description: Resolved dead-letter sink URI.
            conditions:
              type: array
              description: Status conditions for the Subscription.
              items:
                $ref: '#/components/schemas/Condition'
    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.
    SubscriptionList:
      type: object
      description: A list of Subscription resources.
      required:
      - apiVersion
      - kind
      - items
      properties:
        apiVersion:
          type: string
          description: API version for the list.
        kind:
          type: string
          const: SubscriptionList
          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 Subscription resources.
          items:
            $ref: '#/components/schemas/Subscription'
    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.
    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.
  responses:
    Conflict:
      description: A resource with this name already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
  parameters:
    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
    continueToken:
      name: continue
      in: query
      required: false
      description: Pagination token returned by a previous list call.
      schema:
        type: string
    labelSelector:
      name: labelSelector
      in: query
      required: false
      description: Selector to filter resources by label key-value pairs.
      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
  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/