openapi.yaml

openapi: 3.1.0
info:
  title: BitRouter API
  version: 0.9.0
  description: |
    The BitRouter API is a modular LLM routing proxy that exposes multiple provider-compatible
    API surfaces through a single gateway. Route requests to OpenAI, Anthropic, and Google
    models using the native API format of each provider.

    ## Base URL

    ```
    https://api.bitrouter.ai/v1
    ```

    ## Authentication

    BitRouter uses the **x402** payment protocol for request authentication and billing.
    Include a valid x402 signature with each request. See the
    [x402 specification](https://www.x402.org/) for details.

    ## Multi-Protocol Routing

    BitRouter accepts requests in the native format of each supported provider:

    - **OpenAI** — `/v1/chat/completions`, `/v1/responses`
    - **Anthropic** — `/v1/messages`
    - **Google** — `/v1beta/models/{model}:generateContent`

    The router resolves the requested model name to a configured upstream provider,
    forwards the request, and returns the response in the same provider format.

servers:
  - url: https://api.bitrouter.ai/v1
    description: Production

tags:
  - name: OpenAI Compatible
    description: |
      OpenAI-format endpoints. Drop-in compatible with the OpenAI API — accepts the same
      request schema and returns the same response format.
  - name: Anthropic Compatible
    description: |
      Anthropic-format endpoint. Drop-in compatible with the Anthropic Messages API.
  - name: Google Compatible
    description: |
      Google Generative AI endpoint. Compatible with the Gemini `generateContent` API.
  - name: Discovery
    description: Model and route listing endpoints for inspecting the router's configuration.
  - name: Admin
    description: Runtime route management — create, list, and remove routes without restarting the server.
  - name: Observability
    description: Health checks and metrics.

components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error description.
          required:
            - message

    # ── OpenAI Chat Completions ──────────────────────────────

    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: Model ID or route name to use for the completion.
          example: gpt-4o
        messages:
          type: array
          description: A list of messages comprising the conversation so far.
          items:
            $ref: "#/components/schemas/ChatMessage"
        temperature:
          type: number
          description: Sampling temperature (0.0–2.0).
          minimum: 0
          maximum: 2
        top_p:
          type: number
          description: Nucleus sampling parameter.
          minimum: 0
          maximum: 1
        max_tokens:
          type: integer
          description: Maximum number of tokens to generate.
        max_completion_tokens:
          type: integer
          description: Maximum number of completion tokens to generate.
        stop:
          type: array
          items:
            type: string
          description: Sequences where the API will stop generating.
        presence_penalty:
          type: number
          description: Presence penalty (-2.0 to 2.0).
        frequency_penalty:
          type: number
          description: Frequency penalty (-2.0 to 2.0).
        seed:
          type: integer
          description: Seed for deterministic sampling.
        stream:
          type: boolean
          description: Whether to stream partial responses using SSE.
          default: false

    ChatMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
          description: The role of the message author.
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: "#/components/schemas/ChatContentPart"
          description: The content of the message — either a plain string or an array of content parts.

    ChatContentPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string

    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the completion.
        object:
          type: string
          enum:
            - chat.completion
        created:
          type: integer
          description: Unix timestamp (seconds) of when the completion was created.
        model:
          type: string
          description: The model used for the completion.
        choices:
          type: array
          items:
            $ref: "#/components/schemas/ChatCompletionChoice"
        usage:
          $ref: "#/components/schemas/ChatCompletionUsage"

    ChatCompletionChoice:
      type: object
      properties:
        index:
          type: integer
        message:
          type: object
          properties:
            role:
              type: string
            content:
              type: string
              nullable: true
        finish_reason:
          type: string
          nullable: true
          enum:
            - stop
            - length

    ChatCompletionUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer

    ChatCompletionChunk:
      type: object
      description: A single chunk in a streamed chat completion response (SSE `data` payload).
      properties:
        id:
          type: string
        object:
          type: string
          enum:
            - chat.completion.chunk
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            $ref: "#/components/schemas/ChatCompletionChunkChoice"
        usage:
          $ref: "#/components/schemas/ChatCompletionUsage"

    ChatCompletionChunkChoice:
      type: object
      properties:
        index:
          type: integer
        delta:
          type: object
          properties:
            role:
              type: string
            content:
              type: string
        finish_reason:
          type: string
          nullable: true

    # ── OpenAI Responses API ─────────────────────────────────

    ResponsesRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: Model ID or route name.
          example: gpt-4o
        input:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: "#/components/schemas/ResponsesInputMessage"
          description: A text string or an array of input messages.
        temperature:
          type: number
          description: Sampling temperature.
        top_p:
          type: number
          description: Nucleus sampling parameter.
        max_output_tokens:
          type: integer
          description: Maximum number of output tokens.
        stream:
          type: boolean
          description: Whether to stream the response using SSE.
          default: false

    ResponsesInputMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
            - system
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: "#/components/schemas/ResponsesInputContentPart"
          description: Message content — a string or array of content parts.

    ResponsesInputContentPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - input_text
        text:
          type: string

    ResponsesResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
            - response
        created_at:
          type: integer
          description: Unix timestamp (seconds).
        model:
          type: string
        output:
          type: array
          items:
            $ref: "#/components/schemas/ResponsesOutputItem"
        usage:
          $ref: "#/components/schemas/ResponsesUsage"
        status:
          type: string
          enum:
            - completed

    ResponsesOutputItem:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - message
        role:
          type: string
        content:
          type: array
          items:
            $ref: "#/components/schemas/ResponsesOutputContent"
        status:
          type: string

    ResponsesOutputContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - output_text
        text:
          type: string

    ResponsesUsage:
      type: object
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer

    ResponsesStreamEvent:
      type: object
      description: A single event in a streamed Responses API response (SSE `data` payload).
      properties:
        type:
          type: string
          description: Event type (e.g. `response.output_text.delta`, `response.completed`).
        item_id:
          type: string
        output_index:
          type: integer
        content_index:
          type: integer
        delta:
          type: string

    # ── Anthropic Messages ───────────────────────────────────

    MessagesRequest:
      type: object
      required:
        - model
        - messages
        - max_tokens
      properties:
        model:
          type: string
          description: Model ID or route name.
          example: claude-sonnet-4-20250514
        messages:
          type: array
          description: Input messages.
          items:
            $ref: "#/components/schemas/AnthropicMessage"
        max_tokens:
          type: integer
          description: The maximum number of tokens to generate before stopping.
        system:
          type: string
          description: System prompt.
        temperature:
          type: number
          description: Sampling temperature (0.0–1.0).
          minimum: 0
          maximum: 1
        top_p:
          type: number
          description: Nucleus sampling parameter.
        top_k:
          type: integer
          description: Top-K sampling parameter.
        stop_sequences:
          type: array
          items:
            type: string
          description: Custom stop sequences.
        stream:
          type: boolean
          description: Whether to stream the response using SSE.
          default: false

    AnthropicMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: "#/components/schemas/AnthropicContentBlock"
          description: Message content — a string or array of content blocks.

    AnthropicContentBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string

    MessagesResponse:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - message
        role:
          type: string
          enum:
            - assistant
        content:
          type: array
          items:
            $ref: "#/components/schemas/MessagesResponseContent"
        model:
          type: string
        stop_reason:
          type: string
          nullable: true
          enum:
            - end_turn
            - max_tokens
            - stop_sequence
        stop_sequence:
          type: string
          nullable: true
        usage:
          $ref: "#/components/schemas/MessagesUsage"

    MessagesResponseContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string

    MessagesUsage:
      type: object
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer

    MessagesStreamEvent:
      type: object
      description: A single event in a streamed Anthropic Messages response (SSE `data` payload).
      properties:
        type:
          type: string
          description: "Event type: `message_start`, `content_block_delta`, `message_delta`, `message_stop`."
        index:
          type: integer
        delta:
          $ref: "#/components/schemas/MessagesStreamDelta"
        message:
          $ref: "#/components/schemas/MessagesStreamMessage"

    MessagesStreamDelta:
      type: object
      properties:
        type:
          type: string
        text:
          type: string
        stop_reason:
          type: string

    MessagesStreamMessage:
      type: object
      properties:
        id:
          type: string
        model:
          type: string
        role:
          type: string

    # ── Google Generative AI ─────────────────────────────────

    GenerateContentRequest:
      type: object
      required:
        - model
        - contents
      properties:
        model:
          type: string
          description: Model ID or route name.
          example: gemini-2.0-flash
        contents:
          type: array
          description: The conversation contents.
          items:
            $ref: "#/components/schemas/GoogleContent"
        systemInstruction:
          $ref: "#/components/schemas/GoogleSystemInstruction"
        generationConfig:
          $ref: "#/components/schemas/GoogleGenerationConfig"
        stream:
          type: boolean
          description: Whether to stream the response.
          default: false

    GoogleContent:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - user
            - model
        parts:
          type: array
          items:
            $ref: "#/components/schemas/GooglePart"

    GoogleSystemInstruction:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: "#/components/schemas/GooglePart"

    GooglePart:
      type: object
      properties:
        text:
          type: string

    GoogleGenerationConfig:
      type: object
      properties:
        temperature:
          type: number
        topP:
          type: number
        topK:
          type: integer
        maxOutputTokens:
          type: integer
        stopSequences:
          type: array
          items:
            type: string

    GenerateContentResponse:
      type: object
      properties:
        candidates:
          type: array
          items:
            $ref: "#/components/schemas/GenerateContentCandidate"
        usageMetadata:
          $ref: "#/components/schemas/GenerateContentUsageMetadata"
        modelVersion:
          type: string

    GenerateContentCandidate:
      type: object
      properties:
        content:
          type: object
          properties:
            role:
              type: string
            parts:
              type: array
              items:
                $ref: "#/components/schemas/GooglePart"
        finishReason:
          type: string
        index:
          type: integer

    GenerateContentUsageMetadata:
      type: object
      properties:
        promptTokenCount:
          type: integer
        candidatesTokenCount:
          type: integer
        totalTokenCount:
          type: integer

    GenerateContentStreamChunk:
      type: object
      description: A single chunk in a streamed Google GenerateContent response.
      properties:
        candidates:
          type: array
          items:
            type: object
            properties:
              content:
                type: object
                properties:
                  role:
                    type: string
                  parts:
                    type: array
                    items:
                      $ref: "#/components/schemas/GooglePart"
              finishReason:
                type: string
                nullable: true
              index:
                type: integer
        usageMetadata:
          $ref: "#/components/schemas/GenerateContentUsageMetadata"
        modelVersion:
          type: string

    # ── Discovery ────────────────────────────────────────────

    ModelResponse:
      type: object
      properties:
        id:
          type: string
          description: The upstream model ID.
          example: gpt-4o
        provider:
          type: string
          description: The provider that offers this model.
          example: openai
        name:
          type: string
          description: Human-readable display name.
        description:
          type: string
          description: Brief description of the model's capabilities.
        max_input_tokens:
          type: integer
          description: Maximum input context window in tokens.
        max_output_tokens:
          type: integer
          description: Maximum number of output tokens.
        input_modalities:
          type: array
          items:
            type: string
          description: "Input modalities the model accepts (e.g. `text`, `image`)."
        output_modalities:
          type: array
          items:
            type: string
          description: Output modalities the model can produce.

    RouteEntry:
      type: object
      properties:
        model:
          type: string
          description: The virtual model/route name.
          example: default
        provider:
          type: string
          description: The provider this route maps to.
          example: openai
        protocol:
          type: string
          description: "The API protocol (`openai`, `anthropic`, `google`)."
          example: openai

    # ── Admin ────────────────────────────────────────────────

    DynamicRoute:
      type: object
      required:
        - model
        - endpoints
      properties:
        model:
          type: string
          description: The virtual model name to create or update.
          example: research
        strategy:
          type: string
          description: Routing strategy across endpoints.
          enum:
            - priority
            - load_balance
          default: priority
        endpoints:
          type: array
          minItems: 1
          description: One or more upstream endpoints to route to.
          items:
            $ref: "#/components/schemas/RouteEndpoint"

    RouteEndpoint:
      type: object
      required:
        - provider
        - model_id
      properties:
        provider:
          type: string
          description: Provider name (must exist in config or built-ins).
          example: openai
        model_id:
          type: string
          description: The upstream model ID to send to this provider.
          example: gpt-4o

    AdminRouteListEntry:
      type: object
      properties:
        model:
          type: string
          description: The virtual model/route name.
        strategy:
          type: string
          nullable: true
          description: "Routing strategy (`priority` or `load_balance`). Null for config-defined routes."
        endpoints:
          type: array
          items:
            $ref: "#/components/schemas/RouteEndpoint"
        source:
          type: string
          description: "Where this route was defined: `config` or `dynamic`."
          enum:
            - config
            - dynamic

    # ── Observability ────────────────────────────────────────

    MetricsSnapshot:
      type: object
      properties:
        uptime_seconds:
          type: integer
          description: Seconds since the metrics collector was created.
        routes:
          type: object
          description: Per-route aggregate metrics keyed by route name.
          additionalProperties:
            $ref: "#/components/schemas/RouteSnapshot"

    RouteSnapshot:
      type: object
      properties:
        total_requests:
          type: integer
        total_errors:
          type: integer
        error_rate:
          type: number
        latency_p50_ms:
          type: integer
        latency_p99_ms:
          type: integer
        avg_input_tokens:
          type: integer
        avg_output_tokens:
          type: integer
        last_used:
          type: integer
          description: Unix timestamp (seconds) of the last request on this route.
        by_endpoint:
          type: object
          description: Per-endpoint breakdown within this route.
          additionalProperties:
            $ref: "#/components/schemas/EndpointSnapshot"

    EndpointSnapshot:
      type: object
      properties:
        total_requests:
          type: integer
        total_errors:
          type: integer
        latency_p50_ms:
          type: integer
        latency_p99_ms:
          type: integer

paths:
  # ── OpenAI Compatible ──────────────────────────────────────

  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create chat completion
      description: |
        Creates a chat completion for the given messages. This endpoint is a drop-in
        replacement for the OpenAI Chat Completions API — it accepts the same request
        schema and returns the same response format, including `usage` with token counts.

        The router resolves the requested model to an upstream provider, forwards the
        request, and returns the response. Supports both synchronous and streaming modes.

        When `stream: true`, the response is sent as Server-Sent Events (SSE) where each
        `data` line contains a `ChatCompletionChunk` JSON object. The stream ends with
        `data: [DONE]`.
      tags:
        - OpenAI Compatible
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatCompletionRequest"
      responses:
        "200":
          description: Chat completion response (non-streaming).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatCompletionResponse"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ChatCompletionChunk"
        "400":
          description: Bad request — invalid model or malformed request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: No route found for the requested model.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /responses:
    post:
      operationId: createResponse
      summary: Create response
      description: |
        Creates a model response using the OpenAI Responses API format. Accepts either a
        plain text string or a structured array of input messages.

        When `stream: true`, the response is sent as Server-Sent Events (SSE) where each
        `data` line contains a `ResponsesStreamEvent` JSON object.
      tags:
        - OpenAI Compatible
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResponsesRequest"
      responses:
        "200":
          description: Response (non-streaming).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponsesResponse"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ResponsesStreamEvent"
        "400":
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: No route found for the requested model.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Anthropic Compatible ───────────────────────────────────

  /messages:
    post:
      operationId: createMessage
      summary: Create message
      description: |
        Creates a message using the Anthropic Messages API format. Accepts the same
        request schema as the Anthropic API and returns the same response format.

        When `stream: true`, the response is sent as Server-Sent Events (SSE). Each event
        has a `type` field indicating the event kind (`message_start`, `content_block_delta`,
        `message_delta`, `message_stop`).
      tags:
        - Anthropic Compatible
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessagesRequest"
      responses:
        "200":
          description: Messages response (non-streaming).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessagesResponse"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/MessagesStreamEvent"
        "400":
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: No route found for the requested model.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Google Compatible ──────────────────────────────────────

  /v1beta/models/{model}:generateContent:
    post:
      operationId: generateContent
      summary: Generate content
      description: |
        Generates content using the Google Generative AI API format. Compatible with
        the Gemini `generateContent` endpoint.

        When `stream: true`, the response is sent as newline-delimited JSON where each
        line contains a `GenerateContentStreamChunk` object.

        **Note:** This endpoint uses the full path `/v1beta/models/{model}:generateContent`
        rather than being relative to the `/v1` base URL.
      tags:
        - Google Compatible
      parameters:
        - name: model
          in: path
          required: true
          description: "Model ID with optional action suffix (e.g. `gemini-2.0-flash:generateContent`)."
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateContentRequest"
      responses:
        "200":
          description: Generated content response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerateContentResponse"
        "400":
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: No route found for the requested model.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Discovery ──────────────────────────────────────────────

  /models:
    get:
      operationId: listModels
      summary: List available models
      description: |
        Returns all models available across configured providers. Supports optional
        query filters for provider, model ID substring, and modality.
      tags:
        - Discovery
      parameters:
        - name: provider
          in: query
          description: Filter by provider name (exact match).
          schema:
            type: string
        - name: id
          in: query
          description: Filter by model ID (case-insensitive substring match).
          schema:
            type: string
        - name: input_modality
          in: query
          description: "Filter by supported input modality (e.g. `text`, `image`)."
          schema:
            type: string
        - name: output_modality
          in: query
          description: Filter by supported output modality.
          schema:
            type: string
      responses:
        "200":
          description: List of models.
          content:
            application/json:
              schema:
                type: object
                properties:
                  models:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModelResponse"

  /routes:
    get:
      operationId: listRoutes
      summary: List configured routes
      description: |
        Returns the list of configured model routes, including the virtual model
        name, provider, and API protocol for each route.
      tags:
        - Discovery
      responses:
        "200":
          description: List of routes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  routes:
                    type: array
                    items:
                      $ref: "#/components/schemas/RouteEntry"

  # ── Admin ──────────────────────────────────────────────────

  /admin/routes:
    get:
      operationId: listAdminRoutes
      summary: List all routes (admin)
      description: |
        Lists all routes including both config-defined and dynamically-added routes.
        Each entry includes a `source` field indicating where it was defined.
        Dynamic routes shadow config routes with the same model name.
      tags:
        - Admin
      responses:
        "200":
          description: List of all routes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  routes:
                    type: array
                    items:
                      $ref: "#/components/schemas/AdminRouteListEntry"
    post:
      operationId: createRoute
      summary: Create or update a dynamic route
      description: |
        Creates a new dynamic route or updates an existing one. Dynamic routes shadow
        any config-defined route with the same model name. Requires at least one endpoint.
      tags:
        - Admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DynamicRoute"
      responses:
        "200":
          description: Route created or updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - ok
                  model:
                    type: string
        "400":
          description: Bad request (e.g. empty endpoints array).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /admin/routes/{name}:
    delete:
      operationId: deleteRoute
      summary: Remove a dynamic route
      description: |
        Removes a dynamically-added route by model name. Config-defined routes
        cannot be removed via this endpoint. If the dynamic route was shadowing
        a config route, the config route becomes active again.
      tags:
        - Admin
      parameters:
        - name: name
          in: path
          required: true
          description: The model name of the dynamic route to remove.
          schema:
            type: string
      responses:
        "200":
          description: Route removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - ok
                  model:
                    type: string
                  removed:
                    type: boolean
        "404":
          description: No dynamic route found with this name.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Observability ──────────────────────────────────────────

  /metrics:
    get:
      operationId: getMetrics
      summary: Get metrics snapshot
      description: |
        Returns an in-memory snapshot of per-route and per-endpoint metrics including
        request counts, error rates, latency percentiles, and token usage averages.
      tags:
        - Observability
      responses:
        "200":
          description: Metrics snapshot.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetricsSnapshot"

  /health:
    get:
      operationId: healthCheck
      summary: Health check
      description: Returns `{"status":"ok"}` if the router is healthy.
      tags:
        - Observability
      responses:
        "200":
          description: Router is healthy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - ok