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 and in the REST API reference at /docs/api.

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 with GitHub, Google, Microsoft or an email address. Signup creates a personal workspace on the free plan and issues an API key.

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

Authorization: Bearer osr_...
X-API-Key: osr_...

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.

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

{
  "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.

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.

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)

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, with the price your workspace pays per million tokens, and in GET /v1/models under its catalogue id (openai/gpt-4.1-mini).

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 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):

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

Where next

• Platform guide - authentication, organizations, tenants, budgets, traces, errors.
• MCP server and cost estimates - put the router inside VS Code, Cursor or Claude.
• Marketplace - shared agents, skills, personas, prompts and stack templates.
• Python SDK quickstart - the same router as a zero-dependency library.