Start in one prompt.

Quickstart#

npx -y scaledthought@0.3 init --region us

npx -y scaledthought@0.3 billing topup --amount-usd 20

curl "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash",
    "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 (Canada's https://api.ca.scaledthought.com/v1 is coming soon).

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 npx -y scaledthought@0.3 models --live or /pricing.

curl "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash",
    "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="deepseek-v4-1-flash",
    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. Models that support tool calling return standard tool_calls. Support and quality vary by model, so check a model's card before relying on it.

resp = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    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. On models that support it, output is constrained to the schema during decoding. Validate the result before relying on it.

resp = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    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"],
        }},
    },
)

Responses API & Codex#

POST $ST_BASE_URL/responses speaks the OpenAI Responses API, so clients that use only that protocol, such as Codex, can use ScaledThought as their model provider. It takes input (a string, or messages, function_call and function_call_output items), instructions, function and custom (freeform) tools, tool_choice, max_output_tokens, text.format for JSON output and stream: true (Responses events, ending with response.completed or response.incomplete with its usage, or response.failed with an error).

It is stateless. We store no responses, so send the whole conversation in input every turn (Codex does) and leave out previous_response_id, which returns 400 invalid_request; store is always false. Hosted tools such as file search return 400; a web search tool is ignored. Requests without max_output_tokens get a cap of what the model's context leaves after your prompt, at most 32,768 tokens.

Billing is the same as chat completions: per token, from the usage the model server reports, paid from your credits.

# ~/.codex/config.toml
model = "deepseek-v4-1-flash"  # or a model id from `npx -y scaledthought@0.3 models --live`
model_provider = "scaledthought"

[model_providers.scaledthought]
name = "ScaledThought"
base_url = "https://api.us.scaledthought.com/v1"  # your ST_BASE_URL
env_key = "ST_API_KEY"
wire_api = "responses"
model_catalog_url = "https://api.us.scaledthought.com/v1/codex/models"  # same host (and region) as base_url

Codex reads ST_API_KEY from the environment, so load ./.env into the shell first. wire_api = "responses" is required: ScaledThought serves Codex over the Responses API.

