openapi: 3.0.3
info:
  title: Azure API Management AI Gateway API
  description: The AI gateway capabilities in Azure API Management provide specialized features for managing, securing, and observing AI backend APIs including Azure OpenAI, OpenAI-compatible LLMs, MCP servers, and A2A agent APIs. Includes token rate limiting, semantic caching, load balancing across AI backends, and content safety enforcement.
  version: '2024-05-01'
  contact:
    name: Microsoft Azure
    url: https://learn.microsoft.com/en-us/azure/api-management/genai-gateway-capabilities
servers:
- url: https://{service-name}.azure-api.net
tags:
- name: Gateway
paths:
  /{api-path}:
    get:
      summary: Proxy GET request to backend API
      operationId: Gateway_ProxyGet
      tags:
      - Gateway
      description: Routes GET request through the gateway, applying configured policies.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: api-path
        in: path
        required: true
        schema:
          type: string
        example: petstore/v1/pets
      responses:
        '200':
          description: Response from backend API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayResponse'
              examples:
                ProxyGetExample:
                  summary: Proxied GET response
                  value:
                    statusCode: 200
                    headers:
                      x-apim-request-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      x-ms-request-id: req-001
                    body:
                      message: Response from backend service
              x-microcks-default:
                statusCode: 200
                headers:
                  x-apim-request-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    post:
      summary: Proxy POST request to backend API
      operationId: Gateway_ProxyPost
      tags:
      - Gateway
      description: Routes POST request through the gateway, applying configured policies.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: api-path
        in: path
        required: true
        schema:
          type: string
        example: petstore/v1/pets
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              ProxyPostExample:
                summary: Proxied POST request body
                value:
                  name: Fluffy
                  species: cat
      responses:
        '200':
          description: Response from backend API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayResponse'
              examples:
                ProxyPostExample:
                  summary: Proxied POST response
                  value:
                    statusCode: 201
                    headers:
                      x-apim-request-id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                    body:
                      id: pet-123
                      name: Fluffy
                      species: cat
              x-microcks-default:
                statusCode: 201
    put:
      summary: Proxy PUT request to backend API
      operationId: Gateway_ProxyPut
      tags:
      - Gateway
      description: Routes PUT request through the gateway, applying configured policies.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: api-path
        in: path
        required: true
        schema:
          type: string
        example: petstore/v1/pets/pet-123
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              ProxyPutExample:
                summary: Proxied PUT request body
                value:
                  name: Fluffy Updated
                  species: cat
      responses:
        '200':
          description: Response from backend API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayResponse'
              examples:
                ProxyPutExample:
                  summary: Proxied PUT response
                  value:
                    statusCode: 200
                    headers:
                      x-apim-request-id: c3d4e5f6-a7b8-9012-cdef-123456789012
                    body:
                      id: pet-123
                      name: Fluffy Updated
                      species: cat
              x-microcks-default:
                statusCode: 200
    delete:
      summary: Proxy DELETE request to backend API
      operationId: Gateway_ProxyDelete
      tags:
      - Gateway
      description: Routes DELETE request through the gateway, applying configured policies.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: api-path
        in: path
        required: true
        schema:
          type: string
        example: petstore/v1/pets/pet-123
      responses:
        '200':
          description: Response from backend API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayResponse'
              examples:
                ProxyDeleteExample:
                  summary: Proxied DELETE response
                  value:
                    statusCode: 204
                    headers:
                      x-apim-request-id: d4e5f6a7-b8c9-0123-defa-234567890123
                    body: {}
              x-microcks-default:
                statusCode: 204
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways
  : get:
      summary: Microsoft Azure API Management Gateway_ListByService
      operationId: Gateway_ListByService
      description: Lists a collection of gateways registered with service instance.
      responses:
        '200':
          description: Success
      tags:
      - Gateway
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/{gatewayId}
  : head:
      summary: Microsoft Azure API Management Gateway_GetEntityTag
      operationId: Gateway_GetEntityTag
      description: Gets the entity state (Etag) version of the Gateway specified by its identifier.
      responses:
        '200':
          description: Success
      tags:
      - Gateway
    get:
      summary: Microsoft Azure API Management Gateway_Get
      operationId: Gateway_Get
      description: Gets the details of the Gateway specified by its identifier.
      responses:
        '200':
          description: Success
      tags:
      - Gateway
    put:
      summary: Microsoft Azure API Management Gateway_CreateOrUpdate
      operationId: Gateway_CreateOrUpdate
      description: Creates or updates a Gateway to be used in Api Management instance.
      responses:
        '200':
          description: Success
      tags:
      - Gateway
    patch:
      summary: Microsoft Azure API Management Gateway_Update
      operationId: Gateway_Update
      description: Updates the details of the gateway specified by its identifier.
      responses:
        '200':
          description: Success
      tags:
      - Gateway
    delete:
      summary: Microsoft Azure API Management Gateway_Delete
      operationId: Gateway_Delete
      description: Deletes specific Gateway.
      responses:
        '200':
          description: Success
      tags:
      - Gateway
components:
  schemas:
    GatewayResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 200
        headers:
          type: object
          properties:
            x-apim-request-id:
              type: string
              example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            x-ms-request-id:
              type: string
              example: req-001
        body:
          type: object
externalDocs:
  description: Documentation
  url: https://learn.microsoft.com/en-us/azure/api-management/genai-gateway-capabilities
x-generated-from: documentation