openapi: 3.0.3
info:
  title: Bifrost HTTP Gateway Chat API
  description: The Bifrost HTTP Gateway API provides an OpenAI-compatible RESTful interface that routes requests to any of 20+ supported AI providers through a single unified endpoint. Requests specify the provider and model using the format provider/model-name in the model field, enabling seamless provider switching without client code changes.
  version: v1
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: Bifrost Community
    url: https://github.com/maximhq/bifrost
  x-generated-from: documentation
servers:
- url: http://localhost:8080
  description: Bifrost HTTP Gateway (default local port 8080)
tags:
- name: Chat
  description: Chat completions compatible with OpenAI chat API
paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: Bifrost Create Chat Completion
      description: Creates a chat completion routed to the specified AI provider and model. Use the format provider/model-name in the model field (e.g., openai/gpt-4o, anthropic/claude-3-5-sonnet-20241022).
      tags:
      - Chat
      security:
      - BifrostProviderAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              CreateChatCompletion201Example:
                summary: Default createChatCompletion request example
                x-microcks-default: true
                value:
                  model: openai/gpt-4o
                  messages:
                  - role: user
                    content: Hello, how are you?
                  temperature: 0.7
                  max_tokens: 256
      responses:
        '200':
          description: Chat completion response from the AI provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
              examples:
                CreateChatCompletion200Example:
                  summary: Default createChatCompletion 200 response
                  x-microcks-default: true
                  value:
                    id: chatcmpl-abc123
                    object: chat.completion
                    created: 1713000000
                    model: openai/gpt-4o
                    choices:
                    - index: 0
                      message:
                        role: assistant
                        content: Hello! I'm doing well, thank you for asking.
                      finish_reason: stop
                    usage:
                      prompt_tokens: 12
                      completion_tokens: 14
                      total_tokens: 26
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream provider error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/chat/completions/stream:
    post:
      operationId: streamChatCompletion
      summary: Bifrost Stream Chat Completion
      description: Creates a streaming chat completion. Returns server-sent events (SSE) with incremental token chunks from the AI provider.
      tags:
      - Chat
      security:
      - BifrostProviderAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              StreamChatCompletion201Example:
                summary: Default streamChatCompletion request example
                x-microcks-default: true
                value:
                  model: anthropic/claude-3-5-sonnet-20241022
                  messages:
                  - role: user
                    content: Tell me a short joke.
                  stream: true
      responses:
        '200':
          description: Server-sent event stream of chat completion chunks.
          content:
            text/event-stream:
              schema:
                type: string
              examples:
                StreamChatCompletion200Example:
                  summary: Default streamChatCompletion 200 response
                  x-microcks-default: true
                  value: 'data: {"id":"chatcmpl-xyz","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}


                    data: [DONE]

                    '
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ChatCompletionRequest:
      title: Chat Completion Request
      description: Request body for creating a chat completion.
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: Provider and model name in the format provider/model-name (e.g., openai/gpt-4o, anthropic/claude-3-5-sonnet-20241022).
          example: openai/gpt-4o
        messages:
          type: array
          description: Array of messages comprising the conversation.
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          description: Sampling temperature between 0 and 2.
          example: 0.7
        max_tokens:
          type: integer
          description: Maximum number of tokens to generate.
          example: 256
        stream:
          type: boolean
          description: Whether to stream the response as SSE.
          example: false
        top_p:
          type: number
          description: Nucleus sampling probability.
          example: 1.0
        n:
          type: integer
          description: Number of completions to generate.
          example: 1
    ChatMessage:
      title: Chat Message
      description: A single message in a chat conversation.
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          description: Role of the message author.
          enum:
          - system
          - user
          - assistant
          example: user
        content:
          type: string
          description: Content of the message.
          example: Hello, how are you?
    ChatCompletionResponse:
      title: Chat Completion Response
      description: Response from a chat completion request.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the completion.
          example: chatcmpl-abc123
        object:
          type: string
          description: Object type, always chat.completion.
          example: chat.completion
        created:
          type: integer
          description: Unix timestamp of when the completion was created.
          example: 1713000000
        model:
          type: string
          description: Provider and model used for the completion.
          example: openai/gpt-4o
        choices:
          type: array
          description: Array of completion choices.
          items:
            $ref: '#/components/schemas/ChatChoice'
        usage:
          $ref: '#/components/schemas/UsageStats'
    ErrorResponse:
      title: Error Response
      description: Standard error response.
      type: object
      properties:
        error:
          type: string
          description: Error message.
          example: invalid model format
        code:
          type: integer
          description: HTTP status code.
          example: 400
    UsageStats:
      title: Usage Stats
      description: Token usage statistics for the completion.
      type: object
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens in the prompt.
          example: 12
        completion_tokens:
          type: integer
          description: Number of tokens generated.
          example: 14
        total_tokens:
          type: integer
          description: Total tokens used.
          example: 26
    ChatChoice:
      title: Chat Choice
      description: A single completion choice in the response.
      type: object
      properties:
        index:
          type: integer
          description: Index of this choice.
          example: 0
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          type: string
          description: Reason the generation stopped.
          enum:
          - stop
          - length
          - content_filter
          example: stop
  securitySchemes:
    BifrostProviderAuth:
      type: apiKey
      in: header
      name: x-bf-provider-key
      description: Provider API key passed as x-bf-provider-key header. Alternatively, provider keys can be configured server-side in bifrost configuration.