openapi: 3.1.0
info:
  title: QuotaFlow OpenAI-Compatible API
  version: 2026-05-18
  description: |
    QuotaFlow exposes OpenAI-compatible endpoints for model discovery, Responses, and Chat Completions.
    Use this schema for SDK configuration, AI agent integration, and generated API references.
servers:
  - url: https://api.quotaflow.ai/openai/v1
    description: Production OpenAI-compatible base URL
security:
  - bearerAuth: []
paths:
  /models:
    get:
      operationId: listModels
      summary: List models
      description: Lists models available to the authenticated QuotaFlow key.
      responses:
        '200':
          description: Model list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
              examples:
                ok:
                  value:
                    object: list
                    data:
                      - id: gpt-5.2
                        object: model
                        owned_by: openai
                      - id: gpt-5.3-codex
                        object: model
                        owned_by: openai
                      - id: gpt-5.4
                        object: model
                        owned_by: openai
                      - id: gpt-5.5
                        object: model
                        owned_by: openai
                      - id: gpt-4o-mini-transcribe
                        object: model
                        owned_by: openai
        '401':
          $ref: '#/components/responses/MissingOrInvalidKey'
  /responses:
    post:
      operationId: createResponse
      summary: Create a response
      description: Creates an OpenAI-compatible response. Supports streaming with server-sent events when `stream` is true.
      parameters:
        - $ref: '#/components/parameters/SessionIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseCreateRequest'
            examples:
              minimal:
                value:
                  model: gpt-5.5
                  input: Return only the word connected.
                  stream: false
      responses:
        '200':
          description: Response object or streaming event stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/MissingOrInvalidKey'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/CapacityUnavailable'
  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create a chat completion
      description: Legacy OpenAI-compatible chat completions endpoint for existing clients.
      parameters:
        - $ref: '#/components/parameters/SessionIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              minimal:
                value:
                  model: gpt-5.5
                  messages:
                    - role: user
                      content: Return only the word ready.
                  stream: false
      responses:
        '200':
          description: Chat completion response or stream.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
            text/event-stream:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/MissingOrInvalidKey'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimited'
  /audio/transcriptions:
    post:
      operationId: createAudioTranscription
      summary: Create an audio transcription
      description: Transcribes audio to text. This route uses only upstream accounts marked with the `audioTranscription` capability.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [model, file]
              properties:
                model:
                  type: string
                  examples: [gpt-4o-mini-transcribe]
                file:
                  type: string
                  format: binary
                language:
                  type: string
                prompt:
                  type: string
      responses:
        '200':
          description: Audio transcription result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/MissingOrInvalidKey'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: QuotaFlow API key.
  parameters:
    SessionIdHeader:
      name: x-session-id
      in: header
      required: false
      description: Stable session id used for sticky upstream routing and cache locality.
      schema:
        type: string
  responses:
    MissingOrInvalidKey:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing:
              value:
                error: Missing API key
                message: Please provide an API key in the x-api-key, x-goog-api-key, or Authorization header
    PermissionDenied:
      description: The API key lacks permission for this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            denied:
              value:
                error:
                  message: This API key does not have permission to access OpenAI
                  type: permission_denied
                  code: permission_denied
    BadRequest:
      description: Invalid request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Capacity or upstream rate limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            usageLimit:
              value:
                error:
                  type: usage_limit_reached
                  message: The usage limit has been reached
                  resets_in_seconds: 3600
    CapacityUnavailable:
      description: Capacity guard queue timeout or temporary capacity unavailability.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ModelList:
      type: object
      required: [object, data]
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
    Model:
      type: object
      required: [id, object]
      properties:
        id:
          type: string
          examples: [gpt-5.5]
        object:
          type: string
          examples: [model]
        created:
          type: integer
        owned_by:
          type: string
    ResponseCreateRequest:
      type: object
      required: [model, input]
      additionalProperties: true
      properties:
        model:
          type: string
          examples: [gpt-5.5]
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties: true
        stream:
          type: boolean
          default: false
        session_id:
          type: string
          description: Optional sticky session id.
        conversation_id:
          type: string
          description: Optional sticky conversation id.
        prompt_cache_key:
          type: string
          description: Optional cache-friendly sticky key.
        max_output_tokens:
          type: integer
          minimum: 1
    ResponseObject:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
        object:
          type: string
        model:
          type: string
        output:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type: object
          additionalProperties: true
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      additionalProperties: true
      properties:
        model:
          type: string
          examples: [gpt-5.5]
        messages:
          type: array
          items:
            type: object
            required: [role, content]
            properties:
              role:
                type: string
                enum: [system, user, assistant, tool]
              content:
                oneOf:
                  - type: string
                  - type: array
                    items:
                      type: object
                      additionalProperties: true
        stream:
          type: boolean
          default: false
    ErrorResponse:
      type: object
      additionalProperties: true
      properties:
        error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        message:
          type: string
