API Reference

OpenAI-Compatible REST API

Site proxy base URL: https://your-site.example/api

Authentication

Site proxy requests require a Better Auth session or user API key in the Authorization header. The proxy forwards only its private gateway key. Direct gateway deployments instead require the server-level ROUTER_API_KEY. Usage history is available at /api/usage for authenticated users.

Authorization: Bearer router_user_...

Endpoints

POST/api/v1/chat/completions

Create a chat completion with any model

Parameter	Type	Required	Description
model	string	Yes	Model ID, e.g. openai/gpt-4o
messages	array	Yes	Array of message objects
temperature	number	No	0–2, default 1
max_tokens	integer	No	Max output tokens
stream	boolean	No	Stream response via SSE
response_format	object	No	JSON mode: { type: "json_object" }

POST/v1/completionsRoadmap

Legacy text completions (planned; chat completions are available now)

Parameter	Type	Required	Description
model	string	Yes	Model ID
prompt	string	Yes	Input text
max_tokens	integer	No	Max output tokens

GET/api/v1/models

List all available models

POST/api/v1/embeddingsRoadmap

Generate text embeddings (planned)

Parameter	Type	Required	Description
model	string	Yes	Embedding model ID
input	string	Yes	Text to embed

GET/api/usage

Recent usage for the authenticated Better Auth user (same-origin control-plane route)

Parameter	Type	Required	Description
limit	integer	No	Number of records to return, capped at 100

Example

Request

POST /api/v1/chat/completions
Authorization: Bearer router_user_...

{
  "model": "openai/gpt-4o",
  "messages": [
    {"role": "user", "content": "Hi"}
  ]
}

Response (200)

{
  "id": "chatcmpl_abc123",
  "model": "openai/gpt-4o",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 7,
    "total_tokens": 15
  }
}

Back to Docs