API Routes

Detailed reference for all HTTP endpoints - /health, /v1/models, and /v1/chat/completions with request/response schemas. Entirely free ($0 cost).

`GET /health`

Returns server health status and a provider health snapshot for the keys passed via headers.

Request

No parameters. Provider keys passed via X-{Provider}-Key headers are used for health introspection.

Response

200 OK

{
  "status": "ok",
  "providers": {
    "groq": {
      "state": "healthy",
      "consecutiveFailures": 0
    }
  }
}

Scoped health

Health state is returned only for the keys you pass via headers. Other users' health is never exposed.

`GET /v1/models`

Returns all known models in OpenAI format. Includes 6 capability aliases and ~87 concrete provider models.

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "free:auto",
      "object": "model",
      "created": 1710000000,
      "owned_by": "freerouter"
    },
    {
      "id": "groq/llama-3.3-70b-versatile",
      "object": "model",
      "created": 1710000000,
      "owned_by": "groq"
    }
  ]
}

Included models

Type	Count	Example
Aliases	6	`free:auto`, `free:fast`, `free:reasoning`, `free:long-context`, `free:vision`, `free:tool-use`
Concrete models	~87	`groq/llama-3.3-70b-versatile`, `google/gemini-2.5-flash`, ...

Concrete models use the format {provider}/{modelId} (e.g. groq/llama-3.3-70b-versatile).

`POST /v1/chat/completions`

Main completion endpoint. Fully OpenAI-compatible - works with any OpenAI SDK client, the Vercel AI SDK, or raw HTTP requests.

Parameters

Prop

Type

Message roles

Role	Description
`system`	System prompt for behavior control
`user`	User message. `content` can be a string or array of content parts (text, image_url)
`assistant`	Assistant response. Can include `tool_calls`
`tool`	Tool result. Must include `tool_call_id` referencing the original call

Request body example

Request

{
  "model": "free:auto",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What's the weather in Tokyo?" }
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "City name" }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Responses

200 OK

{
  "id": "chatcmpl-abc123def",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "free:auto",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Let me check the weather in Tokyo for you."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "promptTokens": 25,
    "completionTokens": 12,
    "totalTokens": 37
  }
}

Pinned model usage

Instead of an alias, pass a concrete model ID to pin to a specific provider:

Pinned model request

{
  "model": "groq/llama-3.3-70b-versatile",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ]
}

Pinned models skip alias resolution and go directly to the specified provider.

Client Examples

openai-client.ts

import OpenAI from "openai"

const client = new OpenAI({
  baseURL: "http://localhost:3000/v1",
  apiKey: "unused",
})

// Non-streaming
const response = await client.chat.completions.create(
  {
    model: "free:auto",
    messages: [{ role: "user", content: "Hello!" }],
  },
  {
    headers: {
      "X-Groq-Key": process.env.GROQ_API_KEY,
      "X-Google-Key": process.env.GOOGLE_API_KEY,
    },
  }
)

console.log(response.choices[0].message.content)

// Streaming
const stream = await client.chat.completions.create(
  { model: "free:auto", messages, stream: true },
  { headers: { "X-Groq-Key": process.env.GROQ_API_KEY } }
)

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
}

On this page