model_catalog_url tells Codex the context windows of the models live in your region, so it compacts long sessions in time, and gives it its apply_patch editing tool. It is built from the live models on every request; Codex sends your key with it, so keep it on the same host as base_url (your region's).

Models & benchmarks#

GET /v1/models lists the model ids live in your region, in OpenAI's format. That list is the truth about what you can call. 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 and filter, use npx -y scaledthought@0.3 models --live or the MCP tool models_search. For people, /pricing lists every model live in the US with its price, from the same API.

curl "$ST_BASE_URL/models"
curl "$ST_BASE_URL/models/deepseek-v4-1-flash"

Regions & retention#

Every key is pinned to its region. The US region is open now; Canada (ca) is coming soon; its API doesn't answer until it opens. Requests are served and logged, and account and usage records stored, only in that country. Card payments for every region are processed by Stripe in the US. Prompts and completions are not stored after the response is returned, and are never used for training. Batch and fine-tuning files are erased after 30 days, or sooner with DELETE /v1/files/{id}. Every response carries x-st-region and x-st-data-retention: none. See security (or /security.json) and the Privacy Policy.

Keys & budgets#

Agents can create scoped keys with hard daily spending limits. When a budget is hit, calls return 402 instead of spending more. A revoked key stops working within about 30 seconds.

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

Scopes are inference, read, keys, billing. A key can only give a new key scopes it has itself (otherwise 403 scope_not_allowed). Expiry: send expires_in (like "30d") or expires_at, up to 365 days; after that the key gets 401 key_expired. A key never outlives the key that created it.

Sub-agent keys: with child: true the new key records the calling key as its parent. Its daily budget fits in what the parent has left today, its rate limits and expiry are no higher than the parent's, and it can manage only its own sub-keys. Revoking a key revokes every key below it.

Rotation: POST /v1/keys/{id}/rotate mints a replacement with the same name, scopes, budget and limits, returned once. The old key keeps working for grace (default 24h, "0" to "7d"). Self-revocation: DELETE /v1/keys/self revokes the calling key and its sub-agent keys, with no scope needed, so an agent that suspects a leak can act at once.

npx -y scaledthought@0.3 keys create --name sub-agent --child --scopes inference --budget-usd 2 --expires-in 12h
npx -y scaledthought@0.3 keys rotate key_… --grace 24h
npx -y scaledthought@0.3 keys revoke-self

More on how keys and data are protected: security.

Credits & approval#

Usage is paid from prepaid credits, $20 to $2,000 per top-up, at most $2,000 per 24 hours and 2 open approval links at a time. The agent asks for a top-up ($20 by default) and gets back an approval_url: a funding page where its human confirms or changes the amount, can turn on auto-reload, and pays by card. The credits land once the payment is confirmed, and we email a receipt. Nothing is ever charged without that approval. Credits don't expire. When they run out, requests return 402 insufficient_credits with the balance and the amount needed.

npx -y scaledthought@0.3 billing topup --amount-usd 20

Auto-reload is optional and recommended: when the balance drops below a threshold (default $5), the saved card adds a set amount (default $20), so the agent never stalls. The human turns it on on the funding page of any top-up, or without buying anything through an auto-reload setup link (billing auto-reload setup), where they save a card. Loads are limited to $2,000 per 24 hours. Turning it on or raising any limit needs a new approval; turning it off or lowering it doesn't. If a reload is declined, auto-reload switches itself off and the next 402 tells the agent to get a new link. billing status shows the balance and any pending top-ups; billing transactions lists every purchase, reload and charge.

npx -y scaledthought@0.3 billing topup --amount-usd 20 --auto-reload-below 5 --auto-reload-amount 20
npx -y scaledthought@0.3 billing auto-reload setup --below 5 --amount 20   # no purchase: they save a card
npx -y scaledthought@0.3 billing auto-reload off

Notices & webhooks#

Responses can carry x-st-notice with comma-separated codes: low_balance (a paid account whose balance is under $5). An agent that sees one should tell its human what to approve. GET /v1/account, MCP account_status,status and doctor show the same codes with the words to relay.

Webhooks push the same signals instead: balance.low, key.expiring and budget.exhausted. Endpoints must be public https URLs on port 443. Each POST carries x-st-signature: t=…,v1=…, an HMAC-SHA256 of <t>.<raw body> keyed with the endpoint's signing secret, which is shown once when you add it. Deliveries go to your URL wherever it is hosted, even outside your account's region, and carry only id, type, created_at, region, account_id and data: ids, integer micro-dollar amounts, day counts and timestamps, never prompts, names or emails. data per event: balance.low {balance_micros, threshold_micros}, key.expiring {key_id, expires_at}, budget.exhausted {scope, key_id, budget_micros, spent_today_micros, resets_at}. Failed deliveries are retried with backoff for about two days.

npx -y scaledthought@0.3 webhooks add https://hooks.example.com/st --events balance.low,budget.exhausted

Optional request headers: x-st-app names your app in usage records (not published), and x-st-session keeps one conversation on the same replica so its cached prefix is reused (memory only, never stored). In Canada, requests never overflow to another country: when every replica of a model is busy a request waits briefly, then gets 429 capacity_exhausted with Retry-After.

Batch inference#

Upload a JSONL file of requests and get results at 50% of the normal price. Batches run in a 24-hour completion window and typically finish within it, but finishing in time isn't promised. The Files and Batches endpoints follow OpenAI's, so client.batches.create works. Every line is validated up front, so a bad file fails within seconds.

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 (find one with models --live --modality embedding). Input can be a string or an array of strings.

vecs = client.embeddings.create(model="<embedding-model-id>", 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. Only base models running on our own GPUs in your region can be trained, and adapters can't be downloaded. Training is billed per 1M training tokens (dataset tokens × epochs); the job response includes an estimate before anything runs. Paid from prepaid credits. See pricing.

f = client.files.create(file=open("examples.jsonl", "rb"), purpose="fine-tune")
job = client.fine_tuning.jobs.create(model="<base-id>", 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 (Canada's https://api.ca.scaledthought.com/mcp is coming soon; 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@0.3 init or POST /v1/accounts first, then npx -y scaledthought@0.3 mcp prints the exact command and config for your region. The agent gets these tools:

npx -y scaledthought@0.3 mcp

CLI#

Run it as npx -y scaledthought@0.3 <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. Until the account's first credit purchase, 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.