openapi: 3.1.0
info:
  title: kgateway Kubernetes Gateway AIBackend TrafficPolicy API
  description: kgateway is the most widely deployed gateway in Kubernetes for microservices and AI agents. It is a feature-rich, fast, and flexible Kubernetes-native ingress controller and next-generation API gateway built on top of Envoy proxy and the Kubernetes Gateway API. kgateway provides custom resource definitions (CRDs) under the gateway.kgateway.dev API group for configuring traffic policies, backends, direct responses, gateway extensions, gateway parameters, HTTP listener policies, and AI backends. These resources are managed through the Kubernetes API server.
  version: 2.1.0
  contact:
    name: kgateway
    url: https://kgateway.dev
  license:
    name: Apache 2.0
    url: https://github.com/kgateway-dev/kgateway/blob/main/LICENSE
servers:
- url: https://{kubernetes-api-server}/apis/gateway.kgateway.dev/v1alpha1
  description: Kubernetes API Server - kgateway Custom Resources
  variables:
    kubernetes-api-server:
      default: kubernetes.default.svc
      description: The Kubernetes API server hostname
security:
- BearerAuth: []
tags:
- name: TrafficPolicy
  description: Attach traffic management policies to routes in an HTTPRoute resource or all routes served by a Gateway. Supports CORS, external auth, external processing, rate limiting, timeouts, retries, transformations, and header modifiers.
paths:
  /namespaces/{namespace}/trafficpolicies:
    get:
      operationId: listTrafficPolicies
      summary: Kgateway List TrafficPolicy resources
      description: List all TrafficPolicy resources in the specified namespace.
      tags:
      - TrafficPolicy
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/LabelSelector'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Continue'
      responses:
        '200':
          description: Successfully retrieved list of TrafficPolicy resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrafficPolicyList'
        '401':
          description: Unauthorized
    post:
      operationId: createTrafficPolicy
      summary: Kgateway Create a TrafficPolicy
      description: Create a TrafficPolicy resource to attach traffic management policies to routes in an HTTPRoute resource.
      tags:
      - TrafficPolicy
      parameters:
      - $ref: '#/components/parameters/Namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrafficPolicy'
      responses:
        '201':
          description: Successfully created TrafficPolicy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrafficPolicy'
        '401':
          description: Unauthorized
        '409':
          description: Conflict - resource already exists
  /namespaces/{namespace}/trafficpolicies/{name}:
    get:
      operationId: getTrafficPolicy
      summary: Kgateway Get a TrafficPolicy
      description: Retrieve a specific TrafficPolicy resource by name and namespace.
      tags:
      - TrafficPolicy
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/Name'
      responses:
        '200':
          description: Successfully retrieved TrafficPolicy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrafficPolicy'
        '401':
          description: Unauthorized
        '404':
          description: TrafficPolicy not found
    put:
      operationId: replaceTrafficPolicy
      summary: Kgateway Replace a TrafficPolicy
      description: Replace a specific TrafficPolicy resource.
      tags:
      - TrafficPolicy
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/Name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrafficPolicy'
      responses:
        '200':
          description: Successfully replaced TrafficPolicy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrafficPolicy'
        '401':
          description: Unauthorized
        '404':
          description: TrafficPolicy not found
    delete:
      operationId: deleteTrafficPolicy
      summary: Kgateway Delete a TrafficPolicy
      description: Delete a specific TrafficPolicy resource.
      tags:
      - TrafficPolicy
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/Name'
      responses:
        '200':
          description: Successfully deleted TrafficPolicy.
        '401':
          description: Unauthorized
        '404':
          description: TrafficPolicy not found
