# Mouse Decision API (mouse-1)

> mouse-1 is a fast (~100ms) single-pass decision model for agent harnesses. Instead of generating text token by token, it reads a state and evaluates up to 128 typed questions (choice, noul, score) in parallel, returning calibrated probability distributions with Zero Data Retention (Mouse-Data-Retention: none) and $0 output token cost.

## Quick Start for Coding Agents (Cursor, Claude Code, Codex, OpenCode)

- **Base URL**: `https://api.mouse.dev`
- **Primary Endpoint**: `POST https://api.mouse.dev/v1/decisions`
- **Authentication**: `Authorization: Bearer $MOUSE_API_KEY` (keys start with `sk_mouse_`; create keys with $5 free starter credits at `https://www.mouse.dev/console/keys`).
- **Primary Model Alias**: `mouse-1` (or `mouse`), currently resolving to immutable snapshot `mouse-preview-2026-10-13` (16,384 max `state` tokens).
- **Zero Data Retention**: Every response sends `Mouse-Data-Retention: none` and `Cache-Control: no-store`. Request `state` and `questions` are never logged or stored.
- **Pricing**: `$0.10` / 1M input tokens, `$0.00` output tokens. `4xx` errors are never billed.
- **Wire Compatibility**: Wire-compatible with TypeSafe System One (`@typesafe-ai/sdk` / `typesafe-sdk`) and accepts OpenAI Decisions (`POST /v1/decisions`) field names directly.

### Why Agent Harnesses Use `mouse-1` (The Cost & Latency Lever)

Every turn in an agent harness requires narrow control-flow judgments before and after the main reasoning model runs:
1. **Pre-tool safety gating & auto-approval**: Score `safe` and `destructive` `noul` predicates in ~100 ms before executing `Bash`/`Write`/`MCP` calls. Safe calls run without interrupting the human; destructive calls return `deny` with a reason so the main model re-plans immediately.
2. **Tool & skill routing**: Score candidate MCP tools or skills with a `choice` question so you only load the relevant tool schemas into your frontier model's context window.
3. **Post-tool verification & stall detection**: Score whether test/build output actually supports the agent's completion claim before finishing a turn or burning another frontier model retry.
4. **Prompt-injection defense**: `mouse-1` treats `state` strictly as data (0% decision flip rate on planted instructions vs 65.4% on Jev).

### Endpoints

| Method & Path | Auth | Description |
| --- | --- | --- |
| `POST /v1/decisions` | `Bearer sk_mouse_...` | Evaluate 1 to 128 typed `choice`, `noul`, or `score` questions in parallel against `state` in one request (~100 ms). |
| `POST /v1/calibrations` | `Bearer sk_mouse_...` | Fit a signed confidence cutoff profile (`calp1.<kid>.<blob>`) on 200 to 400 labeled examples (50+ per question signature) using 5-fold cross-fitting. |
| `GET /v1/models` | `Bearer sk_mouse_...` | List active immutable model snapshots and alias mappings (`mouse-1`, `mouse`). |
| `GET /healthz` | None | Unauthenticated liveness and region check (`{ ok: true, region: "us", engine: "modal" }`). |
| `GET /openapi.json` | None | OpenAPI 3.1 specification (also served at `https://www.mouse.dev/openapi.json`). |

### Question Primitives (`POST /v1/decisions`)

1. **`choice`** — Pick one of up to 255 named options:
   - Request: `{ "type": "choice", "instructions": "Optional prompt", "criteria": { "edit": "Modify source file", "search": "Search repo", "ask": null } }`
   - Answer: `{ "type": "choice", "choice": "edit", "confidence": 0.865, "probabilities": { "edit": 0.91, "search": 0.07, "ask": 0.02 }, "mouse": { "calibrated": false, "p_top": 0.91, "abstain": null } }`
2. **`noul`** — Binary yes/no predicate (probability of `true` in `0.0..1.0`):
   - Request: `{ "type": "noul", "instructions": "Can this call run without asking the user?" }`
   - Answer: `{ "type": "noul", "noul": 0.03, "probabilities": { "false": 0.97, "true": 0.03 }, "mouse": { "calibrated": false, "p_top": 0.97, "abstain": null } }`
3. **`score`** — Ordered rubric of 2 to 10 concrete levels (indexed `"0"` to `"N-1"`):
   - Request: `{ "type": "score", "instructions": "How well does the diff satisfy the objective?", "criteria": ["Tests fail or build breaks", "Partial fix", "Addresses requirement and all checks pass"] }`
   - Answer: `{ "type": "score", "score": 1.88, "confidence": 0.85, "legend": { "0": "...", "1": "...", "2": "..." }, "probabilities": { "0": 0.02, "1": 0.08, "2": 0.90 }, "mouse": { "calibrated": false, "p_top": 0.90, "abstain": null } }`

