Your first routed request.

Get a key

Self-service signup is closed during the private beta. Email request beta access and we will provision an organisation, a wallet and a key with the daily and monthly spend caps you ask for.

Keys are organisation-scoped and authenticate as a bearer token. Keep them server-side — never ship a catwalk_ key in a browser or mobile client.

Authorization: Bearer catwalk_<48 hex chars>

Repoint your SDK

No Catwalk SDK exists and none is needed. Set the base URL to https://api.aicatwalk.app/v1 and pass your key. model: "auto" lets Catwalk choose; an explicit provider/model id pins the choice.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CATWALK_API_KEY,
  baseURL: "https://api.aicatwalk.app/v1",
});

const resp = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Summarise this contract in 3 bullets." }],
  // Unknown fields are forwarded as-is; `catwalk` is Catwalk's routing block.
  catwalk: {
    objective: "best_value",
    task: "summarisation",
    max_cost_usd: 0.01,
  },
} as any);

console.log(resp.choices[0].message.content);
console.log((resp as any).catwalk); // receipt_id, selected_model, provider, actual_cost_usd, ...

Python: pass the same block through extra_body.

Or skip the SDK

The same request, without a dependency:

curl https://api.aicatwalk.app/v1/chat/completions \
  -H "Authorization: Bearer $CATWALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Summarise this contract in 3 bullets."}],
    "catwalk": {"objective": "best_value", "task": "summarisation", "max_cost_usd": 0.01}
  }'

Steer the routing

Every field in the catwalk block is optional. Together they are the constraint set the router filters the catalog against.

objective

lowest_cost, best_value (default), highest_quality or lowest_latency.

task

Task type for scorecard-driven routing — for example structured_json or code_generation.

max_cost_usd

Hard cap on this request's estimated cost. Over it, the request is rejected with 400 max_cost_exceeded and nothing is debited.

quality_floor

Minimum quality score, 0 to 1. Models below it are ineligible.

sensitivity

public, internal or confidential — constrains which providers may see the request.

Read the receipt

The response carries a catwalk block with receipt_id, the selected model, the routing reason and estimated versus actual cost. Fetch the full receipt — scored candidates, fallback attempts, the wallet debit — any time.

curl https://api.aicatwalk.app/v1/receipts/$RECEIPT_ID \
  -H "Authorization: Bearer $CATWALK_API_KEY"

Receipts are organisation-scoped: a key reads only its own org's.