components:
  parameters:
    Name:
      name: name
      in: path
      required: true
      description: The name of the resource.
      schema:
        type: string
    Namespace:
      name: namespace
      in: path
      required: true
      description: The Kubernetes namespace.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of resources to return.
      schema:
        type: integer
    Continue:
      name: continue
      in: query
      required: false
      description: Continue token for paginated list requests.
      schema:
        type: string
    LabelSelector:
      name: labelSelector
      in: query
      required: false
      description: A selector to restrict the list of returned objects by labels.
      schema:
        type: string
  schemas:
    TrafficPolicyList:
      type: object
      description: List of TrafficPolicy resources.
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          enum:
          - TrafficPolicyList
        metadata:
          type: object
          properties:
            continue:
              type: string
            resourceVersion:
              type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/TrafficPolicy'
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata.
      properties:
        name:
          type: string
          description: Name of the resource.
        namespace:
          type: string
          description: Namespace of the resource.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Map of string keys and values for organizing resources.
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Annotations for storing arbitrary metadata.
        resourceVersion:
          type: string
          description: An opaque value that represents the internal version of this object.
        creationTimestamp:
          type: string
          format: date-time
          description: Timestamp representing the server time when this object was created.
    TrafficPolicy:
      type: object
      description: TrafficPolicy attaches traffic management policies to routes in an HTTPRoute or all routes served by a Gateway.
      properties:
        apiVersion:
          type: string
          enum:
          - gateway.kgateway.dev/v1alpha1
        kind:
          type: string
          enum:
          - TrafficPolicy
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          type: object
          description: TrafficPolicySpec defines the desired state of a TrafficPolicy.
          properties:
            targetRefs:
              type: array
              description: References to the target resources to which this policy applies.
              items:
                $ref: '#/components/schemas/PolicyTargetRef'
            cors:
              type: object
              description: CORS policy configuration.
              properties:
                allowOrigins:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - Exact
                        - Prefix
                        - Regex
                      value:
                        type: string
                allowMethods:
                  type: array
                  items:
                    type: string
                allowHeaders:
                  type: array
                  items:
                    type: string
                exposeHeaders:
                  type: array
                  items:
                    type: string
                maxAge:
                  type: string
                  description: Maximum time a preflight request can be cached.
                allowCredentials:
                  type: boolean
            extAuth:
              type: object
              description: External authentication configuration.
              properties:
                extensionRef:
                  type: object
                  description: Reference to a GatewayExtension for external auth.
                  properties:
                    name:
                      type: string
                    namespace:
                      type: string
                disable:
                  type: boolean
                  description: Disable external auth for this route.
            extProc:
              type: object
              description: External processing configuration.
              properties:
                extensionRef:
                  type: object
                  properties:
                    name:
                      type: string
                    namespace:
                      type: string
                disable:
                  type: boolean
                  description: Disable external processing for this route.
            rateLimit:
              type: object
              description: Rate limiting configuration.
              properties:
                extensionRef:
                  type: object
                  properties:
                    name:
                      type: string
                    namespace:
                      type: string
                disable:
                  type: boolean
            timeout:
              type: object
              description: Timeout configuration for requests.
              properties:
                request:
                  type: string
                  description: Maximum duration for the entire request. Uses Go duration format (e.g., 30s, 1m).
                idle:
                  type: string
                  description: Maximum duration for idle connections.
            retries:
              type: object
              description: Retry configuration for failed requests.
              properties:
                attempts:
                  type: integer
                  description: Maximum number of retry attempts.
                perTryTimeout:
                  type: string
                  description: Timeout per retry attempt.
                backOff:
                  type: object
                  properties:
                    baseInterval:
                      type: string
                    maxInterval:
                      type: string
                retryOn:
                  type: string
                  description: Conditions for retry, comma-separated (e.g., connect-failure,refused-stream,5xx).
            requestHeaderModifier:
              type: object
              description: Modify request headers.
              properties:
                set:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                add:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                remove:
                  type: array
                  items:
                    type: string
            responseHeaderModifier:
              type: object
              description: Modify response headers.
              properties:
                set:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                add:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                remove:
                  type: array
                  items:
                    type: string
          required:
          - targetRefs
        status:
          type: object
          description: Status of the TrafficPolicy.
          properties:
            conditions:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  status:
                    type: string
                    enum:
                    - 'True'
                    - 'False'
                    - Unknown
                  reason:
                    type: string
                  message:
                    type: string
                  lastTransitionTime:
                    type: string
                    format: date-time
    PolicyTargetRef:
      type: object
      description: Reference to a target resource for policy attachment.
      properties:
        group:
          type: string
          description: Group is the group of the target resource.
          default: gateway.networking.k8s.io
        kind:
          type: string
          description: Kind is the kind of the target resource.
          enum:
          - Gateway
          - HTTPRoute
        name:
          type: string
          description: Name is the name of the target resource.
        namespace:
          type: string
          description: Namespace is the namespace of the target resource.
        sectionName:
          type: string
          description: SectionName is the name of a section within the target resource to apply the policy to.
      required:
      - kind
      - name
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Kubernetes API bearer token authentication. Use a service account token or kubeconfig token.
externalDocs:
  description: kgateway API Reference Documentation
  url: https://kgateway.dev/docs/envoy/latest/reference/api/