# 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` (wire-compatible alias: `POST https://api.mouse.dev/v1/systemone`)
- **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` (65,536 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.02` / 1M cached input tokens (5-minute prefix cache on repeated `state`), `$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 ~40–100ms 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` (alias `/v1/systemone`) | `Bearer sk_mouse_...` | Evaluate 1 to 128 typed `choice`, `noul`, or `score` questions in parallel against `state` in a single forward pass (~100ms). |
| `POST /v1/calibrations` | `Bearer sk_mouse_...` | Fit a signed confidence cutoff profile (`calp1.<kid>.<blob>`) on 200 to 5,000 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 1,024 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;
      cached_tokens: number;
      output_tokens: number;
      cost_usd: number;
    };
    latency_ms: number;
  };
}
```

### Published Limits & Error Codes

- **Limits**: `state` <= 65,536 tokens (never truncated; over limit returns `422 state_too_long`), `questions` <= 128 per request, `criteria` options <= 1,024 per question, body <= 4 MB, 200 RPS per key (burst 400), 20M input tokens/min per key.
- **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)

## 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/systemone, 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)