Ambassador Edge Stack API Gateway

openapi: 3.1.0
info:
  title: Ambassador Edge Stack 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: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: Ambassador Edge Stack Documentation
  url: https://www.getambassador.io/docs/edge-stack/latest/
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
tags:
- name: Diagnostics
  description: >-
    Access diagnostic and health check endpoints for monitoring Ambassador
    Edge Stack operational status.
- name: Hosts
  description: >-
    Manage Host resources that configure TLS termination, ACME certificate
    management, and hostname-based routing rules.
  externalDocs:
    url: https://www.getambassador.io/docs/edge-stack/latest/topics/running/host-crd
- 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
- name: Modules
  description: >-
    Manage Ambassador Module resources for global configuration of the
    Ambassador gateway including diagnostics, tracing, and circuit breaking.
- name: RateLimits
  description: >-
    Manage rate limiting configuration for controlling request throughput
    to backend services using labels and descriptors.
  externalDocs:
    url: https://www.getambassador.io/docs/edge-stack/latest/topics/using/rate-limits
- name: TLSContexts
  description: >-
    Manage TLSContext resources that configure TLS settings for Ambassador,
    including certificates, protocols, and cipher suites.
  externalDocs:
    url: https://www.getambassador.io/docs/edge-stack/latest/topics/running/tls/
security:
- bearerAuth: []
paths:
  /ambassador/v0/diag:
    get:
      operationId: getDiagnostics
      summary: Ambassador Retrieve Diagnostic Overview
      description: >-
        Returns a comprehensive diagnostic overview of the Ambassador instance
        including active configuration, cluster state, Envoy status, and any
        configuration errors or warnings.
      tags:
      - Diagnostics
      responses:
        '200':
          description: Diagnostic information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticsOverview'
              examples:
                Getdiagnostics200Example:
                  summary: Default getDiagnostics 200 response
                  x-microcks-default: true
                  value:
                    system:
                      version: example_value
                      hostname: example_value
                      ambassador_id: '500123'
                      cluster_id: '500123'
                      boot_time: '2026-01-15T10:30:00Z'
                    ambassador_config: example_value
                    envoy_status:
                      alive: true
                      ready: true
                      uptime: 10
                    route_info:
                    - prefix: example_value
                      service: example_value
                      weight: 10
                    errors:
                    - kind: example_value
                      name: Example Title
                      namespace: example_value
                      error: example_value
        '401':
          description: Authentication required
        '503':
          description: Ambassador not ready
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ambassador/v0/check_ready:
    get:
      operationId: checkReady
      summary: Ambassador Readiness Health Check
      description: >-
        Returns whether Ambassador is ready to serve traffic. Used by
        Kubernetes readiness probes.
      tags:
      - Diagnostics
      security: []
      responses:
        '200':
          description: Ambassador is ready
        '503':
          description: Ambassador is not ready
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ambassador/v0/check_alive:
    get:
      operationId: checkAlive
      summary: Ambassador Liveness Health Check
      description: >-
        Returns whether the Ambassador process is alive. Used by Kubernetes
        liveness probes.
      tags:
      - Diagnostics
      security: []
      responses:
        '200':
          description: Ambassador is alive
        '503':
          description: Ambassador is not alive
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
  /apis/getambassador.io/v3alpha1/namespaces/{namespace}/hosts:
    get:
      operationId: listHosts
      summary: Ambassador List All Hosts in a Namespace
      description: >-
        Returns a list of all Host resources in the specified namespace. Hosts
        define how Ambassador should handle requests for specific hostnames,
        including TLS termination and ACME certificate provisioning.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/LabelSelector'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Continue'
      responses:
        '200':
          description: Host list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostList'
              examples:
                Listhosts200Example:
                  summary: Default listHosts 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: createHost
      summary: Ambassador Create a New Host
      description: >-
        Creates a new Host resource in the specified namespace. A Host defines
        hostname routing, TLS termination behavior, and optionally configures
        ACME-based automatic certificate management.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/Namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Host'
            examples:
              CreatehostRequestExample:
                summary: Default createHost 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
                    ambassador_id:
                    - {}
                    acmeProvider:
                      authority: example_value
                      email: [email protected]
                      privateKeySecret: {}
                      registration: example_value
                    tlsContext:
                      name: Example Title
                    tlsSecret:
                      name: Example Title
                    requestPolicy:
                      insecure: {}
                    selector:
                      matchLabels: example_value
                  status:
                    state: Initial
                    phaseCompleted: NA
                    errorReason: example_value
                    tlsCertificateSource: None
      responses:
        '201':
          description: Host created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
              examples:
                Createhost201Example:
                  summary: Default createHost 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
                      ambassador_id:
                      - {}
                      acmeProvider:
                        authority: example_value
                        email: [email protected]
                        privateKeySecret: {}
                        registration: example_value
                      tlsContext:
                        name: Example Title
                      tlsSecret:
                        name: Example Title
                      requestPolicy:
                        insecure: {}
                      selector:
                        matchLabels: example_value
                    status:
                      state: Initial
                      phaseCompleted: NA
                      errorReason: example_value
                      tlsCertificateSource: None
        '400':
          description: Invalid Host specification
        '401':
          description: Authentication required
        '409':
          description: Host with this name already exists
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /apis/getambassador.io/v3alpha1/namespaces/{namespace}/hosts/{name}:
    get:
      operationId: getHost
      summary: Ambassador Get a Specific Host
      description: >-
        Retrieves the specification and status of a specific Host resource.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/ResourceName'
      responses:
        '200':
          description: Host retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
              examples:
                Gethost200Example:
                  summary: Default getHost 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
                      ambassador_id:
                      - {}
                      acmeProvider:
                        authority: example_value
                        email: [email protected]
                        privateKeySecret: {}
                        registration: example_value
                      tlsContext:
                        name: Example Title
                      tlsSecret:
                        name: Example Title
                      requestPolicy:
                        insecure: {}
                      selector:
                        matchLabels: example_value
                    status:
                      state: Initial
                      phaseCompleted: NA
                      errorReason: example_value
                      tlsCertificateSource: None
        '401':
          description: Authentication required
        '404':
          description: Host not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateHost
      summary: Ambassador Update a Host
      description: >-
        Replaces an existing Host resource with the provided specification.
      tags:
      - Hosts
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/ResourceName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Host'
            examples:
              UpdatehostRequestExample:
                summary: Default updateHost 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
                    ambassador_id:
                    - {}
                    acmeProvider:
                      authority: example_value
                      email: [email protected]
                      privateKeySecret: {}
                      registration: example_value
                    tlsContext:
                      name: Example Title
                    tlsSecret:
                      name: Example Title
                    requestPolicy:
                      insecure: {}
                    selector:
                      matchLabels: example_value
                  status:
                    state: Initial
                    phaseCompleted: NA
                    errorReason: example_value
                    tlsCertificateSource: None
      responses:
        '200':
          description: Host updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
              examples:
                Updatehost200Example:
                  summary: Default updateHost 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
                      ambassador_id:
                      - {}
                      acmeProvider:
                        authority: example_value
                        email: [email protected]
                        privateKeySecret: {}
                        registra

# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ambassador/refs/heads/main/openapi/ambassador-openapi.yml