<!-- OpenSmartRoute: Platform quickstart. https://opensmartroute.ai/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://opensmartroute.ai/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.

```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}'
```

```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://opensmartroute.ai/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`.

## 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 (**pro** plan and above):

```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`) and the OpenAI-compatible endpoint, metered against a
monthly quota. Learning from feedback and server-side execution of non-LLM targets start on the
**pro** plan.
:::
:::accordion[Do I bring my own provider keys?]
Yes. The platform routes and meters; you connect your own provider credentials so the answer is
billed to you by the provider and never leaves your account boundary.
:::
:::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://opensmartroute.ai/docs/QUICKSTART_SDK.md) or [Deploy with Docker and Helm](https://opensmartroute.ai/docs/deploy.md).
:::
::::

## Where next

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