# Router Documentation

> Build with open models through one familiar API. Explore the guides, choose your model, and make your first connection.

- [Quickstart](https://router.optimai.network/docs/quickstart.md): Send your first Router request.
- [API reference](https://router.optimai.network/docs/api/chat-completions.md): Review request parameters and response formats.
- [Models and availability](https://router.optimai.network/docs/models-and-availability.md): Choose a configured model and understand live capacity.
- [Become a provider](https://router.optimai.network/docs/providers/getting-started.md): Share a supported model through Core Node.

## How the pieces fit

Your application talks only to Router. Router checks each request, selects eligible capacity, and relays the provider's output back to you.

1. **Your application**: Sends OpenAI-compatible requests from your server with a Router API key.
2. **Router API**: Validates the request, reserves credits, selects eligible capacity, and relays output.
3. **Provider computers**: Core Node computers run the selected open model and return ordered output.

## Your model, your code

Use an OpenAI client or a simple HTTP request. Choose a supported model, send a message, and receive a complete answer or stream it into your application.

### cURL

```bash
ROUTER_REQUEST_ID="$(uuidgen)" # Reuse this ID if you retry the same request.
curl "$ROUTER_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -H "Idempotency-Key: $ROUTER_REQUEST_ID" \
  -H "X-Max-Charge-Credits: 5.000000" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma3:1b",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'
```

### Python

```python
import os
from uuid import uuid4
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["ROUTER_BASE_URL"],
    api_key=os.environ["ROUTER_API_KEY"],
)

request_id = str(uuid4()) # Reuse this ID if you retry the same request.
response = client.chat.completions.create(
    model="gemma3:1b",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "Idempotency-Key": request_id,
        "X-Max-Charge-Credits": "5.000000",
    },
)

print(response.choices[0].message.content)
```

### TypeScript

```typescript
import OpenAI from "openai";
import { randomUUID } from "node:crypto";

const client = new OpenAI({
  baseURL: process.env.ROUTER_BASE_URL,
  apiKey: process.env.ROUTER_API_KEY,
});

const requestId = randomUUID(); // Reuse this ID if you retry the same request.
const response = await client.chat.completions.create({
  model: "gemma3:1b",
  messages: [{ role: "user", content: "Hello!" }],
}, {
  headers: { "Idempotency-Key": requestId, "X-Max-Charge-Credits": "5.000000" },
});

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

Set `ROUTER_BASE_URL` to the endpoint shown in [Developer API](/dashboard/developers), including `/v1`. Keep `ROUTER_API_KEY` in your server environment.

## A few useful starting points

[**How Router works**](https://router.optimai.network/docs/how-router-works.md): Follow a request from your application to an available provider.

[**OpenAI compatibility**](https://router.optimai.network/docs/openai-compatibility.md): See the exact endpoints, parameters, and SDK behavior supported today.

[**SDK recipes**](https://router.optimai.network/docs/sdk/typescript.md): Build with cURL, Python, or TypeScript using complete examples.

[**Security & privacy**](https://router.optimai.network/docs/security-and-privacy.md): Protect keys and understand where provider inference runs.

## Build a reliable integration

* [Choose a model](https://router.optimai.network/docs/models-and-availability.md) and validate its current edition limits.
* Use Auto or [choose a provider](https://router.optimai.network/docs/choosing-a-provider.md) at a reviewed pricing revision.
* [Design messages](https://router.optimai.network/docs/message-design.md) that stay within the supported text surface.
* [Stream responses](https://router.optimai.network/docs/streaming.md) while preserving clear completion and error states.
* Add [bounded retries and cancellation](https://router.optimai.network/docs/retries-and-timeouts.md).
* Correlate failures with [usage and observability](https://router.optimai.network/docs/usage-and-observability.md).
* Parse the complete [error response contract](https://router.optimai.network/docs/api/errors.md).

> **Start with the supported API**
> The developer API supports model listing and paid text chat completions, including streaming and optional public offer selection. API keys require explicit paid opt-in; provider eligibility uses ownership, model, pricing, and capacity checks without administrator approval. Other modalities, tool calls, MCP, x402, and external payments remain outside this supported surface.