Envoy Text Completions API

openapi: 3.2.0
info:
  title: Envoy AI Gateway Text Completions API
  description: The Envoy AI Gateway provides a unified proxy layer for accessing Generative AI services built on top of Envoy Gateway. It exposes OpenAI-compatible and Anthropic-compatible API endpoints, enabling applications to route LLM traffic across multiple AI backends including OpenAI, AWS Bedrock, Google Gemini, and others. The gateway handles backend rate limiting, policy control, token-based quota management, and security configuration via Kubernetes custom resources.
  version: 0.2.0
  contact:
    name: Envoy AI Gateway Community
    url: https://aigateway.envoyproxy.io/
  termsOfService: https://aigateway.envoyproxy.io/
servers:
- url: https://{gateway-host}
  description: Envoy AI Gateway instance
  variables:
    gateway-host:
      default: localhost:8080
      description: Hostname and port of the Envoy AI Gateway instance as configured in the AIGatewayRoute Kubernetes custom resource
security:
- bearerAuth: []
tags:
- name: Text Completions
  description: Legacy text completions endpoints compatible with the OpenAI completions API.
paths:
  /v1/completions:
    post:
      operationId: createCompletion
      summary: Envoy Create a text completion
      description: Creates a text completion for the provided prompt using an AI model routed through the gateway. The request format is compatible with the OpenAI legacy Completions API. This endpoint is primarily provided for backward compatibility; the chat completions endpoint is preferred for modern applications.
      tags:
      - Text Completions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: Text completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Completion'
        '400':
          description: Bad request due to malformed input or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized due to missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit or token quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    UsageInfo:
      type: object
      description: Token usage statistics for the API request
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens in the input prompt
        completion_tokens:
          type: integer
          description: Number of tokens in the generated completion
        total_tokens:
          type: integer
          description: Total number of tokens used (prompt + completion)
    ErrorResponse:
      type: object
      description: Error response returned when an API request fails
      properties:
        error:
          type: object
          description: Error details
          properties:
            message:
              type: string
              description: Human-readable error message describing what went wrong
            type:
              type: string
              description: Error type identifier
            code:
              type: string
              description: Error code for programmatic handling
    Completion:
      type: object
      description: A completed text completion response from the AI model
      properties:
        id:
          type: string
          description: Unique identifier for this completion
        object:
          type: string
          description: Object type, always text_completion
          enum:
          - text_completion
        created:
          type: integer
          description: Unix timestamp of when the completion was created
        model:
          type: string
          description: The model that generated the completion
        choices:
          type: array
          description: List of completion choices generated
          items:
            type: object
            properties:
              text:
                type: string
                description: The generated text
              index:
                type: integer
                description: Index of this choice
              finish_reason:
                type: string
                description: Reason the model stopped generating
                enum:
                - stop
                - length
        usage:
          $ref: '#/components/schemas/UsageInfo'
    CompletionRequest:
      type: object
      description: Request body for the legacy text completions endpoint
      required:
      - model
      - prompt
      properties:
        model:
          type: string
          description: ID of the model to use for text completion
        prompt:
          description: The prompt text to generate completion for
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        max_tokens:
          type: integer
          description: Maximum number of tokens to generate
          minimum: 1
        temperature:
          type: number
          description: Sampling temperature
          minimum: 0
          maximum: 2
        stream:
          type: boolean
          description: If true, partial completions are streamed as server-sent events
          default: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. The token is configured per route in the AIGatewayRoute Kubernetes custom resource. For AI provider backends, the gateway may automatically translate the bearer token to the appropriate provider-specific authentication mechanism.
externalDocs:
  description: Envoy AI Gateway Documentation
  url: https://aigateway.envoyproxy.io/docs/