### Drop-in TypeScript Client (Zero Dependencies)

```ts
export async function decide<Q extends Record<string, unknown>>(
  state: unknown,
  questions: Q,
  opts?: { apiKey?: string; calibration?: string; timeoutMs?: number },
) {
  const apiKey = opts?.apiKey ?? process.env.MOUSE_API_KEY;
  if (!apiKey) return null;
  const res = await fetch("https://api.mouse.dev/v1/decisions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "mouse-1",
      state,
      questions,
      ...(opts?.calibration ? { calibration: opts.calibration } : {}),
    }),
    signal: AbortSignal.timeout(opts?.timeoutMs ?? 3000),
  });
  if (!res.ok) return null;
  return (await res.json()) as {
    id: string;
    object: "systemone.response";
    model: string;
    answers: Record<keyof Q, any>;
    usage: {
      input_tokens: number;
      state_tokens: number;
      question_tokens: number;
      framing_tokens: number;
      output_tokens: number;
      cost_usd: number;
    };
    latency_ms: number;
  };
}
```

### Published Limits & Error Codes

- **Limits**: `state` <= 16,384 tokens (never truncated; over limit returns `422 state_too_long`), `questions` <= 128 per request, `criteria` options <= 255 per question, body <= 4 MB, 10 RPS per key (burst 20), 1M input tokens/min per key, state tokens x questions <= 64,000.
- **Error Envelope**: `{ "error": { "type": "...", "code": "...", "message": "...", "param": "..." } }`
  - `400`: `invalid_calibration_profile`
  - `401`: `missing_api_key`, `invalid_api_key`
  - `402`: `insufficient_credits`
  - `404`: `model_not_found`
  - `409`: `profile_model_mismatch`
  - `413`: `request_too_large`
  - `422`: `invalid_schema`, `state_too_long`, `too_many_questions`, `too_many_options`, `too_few_examples`, `too_many_examples`, `too_few_examples_per_question`
  - `429`: `rate_limited`, `token_rate_limited` (honour `Retry-After` header)
  - `503`: `engine_timeout` (honour `Retry-After` header)

## Comparisons

