Knative Routes API

openapi: 3.1.0
info:
  title: Knative Eventing Apis Routes 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: Routes
  description: Knative Route resources manage the network endpoints and traffic distribution across Revisions. Routes support percentage-based traffic splitting for canary deployments and named route targets.
paths:
  /apis/serving.knative.dev/v1/namespaces/{namespace}/routes:
    get:
      operationId: listRoutes
      summary: List Knative Routes
      description: Returns a list of all Knative Route resources in the specified namespace. Routes map network endpoints to Revisions and manage percentage-based traffic distribution.
      tags:
      - Routes
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/continueToken'
      responses:
        '200':
          description: Successfully listed Routes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRoute
      summary: Create a Knative Route
      description: Creates a new Knative Route resource. Routes can distribute traffic across multiple Revisions using percentage-based splitting. Traffic percentages across all targets must sum to 100.
      tags:
      - Routes
      parameters:
      - $ref: '#/components/parameters/namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Route'
      responses:
        '201':
          description: Route successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apis/serving.knative.dev/v1/namespaces/{namespace}/routes/{name}:
    get:
      operationId: getRoute
      summary: Get a Knative Route
      description: Returns the details of a specific Knative Route including its traffic targets, URLs for named routes, and status conditions.
      tags:
      - Routes
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Successfully retrieved the Route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteRoute
      summary: Delete a Knative Route
      description: Deletes a Knative Route. Traffic to the associated URL will cease. Note that Routes owned by a Service are automatically deleted when the Service is deleted.
      tags:
      - Routes
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/name'
      responses:
        '200':
          description: Route deletion initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    TrafficTarget:
      type: object
      description: A traffic target that routes a percentage of traffic to a specific Revision or the latest ready Revision.
      properties:
        revisionName:
          type: string
          description: Specific Revision name to route traffic to. Mutually exclusive with configurationName.
        configurationName:
          type: string
          description: Configuration name to route traffic to the latest ready Revision of that Configuration.
        latestRevision:
          type: boolean
          description: Whether to route to the latest ready Revision. Mutually exclusive with revisionName.
        percent:
          type: integer
          minimum: 0
          maximum: 100
          description: Percentage of traffic to route to this target. All percentages must sum to 100.
        tag:
          type: string
          description: Optional name that creates a named subdomain URL for this traffic target.
        url:
          type: string
          format: uri
          description: Read-only URL for this traffic target. Set by Knative in status. Named tags receive a subdomain URL.
    Route:
      type: object
      description: A Knative Route that manages traffic distribution across Revisions. Routes map network endpoints to one or more Revisions and support percentage-based traffic splitting for progressive rollouts.
      required:
      - apiVersion
      - kind
      - metadata
      - spec
      properties:
        apiVersion:
          type: string
          const: serving.knative.dev/v1
          description: API version for the Knative Route.
        kind:
          type: string
          const: Route
          description: Resource kind identifier.
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          type: object
          description: Specification for the Route.
          properties:
            traffic:
              type: array
              description: Traffic targets for this Route. Percentages must sum to 100.
              items:
                $ref: '#/components/schemas/TrafficTarget'
        status:
          type: object
          description: Status of the Route.
          properties:
            url:
              type: string
              format: uri
              description: Primary URL assigned to this Route.
            conditions:
              type: array
              description: Status conditions for the Route.
              items:
                $ref: '#/components/schemas/Condition'
            traffic:
              type: array
              description: Observed traffic distribution.
              items:
                $ref: '#/components/schemas/TrafficTarget'
    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, including autoscaling configuration annotations.
          additionalProperties:
            type: string
        resourceVersion:
          type: string
          description: Opaque string identifying the resource version for optimistic concurrency.
        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.
        deletionTimestamp:
          type: string
          format: date-time
          description: Time after which the resource will be deleted.
        ownerReferences:
          type: array
          description: References to objects that own this resource.
          items:
            type: object
            properties:
              apiVersion:
                type: string
                description: API version of the owner.
              kind:
                type: string
                description: Kind of the owner.
              name:
                type: string
                description: Name of the owner.
              uid:
                type: string
                description: UID of the owner.
    RouteList:
      type: object
      description: A list of Knative Route resources.
      required:
      - apiVersion
      - kind
      - items
      properties:
        apiVersion:
          type: string
          description: API version for the list.
        kind:
          type: string
          const: RouteList
          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 Route resources.
          items:
            $ref: '#/components/schemas/Route'
    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 Active.
        status:
          type: string
          enum:
          - 'True'
          - 'False'
          - Unknown
          description: Status of the condition.
        reason:
          type: string
          description: Machine-readable reason for the last condition transition.
        message:
          type: string
          description: Human-readable message explaining the current condition.
        lastTransitionTime:
          type: string
          format: date-time
          description: Time of the last condition transition.
    Status:
      type: object
      description: Kubernetes API Status response for errors and operation results.
      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 of the status.
        reason:
          type: string
          description: Machine-readable reason, such as NotFound or AlreadyExists.
        code:
          type: integer
          description: HTTP status code.
  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
  responses:
    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'
  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/