Installation
Clone, install, and run the FreeRouter API server. Make your first completely free ($0 cost) request with cURL.
@freerouter/api is a completely free ($0 cost) HTTP API server wrapping @freerouter/sdk behind OpenAI-compatible endpoints. Routes exclusively across free providers. Built with Hono, runs on Bun.
Prerequisites
| Requirement | Details |
|---|---|
| Runtime | Bun 1.0+ |
| Repository | Clone github.com/r2hu1/freerouter |
| API Key | At least one provider API key |
Installation
git clone https://github.com/r2hu1/freerouter.git
cd freerouter
bun installQuickstart
1. Start the server
bun run apps/api/src/index.tsDefault port
Server starts on http://0.0.0.0:3000. Override: PORT=8080 bun run apps/api/src/index.ts.
2. Make your first request
curl http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-H "X-Groq-Key: gsk_..." \
-d '{
"model": "free:auto",
"messages": [
{"role": "user", "content": "Hello! Who are you?"}
]
}'3. Check server health
curl http://localhost:3000/health{
"status": "ok",
"providers": {}
}BYOK headers
Provider API keys go in HTTP headers, not the request body. See Auth Reference.
Available Endpoints
| Method | Path | Description |
|---|---|---|
GET | /health | Server and provider health |
GET | /v1/models | List all models and aliases |
POST | /v1/chat/completions | Chat completion (streaming optional) |
OpenAI compatible
All endpoints use OpenAI-compatible request/response formats. See Routes for full schemas.