API Reference

FreeRouter exposes an OpenAI-compatible REST API at https://api.freerouter.com/v1. Every endpoint mirrors the shape your key speaks — OpenAI by default.

Base URL

https://api.freerouter.com/v1

All endpoints below are relative to this base. FreeRouter serves HTTPS only.

Authentication

Authenticate with your FreeRouter API key as a Bearer token. Never ship it in client-side code — treat it like any server secret.

Authorization: Bearer fr_live_your_key_here

Each key carries its own API shape and routing rule. Requests with a missing or invalid key return 401 Unauthorized.

POST /v1/chat/completions

The primary inference endpoint. It accepts the standard OpenAI chat completion request body and returns a standard chat completion object (or an SSE stream when stream is true).

Request body

Any other OpenAI-compatible fields are forwarded to the selected gateway as-is.

Example request

curl https://api.freerouter.com/v1/chat/completions \
  -H "Authorization: Bearer $FREEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Ping" }],
    "temperature": 0.2
  }'

Response headers

Beyond the standard headers, FreeRouter adds routing metadata so you can observe behavior:

GET /v1/models

Lists the models available to your key across its attached providers, in the OpenAI list format. Use it to discover valid model strings.

curl https://api.freerouter.com/v1/models \
  -H "Authorization: Bearer $FREEROUTER_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "openai/gpt-4o-mini", "object": "model" },
    { "id": "anthropic/claude-3.5-sonnet", "object": "model" }
  ]
}

API shapes

A shape is the request/response format a FreeRouter key speaks. You choose it per key so FreeRouter can be a true drop-in for whatever client you already run. The base URL is the same for every shape; only the path and body conventions differ.

Set the shape when you create the key, or toggle it later in the dashboard — no code change beyond matching the client you already use. FreeRouter translates between the shape your key speaks and the format each gateway expects.

openai (default)

The de facto standard. Works with the OpenAI SDKs and any OpenAI-compatible client. This is the shape used throughout the Quickstart.

openrouter

Accepts OpenRouter-style requests, including OpenRouter's models fallback array and provider preferences. Handy when you're migrating an app already built against OpenRouter and want to keep its request bodies verbatim.

anthropic

Speaks the Anthropic Messages API. Point an Anthropic client at FreeRouter and call /v1/messages:

curl https://api.freerouter.com/v1/messages \
  -H "Authorization: Bearer $FREEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "anthropic/claude-3.5-sonnet",
    "max_tokens": 256,
    "messages": [{ "role": "user", "content": "Ping" }]
  }'

google

Speaks the Google Gemini generateContent format, so a Gemini client can target FreeRouter with the model in the path:

curl "https://api.freerouter.com/v1/models/google/gemini-1.5-pro:generateContent" \
  -H "Authorization: Bearer $FREEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "Ping" }] }]
  }'

Errors

Errors use standard HTTP status codes with an OpenAI-style error body:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Unknown model: foo/bar"
  }
}