openapi: 3.1.0
info:
  title: Azure AI Foundry Model Inference REST API
  version: '2024-10-21'
  description: |
    Data-plane REST API for running inference against models deployed in Microsoft
    Azure AI Foundry (formerly Azure AI Studio). The endpoint exposes OpenAI-compatible
    routes (`/chat/completions`, `/completions`, `/embeddings`) under the
    `/openai/deployments/{deployment-id}` or `/openai/v1` path on a per-resource host.

    Authentication uses either an API key (`api-key` header) or a Microsoft Entra ID
    OAuth 2.0 bearer token (scope `https://ai.azure.com/.default`).
  contact:
    name: Microsoft Foundry
    url: https://learn.microsoft.com/en-us/azure/ai-foundry/
servers:
  - url: https://{resource}.services.ai.azure.com/openai
    description: Foundry inference endpoint (per-resource)
    variables:
      resource:
        default: my-foundry
        description: Your Foundry resource name
  - url: https://{resource}.openai.azure.com/openai
    description: Compatible Azure OpenAI endpoint exposed by the Foundry resource
    variables:
      resource:
        default: my-foundry
        description: Your Foundry resource name
tags:
  - name: Chat Completions
    description: Chat-formatted text generation
  - name: Completions
    description: Plain text completions
  - name: Embeddings
    description: Vector embeddings for text
  - name: Images
    description: Image generation
  - name: Models
    description: Model and deployment metadata
paths:
  /deployments/{deployment-id}/chat/completions:
    post:
      summary: Create a chat completion
      operationId: createChatCompletion
      tags: [Chat Completions]
      parameters:
        - { in: path, name: deployment-id, required: true, schema: { type: string }, description: Foundry deployment name }
        - { in: query, name: api-version, required: true, schema: { type: string, default: '2024-10-21' } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChatCompletionRequest' }
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ChatCompletionResponse' }
      security:
        - apiKey: []
        - entra: []
  /deployments/{deployment-id}/completions:
    post:
      summary: Create a text completion
      operationId: createCompletion
      tags: [Completions]
      parameters:
        - { in: path, name: deployment-id, required: true, schema: { type: string } }
        - { in: query, name: api-version, required: true, schema: { type: string, default: '2024-10-21' } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt: { type: [string, array] }
                max_tokens: { type: integer }
                temperature: { type: number }
                top_p: { type: number }
                n: { type: integer }
                stream: { type: boolean }
      responses:
        '200':
          description: Completion response
          content:
            application/json:
              schema: { type: object }
      security:
        - apiKey: []
        - entra: []
  /deployments/{deployment-id}/embeddings:
    post:
      summary: Create embeddings
      operationId: createEmbeddings
      tags: [Embeddings]
      parameters:
        - { in: path, name: deployment-id, required: true, schema: { type: string } }
        - { in: query, name: api-version, required: true, schema: { type: string, default: '2024-10-21' } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input: { type: [string, array] }
                user: { type: string }
      responses:
        '200':
          description: Embeddings response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        embedding:
                          type: array
                          items: { type: number }
                        index: { type: integer }
      security:
        - apiKey: []
        - entra: []
  /deployments/{deployment-id}/images/generations:
    post:
      summary: Generate images
      operationId: generateImages
      tags: [Images]
      parameters:
        - { in: path, name: deployment-id, required: true, schema: { type: string } }
        - { in: query, name: api-version, required: true, schema: { type: string, default: '2024-10-21' } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt: { type: string }
                n: { type: integer }
                size: { type: string }
                response_format: { type: string, enum: [url, b64_json] }
      responses:
        '200':
          description: Image generation response
          content:
            application/json:
              schema: { type: object }
      security:
        - apiKey: []
        - entra: []
  /v1/chat/completions:
    post:
      summary: Create a chat completion (OpenAI v1-compatible route)
      description: |
        OpenAI-compatible route. The model deployment is selected by the `model`
        field in the request body rather than the URL path.
      operationId: createChatCompletionV1
      tags: [Chat Completions]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChatCompletionRequest' }
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ChatCompletionResponse' }
      security:
        - entra: []
        - apiKey: []
  /v1/embeddings:
    post:
      summary: Create embeddings (OpenAI v1-compatible route)
      operationId: createEmbeddingsV1
      tags: [Embeddings]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, input]
              properties:
                model: { type: string }
                input: { type: [string, array] }
      responses:
        '200':
          description: Embeddings response
          content:
            application/json:
              schema: { type: object }
      security:
        - entra: []
        - apiKey: []
  /models:
    get:
      summary: List available models
      operationId: listModels
      tags: [Models]
      parameters:
        - { in: query, name: api-version, schema: { type: string, default: '2024-10-21' } }
      responses:
        '200':
          description: Models available on the resource
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { type: object }
      security:
        - apiKey: []
        - entra: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: api-key
      description: Foundry/Azure OpenAI resource API key
    entra:
      type: oauth2
      description: Microsoft Entra ID OAuth 2.0 bearer token (scope https://ai.azure.com/.default)
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            https://ai.azure.com/.default: Default Foundry inference scope
  schemas:
    ChatMessage:
      type: object
      required: [role]
      properties:
        role: { type: string, enum: [system, user, assistant, tool, developer] }
        content: { type: [string, array, 'null'] }
        name: { type: string }
    ChatCompletionRequest:
      type: object
      required: [messages]
      properties:
        model: { type: string, description: Deployment name (for v1 route) }
        messages:
          type: array
          items: { $ref: '#/components/schemas/ChatMessage' }
        temperature: { type: number }
        top_p: { type: number }
        n: { type: integer }
        stream: { type: boolean }
        max_tokens: { type: integer }
        max_completion_tokens: { type: integer }
        stop: { type: [string, array] }
        presence_penalty: { type: number }
        frequency_penalty: { type: number }
        user: { type: string }
    ChatCompletionResponse:
      type: object
      properties:
        id: { type: string }
        object: { type: string }
        created: { type: integer }
        model: { type: string }
        choices:
          type: array
          items:
            type: object
            properties:
              index: { type: integer }
              message: { $ref: '#/components/schemas/ChatMessage' }
              finish_reason: { type: string }
        usage:
          type: object
          properties:
            prompt_tokens: { type: integer }
            completion_tokens: { type: integer }
            total_tokens: { type: integer }