Ambassador Mappings API

openapi: 3.1.0
info:
  title: Ambassador Edge Stack Diagnostics Mappings API
  description: API for managing Ambassador Edge Stack resources in Kubernetes environments. Ambassador Edge Stack is a Kubernetes-native API gateway built on Envoy Proxy that provides routing, load balancing, authentication, rate limiting, and observability for microservices. This specification covers the management of core custom resource definitions (CRDs) including Mapping, Host, TLSContext, RateLimitService, and related configuration resources exposed through the Edge Stack management API.
  version: 3.x
  contact:
    name: Ambassador Labs
    url: https://www.getambassador.io
    email: support@datawire.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{ambassador-host}:8877
  description: Ambassador Edge Stack Admin API
  variables:
    ambassador-host:
      default: localhost
      description: Hostname or IP of the Ambassador Edge Stack admin interface
- url: https://{ambassador-host}/edge_stack/api
  description: Ambassador Edge Stack Management API
  variables:
    ambassador-host:
      default: localhost
      description: Hostname or IP of the Ambassador Edge Stack service
security:
- bearerAuth: []
tags:
- name: Mappings
  description: Manage Mapping resources that associate URL prefixes or paths with backend services. Mappings are the core routing mechanism in Ambassador.
  externalDocs:
    url: https://www.getambassador.io/docs/edge-stack/latest/topics/using/intro-mappings
