Ambassador Diagnostics API

openapi: 3.1.0
info:
  title: Ambassador Edge Stack Diagnostics 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: Diagnostics
  description: Access diagnostic and health check endpoints for monitoring Ambassador Edge Stack operational status.
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
components:
  schemas:
    DiagnosticsOverview:
      type: object
      description: Diagnostic overview of an Ambassador instance
      properties:
        system:
          type: object
          description: System-level information
          properties:
            version:
              type: string
              description: Ambassador version
            hostname:
              type: string
              description: Hostname of the Ambassador pod
            ambassador_id:
              type: string
              description: Ambassador instance ID
            cluster_id:
              type: string
              description: Kubernetes cluster identifier
            boot_time:
              type: string
              format: date-time
              description: When this Ambassador instance started
          example: example_value
        ambassador_config:
          type: object
          description: Active Ambassador configuration summary
          additionalProperties: true
          example: example_value
        envoy_status:
          type: object
          description: Status of the underlying Envoy proxy
          properties:
            alive:
              type: boolean
            ready:
              type: boolean
            uptime:
              type: integer
              description: Envoy uptime in seconds
          example: example_value
        route_info:
          type: array
          description: Summary of active routes
          items:
            type: object
            properties:
              prefix:
                type: string
              service:
                type: string
              weight:
                type: integer
          example: []
        errors:
          type: array
          description: List of configuration errors
          items:
            type: object
            properties:
              kind:
                type: string
              name:
                type: string
              namespace:
                type: string
              error:
                type: string
          example: []
  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/