- [Mouse-1 vs AnyJev L0](https://www.mouse.dev/blog/compare/mouse-vs-anyjev): Mouse-1 vs AnyJev L0: Mouse-1 leads When2Call 85.8% to 80.9% and adds fitted confidence cutoffs; AnyJev's calibration error is 0.24.
- [Mouse-1 vs Claude Haiku 5.5 as an agent judge](https://www.mouse.dev/blog/compare/mouse-vs-claude-haiku-judge): Mouse-1 vs Claude Haiku 5.5 as an agent judge: 4.5 s vs 10.6 s waiting on decisions per task, 344 ms vs 1,353 ms per verdict.
- [Mouse-1 vs Claude Opus 5.5 as an agent judge](https://www.mouse.dev/blog/compare/mouse-vs-claude-opus-judge): Mouse-1 vs Claude Opus 5.5 as an agent judge: tasks finish in 18.1 s vs 84.2 s and cost $0.025 vs $0.174, with every run passing.
- [Mouse-1 vs Cloudflare Clef](https://www.mouse.dev/blog/compare/mouse-vs-cloudflare-clef): Mouse-1 vs Cloudflare Clef: 89.1% vs 84.2% agent decision accuracy, 0% vs 37.4% injection flip rate, $0.10 vs $0.24 per 1M tokens.
- [Mouse-1 vs Darwin-27B-ZTC](https://www.mouse.dev/blog/compare/mouse-vs-darwin-27b): Mouse-1 vs Darwin-27B-ZTC: 84.9% vs 81.1% on four public tool benchmarks and 72.3% vs 50.6% on phishing detection. Hosted, no GPUs.
- [Mouse-1 vs Decider 31B](https://www.mouse.dev/blog/compare/mouse-vs-decider-31b): Mouse-1 vs Decider 31B: a hosted decision API vs weights that need a Blackwell GPU. Mouse-1 leads When2Call, 85.8% to 82.5%.
- [Mouse-1 vs Fastino GLiDE](https://www.mouse.dev/blog/compare/mouse-vs-fastino-glide): Mouse-1 vs Fastino GLiDE: $0.10 vs $0.15 per 1M tokens, zero data retention by default, 84.9% vs 83.8% on public tool benchmarks.
- [Mouse-1 vs GPT-6 Sol for agent decisions](https://www.mouse.dev/blog/compare/mouse-vs-gpt-6-sol): Mouse-1 vs GPT-6 Sol for agent decisions: 344 ms vs 1,706 ms per verdict, $0.10 vs $2 per 1M input tokens, and free output.
- [Mouse-1 vs Jev (TypeSafe)](https://www.mouse.dev/blog/compare/mouse-vs-jev): Mouse-1 vs TypeSafe Jev: 89.1% vs 79.1% agent decision accuracy, 0% vs 65.4% prompt-injection flip rate, and a drop-in System One API.
- [Mouse-1 vs LiteLLM safeguards classifier](https://www.mouse.dev/blog/compare/mouse-vs-litellm-safeguards): Mouse-1 vs LiteLLM's safeguards classifier for Claude Code auto mode: a trained decision model, 344 ms verdicts, 0% injection flips.
- [Mouse-1 vs OpenAI Decisions](https://www.mouse.dev/blog/compare/mouse-vs-openai-decisions): Mouse-1 vs OpenAI Decisions: 89.1% vs 82.5% agent decision accuracy and 0% vs 53.9% injection flips at the same $0.10 per 1M tokens.
- [Mouse-1 vs OpenRouter Armor](https://www.mouse.dev/blog/compare/mouse-vs-openrouter-armor): Mouse-1 vs OpenRouter Armor for gating agent tool calls: works with any provider, a named model and a published 0% injection flip rate.
- [Mouse-1 vs Perplexity Decider](https://www.mouse.dev/blog/compare/mouse-vs-perplexity-decider): Mouse-1 vs Perplexity Decider: zero data retention by default, fitted confidence cutoffs and fine-tuning on your own decisions.
- [Mouse-1 vs Sieve 27B](https://www.mouse.dev/blog/compare/mouse-vs-sieve-27b): Mouse-1 vs Sieve 27B v2: Mouse-1 leads BFCL 97.6% to 96.0% and When2Call 85.8% to 84.8%, as a hosted API with no model to serve.
- [Mouse-1 vs Torchcast Decision 27B](https://www.mouse.dev/blog/compare/mouse-vs-torchcast-decision): Mouse-1 vs Torchcast Decision 27B: a commercial API vs non-commercial CC BY-NC weights. Mouse-1 leads phishing detection 72.3% to 70.4%.


## Documentation Sets

- [Abridged documentation](https://mouse.dev/llms-small.txt): a compact version of the documentation for Mouse Decision API (mouse-1), with non-essential content removed
- [Complete documentation](https://mouse.dev/llms-full.txt): the full documentation for Mouse Decision API (mouse-1)
- [Agent Onboarding & Quickstart](https://mouse.dev/_llms-txt/agent-onboarding--quickstart.txt): Prompt templates, zero-dependency TypeScript/Python clients, authentication, and compatibility for Cursor, Claude Code, and Codex
- [Core Concepts & Question Types](https://mouse.dev/_llms-txt/core-concepts--question-types.txt): Schemas and behavior for choice, noul, and score questions, state fan-out, calibration profiles, and model snapshots
- [Harness Integration Guides](https://mouse.dev/_llms-txt/harness-integration-guides.txt): Patterns for tool routing, action gating, output verification, prompt-injection defense, and calibration
- [Reference, Limits, Errors & Pricing](https://mouse.dev/_llms-txt/reference-limits-errors--pricing.txt): HTTP API reference, error codes, rate limits, prepaid token pricing, and zero-data-retention security guarantees

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [Agent Setup Bundle (llm.txt / llm.text)](https://www.mouse.dev/llm.txt): All-in-one coding agent prompt, wire contract, and complete documentation in a single plain-text file
- [Full Documentation (llms-full.txt)](https://www.mouse.dev/llms-full.txt): Every documentation page concatenated into one Markdown file
- [OpenAPI 3.1 Specification (openapi.json)](https://www.mouse.dev/openapi.json): Complete machine-readable OpenAPI 3.1 schema for POST /v1/decisions, POST /v1/calibrations, and GET /v1/models
- [Interactive API Reference](https://www.mouse.dev/docs/api-reference): Scalar interactive API reference and schema explorer
- [Mouse API Console & Keys](https://www.mouse.dev/console/keys): Create sk_mouse_... API keys ($5.00 free starter credit on verified email)