<!-- OpenSmartRoute: Platform quickstart. https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/QUICKSTART_PLATFORM -->
# Platform quickstart

Route your first request through the hosted platform in about five minutes: create a workspace, get
an API key, ask the router for a decision, let it execute the answer, and report how it went. Every
call shown here is documented in full in the [platform guide](https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/PLATFORM.md) and in the REST API
reference at `/docs/api`.

```mermaid
flowchart LR
    APP["Your app (OpenAI client, model=auto)"] --> API["POST /v1/chat/completions"]
    API --> AUTH["API key, plan, quota and budget"]
    AUTH --> RT["Router.route()"]
    RT --> EXE["Chosen provider or target executes"]
    EXE --> RESP["Answer + X-OSR-Target + token usage"]
    RESP --> LOOP["Metered, traced, learners updated"]
```

## 1. Create a workspace and an API key

Sign up at [opensmartroute.ai/platform/signup](https://opensmartroute.ai/platform/signup) with
GitHub, Google, Microsoft or an email address. Signup creates a personal workspace on the **free**
plan and issues an API key.

:::warning[The API key is shown once]
Copy it into a secret manager immediately - it cannot be retrieved again later. You can create,
rename, rotate and revoke more keys on the keys page of the dashboard at any time.
:::

Authenticate with either a copied key or the CLI browser hand-shake:

::::tabs
:::tab[API key header]
Send the key with every request in either header:

```http
Authorization: Bearer osr_...
X-API-Key: osr_...
```
:::
:::tab[CLI sign-in]
```bash
curl -LsSf https://opensmartroute.ai/install.sh | sh   # Windows: irm https://opensmartroute.ai/install.ps1 | iex
osr login        # opens the browser, mints a key for this machine
osr whoami       # workspace, plan, edition behind the stored credential
```
:::
::::

## 2. Route a request

`POST /api/v1/route` returns a decision: the chosen target, the confidence, ranked alternatives, the
signals the router extracted and a human-readable explanation. Nothing is executed yet. The examples use the
hosted API origin `https://api.opensmartroute.ai`; the site origin (`https://opensmartroute.ai/api/v1/...`, the form
the dashboard's quick-start card shows) answers the same requests, and a self-hosted deployment uses its own URL.

::::tabs
:::tab[curl]
```bash
curl -s https://api.opensmartroute.ai/api/v1/route \
  -H "Authorization: Bearer $OSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Prove that sqrt(2) is irrational.", "top_k": 3}'
```
:::
:::tab[TypeScript]
```bash
npm install @opensmartroute/sdk
```

```ts
import { OpenSmartRoute } from "@opensmartroute/sdk";

const osr = new OpenSmartRoute({ baseUrl: "https://opensmartroute.ai", apiKey: process.env.OSR_API_KEY! });
const decision = await osr.route({ text: "Prove that sqrt(2) is irrational.", top_k: 3 });
console.log(decision.target.id, decision.confidence, decision.explanation);
```
:::
:::tab[Python]
```bash
pip install opensmartroute
```

```python
import os, httpx

r = httpx.post(
    "https://api.opensmartroute.ai/api/v1/route",
    headers={"Authorization": f"Bearer {os.environ['OSR_API_KEY']}"},
    json={"text": "Prove that sqrt(2) is irrational.", "top_k": 3},
)
print(r.json()["target"]["id"], r.json()["confidence"])
```
:::
::::

```json
{
  "request_id": "7f3c...",
  "target": {"id": "llm-frontier", "kind": "llm", "name": "Frontier model"},
  "confidence": 0.81,
  "alternatives": [{"id": "llm-mid", "kind": "llm", "utility": 0.62}],
  "signals": {"complexity": 0.74, "domains": ["math"], "reasoning_need": 0.9, "contains_pii": false},
  "explanation": "llm-frontier: high reasoning need, math domain, quality weight dominates ..."
}
```

Two request fields cover most needs:

- `objective` trades quality, cost and latency per request: `{"objective": {"quality": 1.0, "cost": 0.5}}`
  prefers cheaper targets whenever quality allows.
- `constraints` are hard limits, never traded off: `{"constraints": {"max_cost_per_1k": 0.005,
  "data_boundary": "private"}}` removes every target that stores data less strictly or costs more,
  and the response's `policy_rejections` says which target was dropped and why.

The full field tables - history, context, tenant, kinds, plans - are in the
[platform guide](https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/PLATFORM.md#2-route-a-request).

## 3. Get the answer, not just the decision

The simplest way is the OpenAI-compatible endpoint: point any OpenAI SDK at `/v1` and set `model` to
`auto`. The router chooses the target per request, runs it and returns a standard `chat.completion`
whose `model` field is the target that answered; set `stream: true` and each provider token is
relayed as it arrives.

::::tabs
:::tab[Python]
```python
from openai import OpenAI

client = OpenAI(base_url="https://api.opensmartroute.ai/v1", api_key=OSR_API_KEY)
reply = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Write a haiku about routing."}],
)
print(reply.model)  # the target the router chose, e.g. "llm-small"
print(reply.choices[0].message.content)
```
:::
:::tab[Node.js]
```javascript
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.opensmartroute.ai/v1", apiKey: process.env.OSR_API_KEY });
const reply = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Write a haiku about routing." }],
});
console.log(reply.model);                 // the target the router chose
console.log(reply.choices[0].message.content);
```
:::
:::tab[curl]
```bash
curl -s https://api.opensmartroute.ai/v1/chat/completions \
  -H "Authorization: Bearer $OSR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Write a haiku about routing."}]}'
```
:::
::::

Decision metadata (request id, confidence, alternatives, cost) rides along in an `opensmartroute`
object that other clients ignore. A `models` list makes the router choose among your candidates and
fall back down the list when a target fails. On the **pro** plan and above, `POST /api/v1/route` with
`"execute": true` does the same for any target kind - agents, skills, tools - and returns the output
in `result`.

### Name a model instead of `auto`

Every model the platform sells by the token is on the [storefront](/models?view=offers), with the price your
workspace pays per million tokens, and in `GET /v1/models` under its catalogue id (`openai/gpt-4.1-mini`).

| `model` | The router |
|---|---|
| `"auto"` | chooses across the whole catalogue. |
| `"openai/gpt-4.1-mini"` | chooses among the providers serving that model, by price, health and learned quality. |
| `"openai/gpt-4.1-mini@azure"` | uses that one endpoint. |

```python
reply = client.chat.completions.create(
    model="openai/gpt-4.1-mini",
    messages=[{"role": "user", "content": "Write a haiku about routing."}],
    extra_body={"provider": {"data_collection": "deny", "sort": "price"}},  # optional: steer the endpoint
)
print(reply.model)  # the endpoint that answered: "openai/gpt-4.1-mini@azure"
print(
    reply.model_extra["opensmartroute"]["charge_usd"]
)  # what the call cost you; the same figure lands on the usage row
```

The `provider` object takes `order`, `only`, `ignore`, `data_collection`, `sort` and `max_price`, as on
OpenRouter. The [platform guide](https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/PLATFORM.md#models-by-the-token-offers-prices-credits-and-provider-preferences)
covers the full set, the pay-as-you-go plan, per-key spend limits and how operators list models.

## 4. Report the outcome

The learners (Bradley-Terry, IRT, LinUCB) improve on your own traffic when you tell the platform how
an answer turned out (every plan, the free one included):

```bash
curl -s https://api.opensmartroute.ai/api/v1/feedback \
  -H "Authorization: Bearer $OSR_API_KEY" -H "Content-Type: application/json" \
  -d '{"request_id": "7f3c...", "target_id": "llm-frontier", "success": true, "quality": 0.9}'
```

The dashboard has the same form without curl: expand a row on the activity page and report good or
poor, a quality score and, optionally, the target that would have done better.

## FAQ

::::accordions
:::accordion[What does the free plan include?]
Routing decisions (`POST /api/v1/route`) with the full trace, the OpenAI-compatible endpoint, outcome
feedback and your own provider keys, metered against a monthly quota of 15,000 requests (30 per minute,
2 API keys, 5 seats). Plans (`plan` / `execute` for agents, skills and tools), a bigger quota with overage
instead of a stop, tenants, statistics, audit and SSO come with the paid tiers - see the pricing page or
`GET /api/v1/info`.
:::
:::accordion[Do I bring my own provider keys?]
Yes, on every plan. The platform routes and meters; you connect your own provider credentials under
*Model providers* so the answer is billed to you by the provider and never leaves your account boundary.
:::
:::accordion[Can I pay for models by the token instead?]
Yes. The **pay as you go** plan has no monthly fee and no request quota: buy credits on the billing page and
call any model on the [storefront](/models?view=offers) at the price shown - `model: "openai/gpt-4.1"`
routes among the providers serving it, `"openai/gpt-4.1@azure"` pins one. Requests stop with `402` when the
credits run out; per-key spend limits cap what one integration may charge.
:::
:::accordion[How do I see why a target was chosen?]
Every `POST /api/v1/route` response carries `signals`, `alternatives` and an `explanation`, and
`policy_rejections` lists any target a hard constraint removed. The activity page shows the same
trace per request.
:::
:::accordion[Can I self-host instead?]
Yes. The same router ships as a zero-dependency library and as `osr serve`. Start with the
[Python SDK quickstart](https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/QUICKSTART_SDK.md) or [Deploy with Docker and Helm](https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/deploy.md).
:::
::::

## Where next

- [Platform guide](https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/PLATFORM.md) - authentication, organizations, tenants, budgets, traces, errors.
- [MCP server and cost estimates](https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/MCP.md) - put the router inside VS Code, Cursor or Claude.
- [Marketplace](https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/MARKETPLACE.md) - shared agents, skills, personas, prompts and stack templates.
- [Python SDK quickstart](https://osr-web.kindrock-caaab1a2.centralindia.azurecontainerapps.io/docs/QUICKSTART_SDK.md) - the same router as a zero-dependency library.