ClawSwitch Documentation

§Overview

ClawSwitch is an intelligent LLM proxy gateway. It sits between your AI agents and LLM providers, analyzing each request, picking the best model/provider combination, handling failover, and tracking every dollar — so you ship faster and spend less.

§Quick Start

Get running in 3 steps — no installation needed.

1. 1Pick a plan — Go to Pricing and select Starter, Pro, or Enterprise.
2. 2Create your account — You'll be redirected to the Dashboard. Sign up with email and password, then complete checkout.
3. 3Create an agent & get your API key — In the Dashboard, go to Agents → Create Agent. Name it (e.g., "chatbot"), copy the generated API key — it's shown only once.

Your first request

curl https://api.clawswitch.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Set model: "auto" and ClawSwitch picks the best model. Or specify a model name to force it.

§How It Works

Every request to POST /v1/chat/completions flows through this pipeline:

1. 1Auth — Verify your agent API key
2. 2Cache — Exact or semantic match? → return instantly at $0
3. 3Score — Analyze request complexity
4. 4Route — Pick cheapest model for that complexity tier
5. 5Guard — Check budget limits, token limits, blocked models
6. 6Key Pool — Select best available API key for the provider
7. 7Execute — Call the provider with automatic fallback chain
8. 8Track — Log tokens, cost, savings
9. 9Respond — Return OpenAI-format response + cost headers

Every response includes cost metadata headers:

X-clawswitch-Cost:    $0.000142   ← what you paid
X-clawswitch-Saved:   $7.533000   ← what you saved vs default model
X-clawswitch-Model:   claude-haiku-4-5-20251001
X-clawswitch-Cache:   miss
X-clawswitch-Tier:    simple

§Smart Routing

When you set model: "auto", ClawSwitch's proprietary routing engine analyzes each request and selects the optimal model for quality and cost. Requests are classified into tiers:

The router also detects task domains (code, reasoning, chat, writing) and applies domain-specific model preferences. Each tier has a fallback chain — if the primary model fails, the request cascades to the next model automatically.

Guardrails

Configure safety limits on routing from the Dashboard Switch page:

• •Max cost per request — Reject requests that would exceed a cost threshold
• •Max input tokens — Reject inputs that are too long
• •Allowed tiers — Restrict which routing tiers can be used
• •Blocked models — Prevent specific models from being selected

§API Key Pool

Add multiple API keys per provider. ClawSwitch automatically rotates between them when one gets rate-limited — zero downtime for your agents.

• •Keys are tried in priority order (lower number = preferred)
• •Same-priority keys rotate round-robin for even distribution
• •Rate-limited keys are cooled down with exponential backoff
• •When all keys for a provider are exhausted, email alert is sent

Manage keys in the Dashboard under Settings → API Key Pool:

§Caching

Identical or semantically similar requests are served from cache — $0 cost, instant response.

§Budget Controls

Set daily and monthly spend limits per agent to prevent runaway costs. Manage budgets in the Dashboard Budget page.

Each agent shows a progress bar with current spend vs. limit, plus savings amount. Budget alerts notify you before limits are hit.

§Dashboard Guide

The Dashboard is your control center. Access it at app.clawswitch.com.

Home (Analytics)

• •Today's Spend — Total cost of all requests today
• •Today's Saved — Amount saved vs. Claude Sonnet baseline
• •Request Count — Total requests processed today
• •Cache Hit Rate — Percentage served from cache

Agents

1. 1. Click Create Agent
2. 2. Enter a name (e.g., "code-reviewer", "chatbot", "research-agent")
3. 3. Optionally set a daily budget limit
4. 4. Copy the generated API key — shown only once

Logs

§Playground

Test the complete proxy pipeline from the Dashboard. Send real requests through the same routing, key pool, and fallback chain your agents use — inspect every detail.

Analyze (Routing Only)

Click Analyze to see how a message would be routed without executing:

• •Complexity score and breakdown by factor
• •Tier classification and domain detection
• •Selected model, provider, and full fallback chain
• •Guardrail violation warnings

Run (Full Execution)

Click Run to send the message through the complete pipeline. Results across four tabs:

§SDK & Framework Integration

ClawSwitch is 100% OpenAI-compatible. Any SDK or tool that talks to OpenAI can point at ClawSwitch. Just change the base URL and API key.

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.clawswitch.com/v1",
    api_key="YOUR_API_KEY",  # from Dashboard → Agents
)

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    temperature=0.7,
)
print(response.choices[0].message.content)

Streaming:

stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Write a short poem"}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

Node.js / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.clawswitch.com/v1",
  apiKey: "YOUR_API_KEY",
});

const response = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);

cURL

curl https://api.clawswitch.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "What is 2+2?"}]
  }'

LangChain

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="https://api.clawswitch.com/v1",
    api_key="YOUR_API_KEY",
    model="auto",
)
response = llm.invoke("Explain microservices in simple terms")

LlamaIndex / AutoGen

# LlamaIndex
from llama_index.llms.openai_like import OpenAILike
llm = OpenAILike(api_base="https://api.clawswitch.com/v1", api_key="YOUR_API_KEY", model="auto")

# AutoGen
config_list = [{"model": "auto", "base_url": "https://api.clawswitch.com/v1", "api_key": "YOUR_API_KEY"}]

Cursor / Continue / AI Code Editors

Request Format

Response Headers

§API Reference

Proxy Endpoint

POST https://api.clawswitch.com/v1/chat/completions
Authorization: Bearer <your-api-key>

OpenAI-compatible chat completions with streaming support.

Management API

All management endpoints require JWT authentication (handled by the Dashboard automatically).

Error Codes

§Available Models

View all models with live pricing on the Dashboard Models page. To force a model, set it as the model value instead of "auto".

§Cost Savings

Example: Single agent (8h/day active)

Actual savings depend on your request mix. Check Home in the Dashboard for real-time savings tracking.

§Plans & Pricing

All plans include smart routing, API key pool, fallback chains, cost tracking, and the full dashboard. You only pay for tokens used with your own provider API keys — ClawSwitch doesn't mark up provider costs.