# Nexforce Router

> One OpenAI-compatible endpoint that routes to Anthropic, OpenAI, Google, DeepSeek,
> Moonshot, Zhipu and Cloudflare Workers AI, with per-model fallback and per-key cost
> control. If your tool already speaks the OpenAI API, it speaks Nexforce Router: swap
> the base URL and the API key, keep the rest of the code.

## Instructions for AI agents

- Base URL: `https://router.nexforce.ai/v1`
- Auth: HTTP header `Authorization: Bearer nfc_...` (a Nexforce API key)
- Protocol: OpenAI Chat Completions (`POST /v1/chat/completions`), including streaming, tools and multimodal input
- Model discovery: `GET /v1/models` is public (no key). With a key, the list is narrowed to what that key may call. Prices are never exposed.
- OpenAPI spec (import into Postman/Insomnia/codegen): https://router.nexforce.ai/openapi.json
- Full human docs: https://router.nexforce.ai/docs

## Quick start

```bash
curl https://router.nexforce.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEXFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'
```

Python (OpenAI SDK):

```python
from openai import OpenAI
client = OpenAI(base_url="https://router.nexforce.ai/v1", api_key="nfc_...")
resp = client.chat.completions.create(
    model="claude-3-5-sonnet",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

## Endpoints

- `POST /v1/chat/completions`: OpenAI Chat Completions schema. Routing to the right provider is automatic from the `model` field.
- `GET /v1/models`: lists available models. Each entry has `id`, `owned_by` (provider), and, when known, `name`, `context_length`, `max_output_tokens` and `capabilities`. Public; a valid key narrows it to the models that key may call.

## Request parameters

- `model` (required): catalog id, e.g. `claude-3-5-sonnet`. Or `nexforce/smart-route` to let Nexforce pick (see below).
- `messages` (required): OpenAI array (`system`, `user`, `assistant`, `tool`).
- `stream`: `true` for Server-Sent Events (OpenAI `chat.completion.chunk` deltas, terminated by `data: [DONE]`).
- `temperature`, `top_p`, `max_tokens`, `stop`, `frequency_penalty`, `presence_penalty`.
- `tools`, `tool_choice`: OpenAI function calling, on models that support tools.
- Multimodal: `image_url` content blocks for vision; `file` blocks (base64 `file_data`) for PDFs, on models that support them.

## nexforce/smart-route

Pass `"model": "nexforce/smart-route"` instead of naming a model and Nexforce picks one for you. The router resolves it to a reference (anchor) model and, when a cheaper equivalent with the same capabilities exists, serves the equivalent; otherwise it serves the anchor. The model that actually answered is always disclosed in the response headers.

## Response headers

- `X-Nexforce-Requested-Model`: the model you asked for.
- `X-Nexforce-Served-Model`: the model that actually answered.
- `X-Nexforce-Substituted`: `true` when Smart Routing swapped the model.
- `X-Nexforce-Smart-Route`: `true` when the request used `nexforce/smart-route`.
- `X-Config-Synced-At`: timestamp of the config snapshot used.

## Smart Routing (per-request control)

When Smart Routing is enabled on your config, the router can swap the requested model for a cheaper equivalent before dispatch, preserving needed capabilities. Override per request:

- `X-Nexforce-Smart-Routing: off` — disable for this request (also accepts `false`, `0`).
- `X-Nexforce-Pin-Model: true` — force exactly the requested model, no substitution.

## Agent attribution

Tag a request with the agent that originated it, to split cost and volume per agent in the Console:

- Header `X-Nexforce-Agent: support-bot`, or
- Header `X-Nexforce-Metadata: {"agent":"support-bot"}` (also accepts `agent_label`, `_agent`).

## Error codes

- `401` missing/invalid key
- `402` insufficient wallet balance (recharge at payments.nexforce.ai)
- `403` model/provider blocked for this key, or account suspended
- `404` model not in the catalog
- `429` rate limit or budget exceeded
- `5xx` provider failure (triggers per-model fallback when configured)

Error bodies follow the OpenAI error format, so OpenAI SDK error handling works unchanged.

## Editor / agent integrations

- Cursor: Settings -> Models -> OpenAI API Key, override base URL with `https://router.nexforce.ai/v1`, add model ids manually.
- Cline / Roo Code: provider "OpenAI Compatible", base URL `https://router.nexforce.ai/v1`; the model picker populates from `/v1/models`.
- Continue: `provider: openai`, `apiBase: https://router.nexforce.ai/v1`.
- OpenCode: `@ai-sdk/openai-compatible` with `baseURL: https://router.nexforce.ai/v1`.