paths:
  /apis/getambassador.io/v3alpha1/namespaces/{namespace}/mappings:
    get:
      operationId: listMappings
      summary: Ambassador List All Mappings in a Namespace
      description: Returns a list of all Mapping resources in the specified Kubernetes namespace. Mappings associate URL prefixes or exact paths with backend services and configure routing behavior.
      tags:
      - Mappings
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/LabelSelector'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Continue'
      responses:
        '200':
          description: Mapping list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingList'
              examples:
                Listmappings200Example:
                  summary: Default listMappings 200 response
                  x-microcks-default: true
                  value:
                    apiVersion: example_value
                    kind: example_value
                    metadata:
                      continue: example_value
                      resourceVersion: example_value
                    items:
                    - apiVersion: example_value
                      kind: example_value
        '401':
          description: Authentication required
        '403':
          description: Insufficient permissions
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createMapping
      summary: Ambassador Create a New Mapping
      description: Creates a new Mapping resource in the specified namespace. A Mapping defines how requests matching a URL prefix, path, or header should be routed to a backend service.
      tags:
      - Mappings
      parameters:
      - $ref: '#/components/parameters/Namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Mapping'
            examples:
              CreatemappingRequestExample:
                summary: Default createMapping request
                x-microcks-default: true
                value:
                  apiVersion: example_value
                  kind: example_value
                  metadata:
                    name: Example Title
                    namespace: example_value
                    labels: example_value
                    annotations: example_value
                    creationTimestamp: '2026-01-15T10:30:00Z'
                    generation: 10
                    resourceVersion: example_value
                    uid: '500123'
                  spec:
                    hostname: example_value
                    prefix: example_value
                    prefix_regex: true
                    prefix_exact: true
                    service: example_value
                    rewrite: example_value
                    method: GET
                    method_regex: true
                    headers: example_value
                    query_parameters: example_value
                    host: example_value
                    host_regex: true
                    timeout_ms: 10
                    idle_timeout_ms: 10
                    connect_timeout_ms: 10
                    cluster_idle_timeout_ms: 10
                    weight: 10
                    bypass_auth: true
                    circuit_breakers:
                    - {}
                    labels: example_value
                    add_request_headers: example_value
                    add_response_headers: example_value
                    remove_request_headers:
                    - {}
                    remove_response_headers:
                    - {}
                    allow_upgrade:
                    - {}
                    grpc: true
                    enable_ipv4: true
                    enable_ipv6: true
                    ambassador_id:
                    - {}
                  status:
                    state: Inactive
                    reason: example_value
      responses:
        '201':
          description: Mapping created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mapping'
              examples:
                Createmapping201Example:
                  summary: Default createMapping 201 response
                  x-microcks-default: true
                  value:
                    apiVersion: example_value
                    kind: example_value
                    metadata:
                      name: Example Title
                      namespace: example_value
                      labels: example_value
                      annotations: example_value
                      creationTimestamp: '2026-01-15T10:30:00Z'
                      generation: 10
                      resourceVersion: example_value
                      uid: '500123'
                    spec:
                      hostname: example_value
                      prefix: example_value
                      prefix_regex: true
                      prefix_exact: true
                      service: example_value
                      rewrite: example_value
                      method: GET
                      method_regex: true
                      headers: example_value
                      query_parameters: example_value
                      host: example_value
                      host_regex: true
                      timeout_ms: 10
                      idle_timeout_ms: 10
                      connect_timeout_ms: 10
                      cluster_idle_timeout_ms: 10
                      weight: 10
                      bypass_auth: true
                      circuit_breakers:
                      - {}
                      labels: example_value
                      add_request_headers: example_value
                      add_response_headers: example_value
                      remove_request_headers:
                      - {}
                      remove_response_headers:
                      - {}
                      allow_upgrade:
                      - {}
                      grpc: true
                      enable_ipv4: true
                      enable_ipv6: true
                      ambassador_id:
                      - {}
                    status:
                      state: Inactive
                      reason: example_value
        '400':
          description: Invalid Mapping specification
        '401':
          description: Authentication required
        '409':
          description: Mapping with this name already exists
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /apis/getambassador.io/v3alpha1/namespaces/{namespace}/mappings/{name}:
    get:
      operationId: getMapping
      summary: Ambassador Get a Specific Mapping
      description: Retrieves the full specification and status of a specific Mapping resource identified by name and namespace.
      tags:
      - Mappings
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/ResourceName'
      responses:
        '200':
          description: Mapping retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mapping'
              examples:
                Getmapping200Example:
                  summary: Default getMapping 200 response
                  x-microcks-default: true
                  value:
                    apiVersion: example_value
                    kind: example_value
                    metadata:
                      name: Example Title
                      namespace: example_value
                      labels: example_value
                      annotations: example_value
                      creationTimestamp: '2026-01-15T10:30:00Z'
                      generation: 10
                      resourceVersion: example_value
                      uid: '500123'
                    spec:
                      hostname: example_value
                      prefix: example_value
                      prefix_regex: true
                      prefix_exact: true
                      service: example_value
                      rewrite: example_value
                      method: GET
                      method_regex: true
                      headers: example_value
                      query_parameters: example_value
                      host: example_value
                      host_regex: true
                      timeout_ms: 10
                      idle_timeout_ms: 10
                      connect_timeout_ms: 10
                      cluster_idle_timeout_ms: 10
                      weight: 10
                      bypass_auth: true
                      circuit_breakers:
                      - {}
                      labels: example_value
                      add_request_headers: example_value
                      add_response_headers: example_value
                      remove_request_headers:
                      - {}
                      remove_response_headers:
                      - {}
                      allow_upgrade:
                      - {}
                      grpc: true
                      enable_ipv4: true
                      enable_ipv6: true
                      ambassador_id:
                      - {}
                    status:
                      state: Inactive
                      reason: example_value
        '401':
          description: Authentication required
        '404':
          description: Mapping not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateMapping
      summary: Ambassador Update a Mapping
      description: Replaces an existing Mapping resource with the provided specification. The full Mapping object must be provided.
      tags:
      - Mappings
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/ResourceName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Mapping'
            examples:
              UpdatemappingRequestExample:
                summary: Default updateMapping request
                x-microcks-default: true
                value:
                  apiVersion: example_value
                  kind: example_value
                  metadata:
                    name: Example Title
                    namespace: example_value
                    labels: example_value
                    annotations: example_value
                    creationTimestamp: '2026-01-15T10:30:00Z'
                    generation: 10
                    resourceVersion: example_value
                    uid: '500123'
                  spec:
                    hostname: example_value
                    prefix: example_value
                    prefix_regex: true
                    prefix_exact: true
                    service: example_value
                    rewrite: example_value
                    method: GET
                    method_regex: true
                    headers: example_value
                    query_parameters: example_value
                    host: example_value
                    host_regex: true
                    timeout_ms: 10
                    idle_timeout_ms: 10
                    connect_timeout_ms: 10
                    cluster_idle_timeout_ms: 10
                    weight: 10
                    bypass_auth: true
                    circuit_breakers:
                    - {}
                    labels: example_value
                    add_request_headers: example_value
                    add_response_headers: example_value
                    remove_request_headers:
                    - {}
                    remove_response_headers:
                    - {}
                    allow_upgrade:
                    - {}
                    grpc: true
                    enable_ipv4: true
                    enable_ipv6: true
                    ambassador_id:
                    - {}
                  status:
                    state: Inactive
                    reason: example_value
      responses:
        '200':
          description: Mapping updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mapping'
              examples:
                Updatemapping200Example:
                  summary: Default updateMapping 200 response
                  x-microcks-default: true
                  value:
                    apiVersion: example_value
                    kind: example_value
                    metadata:
                      name: Example Title
                      namespace: example_value
                      labels: example_value
                      annotations: example_value
                      creationTimestamp: '2026-01-15T10:30:00Z'
                      generation: 10
                      resourceVersion: example_value
                      uid: '500123'
                    spec:
                      hostname: example_value
                      prefix: example_value
                      prefix_regex: true
                      prefix_exact: true
                      service: example_value
                      rewrite: example_value
                      method: GET
                      method_regex: true
                      headers: example_value
                      query_parameters: example_value
                      host: example_value
                      host_regex: true
                      timeout_ms: 10
                      idle_timeout_ms: 10
                      connect_timeout_ms: 10
                      cluster_idle_timeout_ms: 10
                      weight: 10
                      bypass_auth: true
                      circuit_breakers:
                      - {}
                      labels: example_value
                      add_request_headers: example_value
                      add_response_headers: example_value
                      remove_request_headers:
                      - {}
                      remove_response_headers:
                      - {}
                      allow_upgrade:
                      - {}
                      grpc: true
                      enable_ipv4: true
                      enable_ipv6: true
                      ambassador_id:
                      - {}
                    status:
                      state: Inactive
                      reason: example_value
        '400':
          description: Invalid Mapping specification
        '401':
          description: Authentication required
        '404':
          description: Mapping not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteMapping
      summary: Ambassador Delete a Mapping
      description: Deletes a specific Mapping resource. Any traffic previously routed by this Mapping will no longer be handled.
      tags:
      - Mappings
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/ResourceName'
      responses:
        '200':
          description: Mapping deleted successfully
        '401':
          description: Authentication required
        '404':
          description: Mapping not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    CircuitBreaker:
      type: object
      description: Circuit breaker configuration for an upstream cluster
      properties:
        priority:
          type: string
          description: Envoy routing priority
          enum:
          - default
          - high
          example: default
        max_connections:
          type: integer
          description: Maximum number of connections to the upstream cluster
          minimum: 1
          example: 10
        max_pending_requests:
          type: integer
          description: Maximum number of pending requests to the upstream cluster
          minimum: 1
          example: 10
        max_requests:
          type: integer
          description: Maximum number of parallel requests to the upstream cluster
          minimum: 1
          example: 10
        max_retries:
          type: integer
          description: Maximum number of parallel retries to the upstream cluster
          minimum: 1
          example: 10
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata
      properties:
        name:
          type: string
          description: Name of the resource, unique within a namespace
          example: Example Title
        namespace:
          type: string
          description: Kubernetes namespace the resource belongs to
          example: example_value
        labels:
          type: object
          description: Key-value pairs for organizing and selecting resources
          additionalProperties:
            type: string
          example: example_value
        annotations:
          type: object
          description: Key-value pairs for storing arbitrary non-identifying metadata
          additionalProperties:
            type: string
          example: example_value
        creationTimestamp:
          type: string
          format: date-time
          description: Timestamp when the resource was created
          example: '2026-01-15T10:30:00Z'
        generation:
          type: integer
          description: Sequence number representing a specific generation of the resource
          example: 10
        resourceVersion:
          type: string
          description: Opaque value for optimistic concurrency control
          example: example_value
        uid:
          type: string
          description: Unique identifier for the resource
          example: '500123'
      required:
      - name
      - namespace
    MappingList:
      type: object
      description: List of Mapping resources
      properties:
        apiVersion:
          type: string
          const: getambassador.io/v3alpha1
          example: example_value
        kind:
          type: string
          const: MappingList
          example: example_value
        metadata:
          type: object
          properties:
            continue:
              type: string
              description: Continuation token for pagination
            resourceVersion:
              type: string
          example: example_value
        items:
          type: array
          description: List of Mapping resources
          items:
            $ref: '#/components/schemas/Mapping'
          example: []
    MappingSpec:
      type: object
      description: Specification for an Ambassador Mapping
      required:
      - hostname
      - prefix
      - service
      properties:
        hostname:
          type: string
          description: Hostname to match for this Mapping. Use '*' to match all hostnames.
          example: api.example.com
        prefix:
          type: string
          description: URL prefix to match for routing
          example: /api/v1/
        prefix_regex:
          type: boolean
          description: Whether the prefix should be interpreted as a regular expression
          default: false
          example: true
        prefix_exact:
          type: boolean
          description: Whether the prefix should be matched exactly rather than as a prefix
          default: false
          example: true
        service:
          type: string
          description: Target service to route to, in the format service-name.namespace:port or a full URL
          example: my-service.default:8080
        rewrite:
          type: string
          description: Prefix rewrite rule applied to the URL before forwarding to the backend service. Set to empty string to disable rewriting.
          example: /
        method:
          type: string
          description: HTTP method to match
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - PATCH
          - HEAD
          - OPTIONS
          example: GET
        method_regex:
          type: boolean
          description: Whether the method value is a regular expression
          default: false
          example: true
        headers:
          type: object
          description: HTTP headers that must be present on the request for this Mapping to match. Values can be exact strings or regular expressions.
          additionalProperties:
            type: string
          example: example_value
        query_parameters:
          type: object
          description: Query parameters that must be present for this Mapping to match
          additionalProperties:
            type: string
          example: example_value
        host:
          type: string
          description: Deprecated. Use hostname instead.
          deprecated: true
          example: example_value
        host_regex:
          type: boolean
          description: Deprecated. Whether host is a regular expression.
          deprecated: true
          example: true
        timeout_ms:
          type: integer
          description: Request timeout in milliseconds
          minimum: 0
          example: 30000
        idle_timeout_ms:
          type: integer
          description: Idle timeout for streaming connections in milliseconds
          minimum: 0
          example: 10
        connect_timeout_ms:
          type: integer
          description: Upstream connection timeout in milliseconds
          minimum: 0
          example: 10
        cluster_idle_timeout_ms:
          type: integer
          description: Idle timeout for upstream connections in the cluster in milliseconds
          minimum: 0
          example: 10
        weight:
          type: integer
          description: Weight for traffic splitting when multiple Mappings match the same prefix. Used in canary deployments.
          minimum: 0
          maximum: 100
          example: 10
        bypass_auth:
          type: boolean
          description: Whether to bypass the external authentication service for this Mapping
          default: false
          example: true
        cors:
          $ref: '#/components/schemas/CORSPolicy'
        retry_policy:
          $ref: '#/components/schemas/RetryPolicy'
        circuit_breakers:
          type: array
          description: Circuit breaker configurations for the upstream cluster
          items:
            $ref: '#/components/schemas/CircuitBreaker'
          example: []
        load_balancer:
          $ref: '#/components/schemas/LoadBalancer'
        labels:
          type: object
          description: Rate limiting labels to apply to requests matching this Mapping. Labels are sent to the rate limiting service for evaluation.
          additionalProperties: true
          example: example_value
        add_request_headers:
          type: object
          description: Headers to add to the request before forwarding to the upstream
          additionalProperties:
            type: string
          example: example_value
        add_response_headers:
          type: object
          description: Headers to add to the response before sending to the client
          additionalProperties:
            type: string
          example: example_value
        remove_request_headers:
          type: array
          description: Header names to remove from the request
          items:
            type: string
          example: []
        remove_response_headers:
          type: array
          description: Header names to remove from the response
          items:
            type: string
          example: []
        allow_upgrade:
          type: array
          description: Protocols to allow upgrade to, such as websocket
          items:
            type: string
          example:
          - websocket
        grpc:
          type: boolean
          description: Whether the upstream service uses gRPC
          default: false
          example: true
        enable_ipv4:
          type: boolean
          description: Whether to enable IPv4 DNS lookups for the upstream service
          example: true
        enable_ipv6:
          type: boolean
          description: Whether to enable IPv6 DNS lookups for the upstream service
          example: true
        ambassador_id:
          type: array
          description: List of Ambassador IDs that should apply this Mapping. Used to partition a single Kubernetes cluster among multiple Ambassador instances.
          items:
            type: string
          example: '500123'
    RetryPolicy:
      type: object
      description: Retry configuration for failed requests
      properties:
        retry_on:
          type: string
          description: Envoy retry condition. Common values include 5xx, gateway-error, connect-failure, retriable-4xx.
          example: 5xx
        num_retries:
          type: integer
          description: Maximum number of retry attempts
          minimum: 0
          example: 3
        per_try_timeout:
          type: string
          description: Timeout per retry attempt (e.g., '3s', '500ms')
          example: 3s
    LoadBalancer:
      type: object
      description: Load balancing configuration for an upstream cluster
      properties:
        policy:
          type: string
          description: Load balancing algorithm
          enum:
          - round_robin
          - least_request
          - ring_hash
          - maglev
          example: round_robin
        cookie:
          type: object
          description: Cookie-based session affinity configuration (for ring_hash policy)
          properties:
            name:
              type: string
              description: Name of the session affinity cookie
            ttl:
              type: string
              description: Time-to-live for the cookie
            path:
              type: string
              description: Cookie path
          example: example_value
        header:
          type: string
          description: Header to use for hash-based load balancing
          example: example_value
        source_ip:
          type: boolean
          description: Whether to use source IP for hash-based load balancing
          example: true
    Mapping:
      type: object
      description: An Ambassador Mapping resource that associates a URL prefix or path with a backend service. Mappings are the primary mechanism for configuring routing in Ambassador Edge Stack.
      required:
      - apiVersion
      - kind
      - metadata
      - spec
      properties:
        apiVersion:
          type: string
          description: API version for the Mapping resource
          const: getambassador.io/v3alpha1
          example: example_value
        kind:
          type: string
          description: Resource kind
          const: Mapping
          example: example_value
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/MappingSpec'
        status:
          $ref: '#/components/schemas/MappingStatus'
    MappingStatus:
      type: object
      description: Status information for a Mapping resource
      properties:
        state:
          type: string
          description: Current state of the Mapping
          enum:
          - Inactive
          - Running
          - Error
          example: Inactive
        reason:
          type: string
          description: Human-readable reason for the current state
          example: example_value
    CORSPolicy:
      type: object
      description: Cross-Origin Resource Sharing configuration
      properties:
        origins:
          type: array
          description: Allowed origins. Use a string for exact match or a regex pattern.
          items:
            type: string
          example:
          - https://example.com
          - https://*.example.com
        methods:
          type: array
          description: Allowed HTTP methods
          items:
            type: string
          example:
          - GET
          - POST
          - PUT
          - DELETE
        headers:
          type: array
          description: Allowed request headers
          items:
            type: string
          example: []
        credentials:
          type: boolean
          description: Whether to allow credentials (cookies, authorization headers)
          example: true
        exposed_headers:
          type: array
          description: Headers exposed to the browser
          items:
            type: string
          example: []
        max_age:
          type: string
          description: How long the preflight response can be cached (e.g., '86400')
          example: example_value
  parameters:
    Namespace:
      name: namespace
      in: path
      required: true
      description: Kubernetes namespace
      schema:
        type: string
      example: default
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of resources to return
      schema:
        type: integer
        minimum: 1
    ResourceName:
      name: name
      in: path
      required: true
      description: Name of the resource
      schema:
        type: string
    LabelSelector:
      name: labelSelector
      in: query
      required: false
      description: Kubernetes label selector to filter resources
      schema:
        type: string
      example: app=my-service
    Continue:
      name: continue
      in: query
      required: false
      description: Continuation token for paginated results
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Tokens are managed through the Ambassador Edge Stack management interface or Kubernetes service account tokens.
externalDocs:
  description: Ambassador Edge Stack Documentation
  url: https://www.getambassador.io/docs/edge-stack/latest/