{
  "openapi": "3.1.0",
  "info": {
    "title": "TheRouter.ai API",
    "version": "1.0.0",
    "description": "Unified LLM gateway. OpenAI-compatible API that routes across 200+ models from OpenAI, Anthropic, Google, Meta, and more. Supports model fallbacks, provider selection, streaming, tool calling, and structured outputs.",
    "contact": {
      "name": "TheRouter.ai",
      "url": "https://therouter.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.therouter.ai",
      "description": "Production"
    }
  ],
  "security": [
    { "BearerAuth": [] }
  ],
  "paths": {
    "/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "summary": "Send a chat completion request",
        "description": "Create an OpenAI-compatible chat completion. Supports model fallbacks via 'models' array and provider routing via 'provider' object.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" },
              "example": {
                "model": "openai/gpt-4o-mini",
                "messages": [
                  { "role": "system", "content": "You are a helpful assistant." },
                  { "role": "user", "content": "What is TheRouter.ai?" }
                ],
                "temperature": 0.7,
                "max_tokens": 500,
                "stream": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat completion response",
            "headers": {
              "x-request-id": {
                "description": "Request trace ID (UUIDv4)",
                "schema": { "type": "string", "format": "uuid" }
              },
              "X-RateLimit-Limit": {
                "description": "Request quota window limit",
                "schema": { "type": "integer" }
              },
              "X-RateLimit-Remaining": {
                "description": "Remaining requests in window",
                "schema": { "type": "integer" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" },
                "example": {
                  "id": "chatcmpl-abc123",
                  "object": "chat.completion",
                  "created": 1700000000,
                  "model": "openai/gpt-4o-mini",
                  "choices": [
                    {
                      "index": 0,
                      "message": {
                        "role": "assistant",
                        "content": "TheRouter.ai is a unified LLM gateway that routes requests across multiple AI providers through a single API."
                      },
                      "finish_reason": "stop"
                    }
                  ],
                  "usage": {
                    "prompt_tokens": 25,
                    "completion_tokens": 30,
                    "total_tokens": 55
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": {
                  "error": {
                    "message": "Missing required parameter: model or models",
                    "type": "invalid_request_error",
                    "code": 400,
                    "param": "model"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — missing or invalid API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": {
                  "error": {
                    "message": "Invalid API key",
                    "type": "authentication_error",
                    "code": 401,
                    "param": null
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required — insufficient credits",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": {
                  "error": {
                    "message": "Insufficient credit balance",
                    "type": "insufficient_credits",
                    "code": "insufficient_credits",
                    "balance": {
                      "current": 2.5,
                      "threshold": 5,
                      "currency": "credits"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": { "type": "integer" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": {
                  "error": {
                    "message": "Rate limit exceeded",
                    "type": "rate_limit_error",
                    "code": 429,
                    "param": null
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List available models",
        "description": "Return all available models with pricing, context lengths, supported parameters, and architecture metadata.",
        "responses": {
          "200": {
            "description": "Model list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ModelListResponse" },
                "example": {
                  "data": [
                    {
                      "id": "openai/gpt-4o",
                      "object": "model",
                      "created": 1700000000,
                      "owned_by": "openai",
                      "name": "GPT-4o",
                      "description": "General-purpose multimodal model",
                      "context_length": 128000,
                      "pricing": {
                        "prompt": "0.000005",
                        "completion": "0.000015"
                      },
                      "architecture": {
                        "modality": "text+image->text",
                        "input_modalities": ["text", "image"],
                        "output_modalities": ["text"]
                      },
                      "supported_parameters": ["temperature", "top_p", "stop", "tools"]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/credits": {
      "get": {
        "operationId": "getCredits",
        "summary": "Get credit balance",
        "description": "Read credit balance and total usage. Requires management API key (sk-mgmt-... prefix).",
        "responses": {
          "200": {
            "description": "Credit balance",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreditsResponse" },
                "example": {
                  "data": {
                    "total_credits": 950.5,
                    "total_usage": 49.5
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — requires management key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/embeddings": {
      "post": {
        "operationId": "createEmbedding",
        "summary": "Create embeddings",
        "description": "Create vector embeddings for input text.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EmbeddingRequest" },
              "example": {
                "model": "openai/text-embedding-3-small",
                "input": "TheRouter.ai is a unified LLM gateway."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embedding response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EmbeddingResponse" },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "object": "embedding",
                      "index": 0,
                      "embedding": [0.0023, -0.0091, 0.0152]
                    }
                  ],
                  "model": "openai/text-embedding-3-small",
                  "usage": {
                    "prompt_tokens": 8,
                    "total_tokens": 8
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from TheRouter.ai dashboard. Use an inference key for model requests; management operations require the appropriate key type."
      }
    },
    "schemas": {
      "ChatCompletionRequest": {
        "type": "object",
        "description": "Either messages or input is required. Accepts both Chat Completions format (messages) and Responses API format (input).",
        "properties": {
          "model": {
            "type": "string",
            "description": "Model alias in provider/model format. Required unless 'models' is provided.",
            "example": "openai/gpt-4o"
          },
          "messages": {
            "type": "array",
            "description": "Conversation messages. Required unless input is provided.",
            "items": { "$ref": "#/components/schemas/ChatMessage" }
          },
          "input": {
            "description": "Responses API input. String or array of input items. When provided instead of messages, auto-translated to Chat Completions format.",
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "object" } }
            ]
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2,
            "description": "Sampling temperature."
          },
          "max_tokens": {
            "type": "integer",
            "description": "Maximum tokens to generate."
          },
          "max_completion_tokens": {
            "type": "integer",
            "description": "Maximum completion tokens (alias for max_tokens)."
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "Enable SSE streaming."
          },
          "top_p": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Nucleus sampling."
          },
          "frequency_penalty": {
            "type": "number",
            "description": "Frequency penalty (-2 to 2)."
          },
          "presence_penalty": {
            "type": "number",
            "description": "Presence penalty (-2 to 2)."
          },
          "stop": {
            "description": "Stop sequence(s).",
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" } }
            ]
          },
          "tools": {
            "type": "array",
            "description": "Tool/function definitions.",
            "items": { "$ref": "#/components/schemas/ToolDefinition" }
          },
          "tool_choice": {
            "description": "Tool selection: 'auto' | 'none' | 'required' | {type, function}."
          },
          "response_format": {
            "type": "object",
            "description": "Structured output format."
          },
          "seed": {
            "type": "integer",
            "description": "Deterministic sampling seed."
          },
          "user": {
            "type": "string",
            "description": "End-user ID for analytics."
          },
          "models": {
            "type": "array",
            "items": { "type": "string" },
            "description": "TheRouter extension: fallback model chain."
          },
          "provider": { "$ref": "#/components/schemas/ProviderPreferences" },
          "route": {
            "type": "string",
            "enum": ["fallback", "sort"],
            "description": "TheRouter extension: routing strategy."
          }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": ["role"],
        "properties": {
          "role": {
            "type": "string",
            "enum": ["system", "user", "assistant", "tool"],
            "description": "Message author role."
          },
          "content": {
            "description": "String or array of content parts."
          },
          "name": {
            "type": "string",
            "description": "Optional author name."
          },
          "tool_calls": {
            "type": "array",
            "description": "Tool calls made by the assistant."
          },
          "tool_call_id": {
            "type": "string",
            "description": "For role=tool: ID of the tool call being responded to."
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique completion ID." },
          "object": { "type": "string", "enum": ["chat.completion"] },
          "created": { "type": "integer", "description": "Unix timestamp." },
          "model": { "type": "string", "description": "Model that generated the response." },
          "choices": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Choice" }
          },
          "usage": { "$ref": "#/components/schemas/Usage" }
        }
      },
      "Choice": {
        "type": "object",
        "properties": {
          "index": { "type": "integer" },
          "message": { "$ref": "#/components/schemas/ChatMessage" },
          "finish_reason": {
            "type": "string",
            "enum": ["stop", "length", "tool_calls", "content_filter"],
            "description": "Why generation stopped."
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": { "type": "integer" },
          "completion_tokens": { "type": "integer" },
          "total_tokens": { "type": "integer" }
        }
      },
      "ProviderPreferences": {
        "type": "object",
        "description": "TheRouter extension: provider routing preferences.",
        "properties": {
          "allow_fallbacks": { "type": "boolean", "description": "Allow automatic provider fallbacks." },
          "order": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Preferred provider order."
          },
          "only": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Only use these providers."
          },
          "ignore": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Exclude these providers."
          }
        }
      },
      "ToolDefinition": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "enum": ["function"] },
          "function": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "description": { "type": "string" },
              "parameters": { "type": "object" }
            },
            "required": ["name", "parameters"]
          }
        }
      },
      "ModelListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Model" }
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Model ID in provider/model format." },
          "object": { "type": "string", "enum": ["model"] },
          "created": { "type": "integer" },
          "owned_by": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "context_length": { "type": "integer" },
          "pricing": {
            "type": "object",
            "properties": {
              "prompt": { "type": "string", "description": "USD per token." },
              "completion": { "type": "string", "description": "USD per token." }
            }
          },
          "architecture": {
            "type": "object",
            "properties": {
              "modality": { "type": "string" },
              "input_modalities": { "type": "array", "items": { "type": "string" } },
              "output_modalities": { "type": "array", "items": { "type": "string" } }
            }
          },
          "supported_parameters": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "CreditsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "total_credits": { "type": "number" },
              "total_usage": { "type": "number" }
            }
          }
        }
      },
      "EmbeddingRequest": {
        "type": "object",
        "required": ["model", "input"],
        "properties": {
          "model": { "type": "string" },
          "input": {
            "description": "Text to embed.",
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" } }
            ]
          },
          "encoding_format": {
            "type": "string",
            "enum": ["float", "base64"]
          }
        }
      },
      "EmbeddingResponse": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "enum": ["list"] },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "object": { "type": "string", "enum": ["embedding"] },
                "index": { "type": "integer" },
                "embedding": { "type": "array", "items": { "type": "number" } }
              }
            }
          },
          "model": { "type": "string" },
          "usage": { "$ref": "#/components/schemas/Usage" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard error envelope. All errors follow this shape.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": { "type": "string", "description": "Human-readable error message." },
              "type": { "type": "string", "description": "Error category: invalid_request_error | authentication_error | rate_limit_error | api_error | insufficient_credits." },
              "code": { "description": "HTTP status code (integer) or semantic code (string)." },
              "param": { "type": "string", "nullable": true, "description": "Which parameter caused the error, if applicable." }
            },
            "required": ["message", "type"]
          }
        }
      }
    }
  }
}