Start in one prompt.

Quickstart

npx -y scaledthought@latest init --region us   # or --region ca

curl "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Authentication

Send your key as a bearer token. Keys are scoped to one region and can carry their own budget. The base URL is your region's host, saved to .env as ST_BASE_URL: https://api.us.scaledthought.com/v1 or https://api.ca.scaledthought.com/v1.

Authorization: Bearer $ST_API_KEY
Content-Type: application/json

Chat completions

POST /v1/chat/completions accepts the OpenAI request shape. Use a model id from /models or "auto" to let the router choose.

curl "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Streaming

Set stream: true to receive server-sent events in the OpenAI delta format.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Write a haiku about open weights"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Tool calling

Pass tools in the OpenAI format. Open models each use a different native tool-call syntax. We normalize all of them, so you always get back standard tool_calls.

resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Weather in Toronto?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        },
    }],
)
print(resp.choices[0].message.tool_calls)

Structured output

Use response_format with a JSON schema. Output is constrained during decoding, so it always parses.

resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": invoice_text}],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "invoice", "schema": {
            "type": "object",
            "properties": {"vendor": {"type": "string"}, "total": {"type": "number"}},
            "required": ["vendor", "total"],
        }},
    },
)

Router

Set model: "auto" and an optional quality_floor between 0 and 1 (default 0.8). The router picks the cheapest model expected to clear the floor for that request. You're billed at the chosen model's price, with no router fee.

{
  "model": "auto",
  "quality_floor": 0.85,
  "messages": [{ "role": "user", "content": "..." }]
}

Read more on the router page.

Models & benchmarks

GET /v1/models lists the model ids live in your region, in OpenAI's format. GET /v1/models/{id} returns one model's pricing, context length, release date, benchmark scores and live status, so an agent can choose without a human reading a web page. To search the whole catalog, use npx -y scaledthought@latest models or the MCP tool models_search.

curl "$ST_BASE_URL/models"
curl "$ST_BASE_URL/models/mimo-v2-6-pro"

Regions & retention

Every key is pinned to us or ca. Requests are served, logged and billed only in that country. Prompts and completions are not stored after the response is returned, and are never used for training. See security.

Keys & budgets

Agents can create scoped keys with hard daily spending limits. When a budget is hit, calls return 402 instead of spending more. On the free tier a key's budget can't exceed the $1/day account cap.

npx -y scaledthought@latest keys create --name support-bot --budget-usd 40

Billing & approval

Every account starts on the free tier with no card. To go further, the agent asks for an upgrade with a monthly cap and gets back an approval_url. It sends that link to its human, who adds a card and approves the cap. Nothing is ever charged beyond it. Lowering the cap needs no approval.

npx -y scaledthought@latest billing upgrade --monthly-cap-usd 50

Batch inference

Upload a JSONL file of requests and get results within 24 hours at 50% of the normal price. The Files and Batches endpoints match OpenAI's, so client.batches.create works unchanged. Every line is validated up front, so a bad file fails in seconds, not hours.

batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
    input_file_id=batch_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
# later
batch = client.batches.retrieve(batch.id)
results = client.files.content(batch.output_file_id).text

Embeddings

POST /v1/embeddings with an embedding model such as qwen3-embedding-8b. Input can be a string or an array of strings.

vecs = client.embeddings.create(model="qwen3-embedding-8b", input=["open weights", "served hot"])

Fine-tuning

Train a LoRA adapter on your own examples. The result is a private model id that only your account can call, served on the same replicas as its base model and billed at the base model's per-token price. Training is billed per 1M training tokens (dataset tokens × epochs); the job response includes an estimate before anything runs. Needs a paid plan. See pricing.

f = client.files.create(file=open("examples.jsonl", "rb"), purpose="fine-tune")
job = client.fine_tuning.jobs.create(model="qwen3-8-27b", training_file=f.id, suffix="triage")
# poll
job = client.fine_tuning.jobs.retrieve(job.id)
resp = client.chat.completions.create(model=job.fine_tuned_model, messages=[...])

MCP server

Remote MCP on your region's API host: https://api.us.scaledthought.com/mcp or https://api.ca.scaledthought.com/mcp (Streamable HTTP, 2026-07-28 spec). Authenticate with your API key as a bearer token. MCP can't create accounts: sign up with npx -y scaledthought@latest init or POST /v1/accounts first, then npx -y scaledthought@latest mcp prints the exact command and config for your region. The agent gets these tools:

npx -y scaledthought@latest mcp

CLI

Run it as npx -y scaledthought@latest <command>. Output is JSON whenever stdout isn't a terminal (or with --json), and errors are one JSON line on stderr with code, message and hint. Nothing prompts. Keys come from ST_API_KEY or ./.env, never from flags.

API reference

Rate limits

Limits are per key. Over the limit, calls return 429 rate_limit_exceeded with a Retry-After header in seconds. Free keys can lower their limits but not raise them.

Errors

API errors are {"error":{"message","type","code"}}. CLI errors add a hint and exit non-zero.