{ "openapi": "3.1.0", "info": { "title": "Mouse API", "version": "1.0.0", "description": "HTTP API reference for `mouse-1`, the single-pass decision model for agent harnesses. Primary endpoint `POST /v1/decisions` (with `POST /v1/systemone` as a wire-compatible alias for TypeSafe System One SDKs), first-party confidence calibration (`POST /v1/calibrations`), immutable model snapshots (`GET /v1/models`), and zero data retention (`Mouse-Data-Retention: none`) by default on every request." }, "paths": { "/v1/systemone": { "post": { "tags": [ "Decisions" ], "summary": "Evaluate decisions (System One alias)", "description": "Evaluate up to 128 typed `choice`, `noul` (yes/no), and `score` questions in parallel against a `state` in a single forward pass (~100ms).", "operationId": "evaluateSystemOne", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemOneRequest" }, "examples": { "agent_tool_routing_and_gating": { "summary": "Tool routing + action gating (Choice + Noul fan-out)", "description": "Evaluate a Choice question and a Noul safety gate in parallel against the same agent state in one forward pass.", "value": { "model": "mouse-1", "state": { "task": "Rename exported function `parseToken` to `verifyToken` in src/auth.ts.", "git_status": "clean", "proposed_command": "pnpm --filter @mouse/relay test" }, "questions": { "next_tool": { "type": "choice", "instructions": "Which tool should handle `task` next?", "criteria": { "edit_file": "Modify source code in a file", "grep_search": "Search for symbols across the repository", "run_tests": "Execute the test suite", "ask_user": "Ask the user for clarification" } }, "safe_to_run": { "type": "noul", "instructions": "Is `proposed_command` safe to run without human approval?" } } } }, "score_rubric": { "summary": "Ordinal patch evaluation (Score)", "description": "Place a state on an ordered 3-level rubric (`0` to `2`) and receive the expectation-weighted score, level probabilities, and confidence.", "value": { "model": "mouse-1", "state": { "objective": "Reject expired API keys with HTTP 401", "diff_summary": "Added expiry check in PgKeyStore._lookup and test in test_api.py", "test_log": "16 passed, 0 failed in 0.42s" }, "questions": { "patch_quality": { "type": "score", "instructions": "How completely does `diff_summary` satisfy `objective` given `test_log`?", "criteria": [ "Tests fail, build breaks, or objective is missed", "Partial fix or missing regression test", "Addresses objective and all checks pass" ] } } } }, "structured_criteria": { "summary": "Structured contrastive criteria", "description": "Pass structured `{ what, not_for, examples }` objects in `criteria` to sharpen boundaries between confusable options.", "value": { "model": "mouse-1", "state": "Customer ticket: My card was charged twice for order #1042. Please refund the duplicate.", "questions": { "department": { "type": "choice", "instructions": "Which team should handle this ticket?", "criteria": { "billing": { "what": "Duplicate charges, invoices, payment failures, or refund requests", "not_for": "Physical return shipments or order tracking", "examples": [ "Charged twice", "Refund my invoice" ] }, "returns": { "what": "Exchanging or returning physical merchandise", "not_for": "Duplicate card charges without a return shipment", "examples": [ "Wrong shoe size", "Arrived damaged" ] }, "shipping": { "what": "Delivery status, carrier delays, or tracking numbers", "not_for": "Billing disputes", "examples": [ "Where is my package?" ] } } } } } } } } }, "required": true }, "responses": { "200": { "description": "Decision answers with calibrated probabilities, confidence, and itemized token usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemOneResponse" }, "example": { "id": "dec_8f92a1c04e1b902d", "object": "systemone.response", "model": "mouse-preview-2026-10-13", "answers": { "next_tool": { "type": "choice", "choice": "edit_file", "confidence": 0.88, "probabilities": { "edit_file": 0.91, "grep_search": 0.06, "run_tests": 0.02, "ask_user": 0.01 }, "logits": { "edit_file": 2.41, "grep_search": -0.31, "run_tests": -1.41, "ask_user": -2.1 }, "mouse": { "calibrated": false, "p_top": 0.91, "abstain": null, "confidence_winning": 0.91, "confidence_normalized": 0.88 } }, "safe_to_run": { "type": "noul", "noul": 0.98, "probabilities": { "false": 0.02, "true": 0.98 }, "logits": { "false": -1.95, "true": 1.94 }, "mouse": { "calibrated": false, "p_top": 0.98, "abstain": null, "confidence_winning": 0.98, "confidence_normalized": 0.96 } } }, "usage": { "input_tokens": 74, "state_tokens": 26, "question_tokens": 26, "framing_tokens": 22, "image_tokens": 0, "cached_tokens": 0, "output_tokens": 0, "cost_usd": 7.4e-06 }, "latency_ms": 38.2 } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Mouse-Model-Version": { "description": "Exact immutable snapshot ID that evaluated the request (`mouse-preview-2026-10-13`).", "schema": { "type": "string", "example": "mouse-preview-2026-10-13" } } } }, "400": { "description": "Invalid or tampered calibration profile (`invalid_calibration_profile`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_calibration_profile", "message": "Calibration profile could not be read.", "param": "calibration" } } } } }, "401": { "description": "Missing or invalid API key (`missing_api_key`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "This API key is not valid. Check it or create a new one." } } } } }, "402": { "description": "Prepaid credit balance is $0.00 (`insufficient_credits`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "insufficient_credits", "message": "Add credits at mouse.dev/console/billing.", "param": "authorization" } } } } }, "404": { "description": "Unknown model name (`model_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "model_not_found", "message": "No model named 'unknown-model'. See GET /v1/models." } } } } }, "409": { "description": "Calibration profile was fitted on a different model snapshot (`profile_model_mismatch`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "profile_model_mismatch", "message": "This profile was fitted on mouse-preview-2026-09-01; this request uses mouse-preview-2026-10-13." } } } } }, "413": { "description": "Request body exceeds 4,000,000 bytes (`request_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "request_too_large", "message": "Request body exceeds 4,000,000 bytes.", "param": "body" } } } } }, "422": { "description": "Schema or limit violation (`invalid_schema`, `state_too_long`, `too_many_questions`, `too_many_options`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "state_too_long", "message": "state is 71,204 tokens; mouse-preview-2026-10-13 reads at most 65,536. Nothing was truncated or billed.", "param": "state" } } } } }, "429": { "description": "Request or input-token rate limit exceeded (`rate_limited`, `token_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Over 200 requests per second for this key. Retry after the Retry-After header." } } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Retry-After": { "description": "Seconds to wait before retrying (`1` or more).", "schema": { "type": "string", "example": "2" } } } }, "503": { "description": "Inference engine timed out (`engine_timeout`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "api_error", "code": "engine_timeout", "message": "The model did not answer in time. Retry after the Retry-After header." } } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Retry-After": { "description": "Seconds to wait before retrying (`1` or more).", "schema": { "type": "string", "example": "2" } } } } } } }, "/v1/decisions": { "post": { "tags": [ "Decisions" ], "summary": "Evaluate decisions", "description": "Evaluate up to 128 typed `choice`, `noul` (yes/no), and `score` questions in parallel against a `state` in a single forward pass (~100ms).", "operationId": "evaluateDecisions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemOneRequest" }, "examples": { "agent_tool_routing_and_gating": { "summary": "Tool routing + action gating (Choice + Noul fan-out)", "description": "Evaluate a Choice question and a Noul safety gate in parallel against the same agent state in one forward pass.", "value": { "model": "mouse-1", "state": { "task": "Rename exported function `parseToken` to `verifyToken` in src/auth.ts.", "git_status": "clean", "proposed_command": "pnpm --filter @mouse/relay test" }, "questions": { "next_tool": { "type": "choice", "instructions": "Which tool should handle `task` next?", "criteria": { "edit_file": "Modify source code in a file", "grep_search": "Search for symbols across the repository", "run_tests": "Execute the test suite", "ask_user": "Ask the user for clarification" } }, "safe_to_run": { "type": "noul", "instructions": "Is `proposed_command` safe to run without human approval?" } } } }, "score_rubric": { "summary": "Ordinal patch evaluation (Score)", "description": "Place a state on an ordered 3-level rubric (`0` to `2`) and receive the expectation-weighted score, level probabilities, and confidence.", "value": { "model": "mouse-1", "state": { "objective": "Reject expired API keys with HTTP 401", "diff_summary": "Added expiry check in PgKeyStore._lookup and test in test_api.py", "test_log": "16 passed, 0 failed in 0.42s" }, "questions": { "patch_quality": { "type": "score", "instructions": "How completely does `diff_summary` satisfy `objective` given `test_log`?", "criteria": [ "Tests fail, build breaks, or objective is missed", "Partial fix or missing regression test", "Addresses objective and all checks pass" ] } } } }, "structured_criteria": { "summary": "Structured contrastive criteria", "description": "Pass structured `{ what, not_for, examples }` objects in `criteria` to sharpen boundaries between confusable options.", "value": { "model": "mouse-1", "state": "Customer ticket: My card was charged twice for order #1042. Please refund the duplicate.", "questions": { "department": { "type": "choice", "instructions": "Which team should handle this ticket?", "criteria": { "billing": { "what": "Duplicate charges, invoices, payment failures, or refund requests", "not_for": "Physical return shipments or order tracking", "examples": [ "Charged twice", "Refund my invoice" ] }, "returns": { "what": "Exchanging or returning physical merchandise", "not_for": "Duplicate card charges without a return shipment", "examples": [ "Wrong shoe size", "Arrived damaged" ] }, "shipping": { "what": "Delivery status, carrier delays, or tracking numbers", "not_for": "Billing disputes", "examples": [ "Where is my package?" ] } } } } } } } } }, "required": true }, "responses": { "200": { "description": "Decision answers with calibrated probabilities, confidence, and itemized token usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemOneResponse" }, "example": { "id": "dec_8f92a1c04e1b902d", "object": "systemone.response", "model": "mouse-preview-2026-10-13", "answers": { "next_tool": { "type": "choice", "choice": "edit_file", "confidence": 0.88, "probabilities": { "edit_file": 0.91, "grep_search": 0.06, "run_tests": 0.02, "ask_user": 0.01 }, "logits": { "edit_file": 2.41, "grep_search": -0.31, "run_tests": -1.41, "ask_user": -2.1 }, "mouse": { "calibrated": false, "p_top": 0.91, "abstain": null, "confidence_winning": 0.91, "confidence_normalized": 0.88 } }, "safe_to_run": { "type": "noul", "noul": 0.98, "probabilities": { "false": 0.02, "true": 0.98 }, "logits": { "false": -1.95, "true": 1.94 }, "mouse": { "calibrated": false, "p_top": 0.98, "abstain": null, "confidence_winning": 0.98, "confidence_normalized": 0.96 } } }, "usage": { "input_tokens": 74, "state_tokens": 26, "question_tokens": 26, "framing_tokens": 22, "image_tokens": 0, "cached_tokens": 0, "output_tokens": 0, "cost_usd": 7.4e-06 }, "latency_ms": 38.2 } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Mouse-Model-Version": { "description": "Exact immutable snapshot ID that evaluated the request (`mouse-preview-2026-10-13`).", "schema": { "type": "string", "example": "mouse-preview-2026-10-13" } } } }, "400": { "description": "Invalid or tampered calibration profile (`invalid_calibration_profile`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_calibration_profile", "message": "Calibration profile could not be read.", "param": "calibration" } } } } }, "401": { "description": "Missing or invalid API key (`missing_api_key`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "This API key is not valid. Check it or create a new one." } } } } }, "402": { "description": "Prepaid credit balance is $0.00 (`insufficient_credits`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "insufficient_credits", "message": "Add credits at mouse.dev/console/billing.", "param": "authorization" } } } } }, "404": { "description": "Unknown model name (`model_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "model_not_found", "message": "No model named 'unknown-model'. See GET /v1/models." } } } } }, "409": { "description": "Calibration profile was fitted on a different model snapshot (`profile_model_mismatch`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "profile_model_mismatch", "message": "This profile was fitted on mouse-preview-2026-09-01; this request uses mouse-preview-2026-10-13." } } } } }, "413": { "description": "Request body exceeds 4,000,000 bytes (`request_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "request_too_large", "message": "Request body exceeds 4,000,000 bytes.", "param": "body" } } } } }, "422": { "description": "Schema or limit violation (`invalid_schema`, `state_too_long`, `too_many_questions`, `too_many_options`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "state_too_long", "message": "state is 71,204 tokens; mouse-preview-2026-10-13 reads at most 65,536. Nothing was truncated or billed.", "param": "state" } } } } }, "429": { "description": "Request or input-token rate limit exceeded (`rate_limited`, `token_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Over 200 requests per second for this key. Retry after the Retry-After header." } } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Retry-After": { "description": "Seconds to wait before retrying (`1` or more).", "schema": { "type": "string", "example": "2" } } } }, "503": { "description": "Inference engine timed out (`engine_timeout`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "api_error", "code": "engine_timeout", "message": "The model did not answer in time. Retry after the Retry-After header." } } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Retry-After": { "description": "Seconds to wait before retrying (`1` or more).", "schema": { "type": "string", "example": "2" } } } } } } }, "/v1/calibrations": { "post": { "tags": [ "Calibrations" ], "summary": "Fit calibration profile", "description": "Fit a signed confidence cutoff profile (`calp1..`) using 5-fold out-of-fold cross-fitting over 200 to 5,000 labeled examples (50+ per distinct question signature).", "operationId": "createCalibration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalibrationRequest" }, "example": { "model": "mouse-1", "target_error": 0.05, "examples": [ { "state": "Customer was charged twice for order #1042.", "questions": { "intent": { "type": "choice", "instructions": "What does the customer need?", "criteria": { "billing": "A charge, invoice, or refund issue", "shipping": "Delivery status or tracking", "account": "Login or profile settings" }, "label": "billing" } } }, { "state": "Where is my tracking link for order #1099?", "questions": { "intent": { "type": "choice", "instructions": "What does the customer need?", "criteria": { "billing": "A charge, invoice, or refund issue", "shipping": "Delivery status or tracking", "account": "Login or profile settings" }, "label": "shipping" } } } ] } } }, "required": true }, "responses": { "200": { "description": "Signed calibration profile (`calp1.`) and 5-fold out-of-fold evaluation report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalibrationResponse" }, "example": { "object": "calibration", "model": "mouse-preview-2026-10-13", "target_error": 0.05, "profile": "calp1.k1.eyJmaXRzIjpbeyJjdXRvZmYiOjAuNzgsImtleXMiOlsiaccountIiwiYmlsbGluZyIsInNoaXBwaW5nIl0sInNpZ25hdHVyZSI6IjRmOGMxMmE5MGUzYjcxMDQiLCJ0eXBlIjoiY2hvaWNlIn1dLCJtb2RlbCI6Im1vdXNlLXByZXZpZXctMjAyNi0xMC0xMyIsInRhcmdldF9lcnJvciI6MC4wNSwidiI6MX0.9f2a4c1e8b304d1a", "n_examples": 250, "questions": [ { "signature": "4f8c12a90e3b7104", "type": "choice", "question_ids": [ "intent" ], "status": "fitted", "before": { "accuracy": 0.912, "ece": 0.031, "brier": 0.142, "nll": 0.264, "mean_confidence": 0.938, "coverage": 1.0, "cutoff": null, "n": 250 }, "after": { "accuracy": 0.912, "ece": 0.031, "brier": 0.142, "nll": 0.264, "mean_confidence": 0.938, "coverage": 0.864, "cutoff": 0.78, "n": 250, "coverage_at_target_error": 0.856, "error_when_covered": 0.0421 } } ], "note": "'coverage_at_target_error' and 'error_when_covered' are 5-fold out-of-fold. Examples were not stored.", "usage": { "input_tokens": 14500, "state_tokens": 3500, "question_tokens": 7750, "framing_tokens": 3250, "image_tokens": 0, "cached_tokens": 0, "output_tokens": 0, "cost_usd": 0.00145 } } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Mouse-Model-Version": { "description": "Exact immutable snapshot ID that evaluated the request (`mouse-preview-2026-10-13`).", "schema": { "type": "string", "example": "mouse-preview-2026-10-13" } } } }, "401": { "description": "Missing or invalid API key (`missing_api_key`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "This API key is not valid. Check it or create a new one." } } } } }, "402": { "description": "Prepaid credit balance is $0.00 (`insufficient_credits`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "billing_error", "code": "insufficient_credits", "message": "Add credits at mouse.dev/console/billing.", "param": "authorization" } } } } }, "404": { "description": "Unknown model name (`model_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "model_not_found", "message": "No model named 'unknown-model'. See GET /v1/models." } } } } }, "413": { "description": "Request body exceeds 4,000,000 bytes (`request_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "request_too_large", "message": "Request body exceeds 4,000,000 bytes.", "param": "body" } } } } }, "422": { "description": "Schema or example-count limit violation (`invalid_schema`, `too_few_examples`, `too_many_examples`, `too_few_examples_per_question`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "invalid_request_error", "code": "state_too_long", "message": "state is 71,204 tokens; mouse-preview-2026-10-13 reads at most 65,536. Nothing was truncated or billed.", "param": "state" } } } } }, "429": { "description": "Request or input-token rate limit exceeded (`rate_limited`, `token_rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Over 200 requests per second for this key. Retry after the Retry-After header." } } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Retry-After": { "description": "Seconds to wait before retrying (`1` or more).", "schema": { "type": "string", "example": "2" } } } }, "503": { "description": "Inference engine timed out (`engine_timeout`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "api_error", "code": "engine_timeout", "message": "The model did not answer in time. Retry after the Retry-After header." } } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Retry-After": { "description": "Seconds to wait before retrying (`1` or more).", "schema": { "type": "string", "example": "2" } } } } } } }, "/v1/models": { "get": { "tags": [ "Models" ], "summary": "List models", "description": "Return all active immutable model snapshots and alias mappings (`mouse-1`, `mouse`).", "operationId": "listModels", "responses": { "200": { "description": "Catalog of immutable model snapshots and active alias mappings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsResponse" }, "example": { "object": "list", "alias": { "mouse-1": "mouse-preview-2026-10-13", "mouse": "mouse-preview-2026-10-13" }, "data": [ { "id": "mouse-preview-2026-10-13", "released": "2026-10-13", "status": "preview", "base": "mouse-1", "max_state_tokens": 65536, "modalities": [ "text" ], "retire_after": null } ], "today": "2026-10-14" } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } } } }, "401": { "description": "Missing or invalid API key (`missing_api_key`, `invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "This API key is not valid. Check it or create a new one." } } } } }, "429": { "description": "Request rate limit exceeded (`rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Over 200 requests per second for this key. Retry after the Retry-After header." } } } }, "headers": { "Mouse-Request-Id": { "description": "Unique request identifier (`req_...`). Include when contacting support.", "schema": { "type": "string", "example": "req_8f92a1c04e1b902d73c104ab" } }, "Mouse-Region": { "description": "Serving region that processed the request (`us`).", "schema": { "type": "string", "example": "us" } }, "Mouse-Data-Retention": { "description": "Always `none`. Request content is never logged or persisted.", "schema": { "type": "string", "enum": [ "none" ], "example": "none" } }, "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ], "example": "no-store" } }, "x-ratelimit-limit-requests": { "description": "Requests-per-second limit for this API key (`200` for standard keys, `5` for playground keys).", "schema": { "type": "string", "example": "200" } }, "x-ratelimit-remaining-requests": { "description": "Remaining requests in the current burst bucket (`400` burst capacity).", "schema": { "type": "string", "example": "399" } }, "x-ratelimit-reset-requests": { "description": "Seconds until the request bucket resets (`1`).", "schema": { "type": "string", "example": "1" } }, "x-ratelimit-limit-tokens": { "description": "Input-tokens-per-minute limit for this API key (`20,000,000`).", "schema": { "type": "string", "example": "20000000" } }, "x-ratelimit-remaining-tokens": { "description": "Remaining input tokens in the current 60-second bucket.", "schema": { "type": "string", "example": "19999930" } }, "x-ratelimit-reset-tokens": { "description": "Seconds until the token bucket resets (`60`).", "schema": { "type": "string", "example": "60" } }, "Retry-After": { "description": "Seconds to wait before retrying (`1` or more).", "schema": { "type": "string", "example": "2" } } } } } } }, "/healthz": { "get": { "tags": [ "System" ], "summary": "Health check", "description": "Unauthenticated liveness probe returning serving region and engine status.", "operationId": "getHealth", "responses": { "200": { "description": "Service liveness and serving region.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "ok": true, "region": "us", "engine": "modal" } } } } }, "security": [] } } }, "components": { "schemas": { "CalChoice": { "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "title": "Instructions", "description": "The question or statement to evaluate against `state`. Accepts a string, structured object, or array." }, "type": { "type": "string", "const": "choice", "title": "Type", "description": "Question primitive type (`choice`)." }, "criteria": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "object", "title": "Criteria", "description": "Map of option keys to descriptions (or `null` when the key is self-explanatory). Up to 1,024 options." }, "label": { "type": "string", "title": "Label", "description": "Ground-truth option key from `criteria`." } }, "additionalProperties": false, "type": "object", "required": [ "type", "criteria", "label" ], "title": "CalChoice" }, "CalExample": { "properties": { "state": { "title": "State", "description": "The example state (string, object, or array). Never stored." }, "questions": { "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/CalChoice" }, { "$ref": "#/components/schemas/CalNoul" }, { "$ref": "#/components/schemas/CalScore" } ], "discriminator": { "propertyName": "type", "mapping": { "choice": "#/components/schemas/CalChoice", "noul": "#/components/schemas/CalNoul", "score": "#/components/schemas/CalScore" } } }, "type": "object", "minProperties": 1, "title": "Questions", "description": "Map of question IDs to labeled questions." } }, "additionalProperties": false, "type": "object", "required": [ "state", "questions" ], "title": "CalExample" }, "CalNoul": { "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "title": "Instructions", "description": "The question or statement to evaluate against `state`. Accepts a string, structured object, or array." }, "type": { "type": "string", "const": "noul", "title": "Type", "description": "Question primitive type (`noul`, binary yes/no predicate)." }, "criteria": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Criteria", "description": "Optional descriptions clarifying what `'true'` (yes) and `'false'` (no) mean." }, "label": { "type": "boolean", "title": "Label", "description": "Ground-truth boolean (`true` for yes, `false` for no)." } }, "additionalProperties": false, "type": "object", "required": [ "type", "label" ], "title": "CalNoul" }, "CalScore": { "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "title": "Instructions", "description": "The question or statement to evaluate against `state`. Accepts a string, structured object, or array." }, "type": { "type": "string", "const": "score", "title": "Type", "description": "Question primitive type (`score`, ordered rubric)." }, "criteria": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "array", "minItems": 1, "title": "Criteria", "description": "Ordered array of 2\u201310 concrete level descriptions from lowest (`0`) to highest (`N - 1`)." }, "label": { "type": "integer", "title": "Label", "description": "Ground-truth integer level index (`0` to `len(criteria) - 1`)." } }, "additionalProperties": false, "type": "object", "required": [ "type", "criteria", "label" ], "title": "CalScore" }, "CalibrationMetrics": { "properties": { "accuracy": { "type": "number", "title": "Accuracy", "description": "Top-1 accuracy across examples (`0..1`)." }, "ece": { "type": "number", "title": "Ece", "description": "Expected calibration error across 10 confidence bins." }, "brier": { "type": "number", "title": "Brier", "description": "Mean Brier score." }, "nll": { "type": "number", "title": "Nll", "description": "Mean negative log-likelihood." }, "mean_confidence": { "type": "number", "title": "Mean Confidence", "description": "Mean top-option probability across examples." }, "coverage": { "type": "number", "title": "Coverage", "description": "Fraction of examples at or above `cutoff`." }, "cutoff": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cutoff", "description": "Fitted `p_top` threshold for `mouse.abstain`." }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Temperature", "description": "Fitted temperature scaling factor `T` (`null` before calibration)." }, "n": { "type": "integer", "title": "N", "description": "Number of labeled examples evaluated for this question signature." }, "coverage_at_target_error": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Coverage At Target Error", "description": "5-fold out-of-fold fraction of examples covered while keeping error at or below `target_error`." }, "error_when_covered": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Error When Covered", "description": "5-fold out-of-fold error rate among covered (non-abstained) examples." } }, "type": "object", "required": [ "accuracy", "ece", "brier", "nll", "mean_confidence", "coverage", "cutoff", "n" ], "title": "CalibrationMetrics" }, "CalibrationQuestionReport": { "properties": { "signature": { "type": "string", "title": "Signature", "description": "16-character SHA-256 signature of `(type, instructions, sorted_keys)`." }, "type": { "type": "string", "enum": [ "choice", "noul", "score" ], "title": "Type", "description": "Question primitive type." }, "question_ids": { "items": { "type": "string" }, "type": "array", "title": "Question Ids", "description": "Question IDs in `examples` that shared this signature." }, "status": { "type": "string", "enum": [ "fitted", "skipped" ], "title": "Status", "description": "Whether the question had enough examples (`50+`) to fit." }, "before": { "anyOf": [ { "$ref": "#/components/schemas/CalibrationMetrics" }, { "type": "null" } ], "description": "Uncalibrated metrics (`cutoff = null`)." }, "after": { "anyOf": [ { "$ref": "#/components/schemas/CalibrationMetrics" }, { "type": "null" } ], "description": "Calibrated metrics including 5-fold out-of-fold coverage and error." }, "n": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "N", "description": "Example count (present when `status` is `skipped`)." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Skip reason when fewer than 50 examples were provided." } }, "type": "object", "required": [ "signature", "type", "question_ids", "status" ], "title": "CalibrationQuestionReport" }, "CalibrationRequest": { "properties": { "model": { "type": "string", "title": "Model", "description": "Model alias (`mouse-1`) or immutable snapshot ID to fit the profile against.", "default": "mouse-1" }, "target_error": { "type": "number", "exclusiveMaximum": 0.5, "exclusiveMinimum": 0.0, "title": "Target Error", "description": "Maximum acceptable error rate (`0.0` to `0.5`, default `0.05`) among non-abstained answers.", "default": 0.05 }, "examples": { "items": { "$ref": "#/components/schemas/CalExample" }, "type": "array", "minItems": 1, "title": "Examples", "description": "200 to 5,000 labeled examples (with at least 50 examples per distinct question signature)." } }, "type": "object", "required": [ "examples" ], "title": "CalibrationRequest" }, "CalibrationResponse": { "properties": { "object": { "type": "string", "const": "calibration", "title": "Object", "description": "Object type (`calibration`)." }, "model": { "type": "string", "title": "Model", "description": "Immutable model snapshot ID this profile is bound to." }, "target_error": { "type": "number", "title": "Target Error", "description": "Target error rate used to fit the abstention cutoffs." }, "profile": { "type": "string", "title": "Profile", "description": "Signed, self-contained calibration profile token (`calp1..`). Pass as `calibration` on `POST /v1/systemone`." }, "n_examples": { "type": "integer", "title": "N Examples", "description": "Total number of labeled examples processed (never stored)." }, "questions": { "items": { "$ref": "#/components/schemas/CalibrationQuestionReport" }, "type": "array", "title": "Questions", "description": "Per-question-signature calibration report (`before` and `after` metrics)." }, "note": { "type": "string", "title": "Note", "description": "Methodology and zero-data-retention note." }, "usage": { "$ref": "#/components/schemas/UsageResponse", "description": "Itemized token usage and USD cost for scoring the calibration examples." } }, "type": "object", "required": [ "object", "model", "target_error", "profile", "n_examples", "questions", "note", "usage" ], "title": "CalibrationResponse" }, "ChoiceAnswer": { "properties": { "type": { "type": "string", "const": "choice", "title": "Type", "description": "Answer primitive type (`choice`)." }, "choice": { "type": "string", "title": "Choice", "description": "Winning option key with the highest probability." }, "confidence": { "type": "number", "title": "Confidence", "description": "Normalized concentration score in `0..1`: `(p_max - 1/n) / (1 - 1/n)`." }, "probabilities": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Probabilities", "description": "Probability distribution across all option keys (sums to `1.0`)." }, "logits": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Logits", "description": "Unnormalized per-option log-scores from the model; `softmax(logits) == probabilities`. Use for offline calibration fitting." }, "mouse": { "$ref": "#/components/schemas/MouseAnswerMeta", "description": "Mouse calibration and abstention metadata." } }, "type": "object", "required": [ "type", "choice", "confidence", "probabilities", "logits", "mouse" ], "title": "ChoiceAnswer" }, "ChoiceQuestion": { "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "title": "Instructions", "description": "The question or statement to evaluate against `state`. Accepts a string, structured object, or array." }, "type": { "type": "string", "const": "choice", "title": "Type", "description": "Question primitive type (`choice`)." }, "criteria": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "object", "title": "Criteria", "description": "Map of option keys to descriptions (or `null` when the key is self-explanatory). Up to 1,024 options." } }, "additionalProperties": false, "type": "object", "required": [ "type", "criteria" ], "title": "ChoiceQuestion" }, "ErrorDetail": { "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "rate_limit_error", "api_error" ], "title": "Type", "description": "Broad error category." }, "code": { "type": "string", "title": "Code", "description": "Machine-readable error code (e.g. `state_too_long`, `invalid_api_key`)." }, "message": { "type": "string", "title": "Message", "description": "Human-readable description naming the limit or field. Never echoes request content." }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Param", "description": "Offending request field path or header, if applicable." } }, "type": "object", "required": [ "type", "code", "message" ], "title": "ErrorDetail" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail", "description": "Error details." } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse" }, "HealthResponse": { "properties": { "ok": { "type": "boolean", "title": "Ok", "description": "`true` when the API process is healthy." }, "region": { "type": "string", "title": "Region", "description": "Serving region identifier (`us`)." }, "engine": { "type": "string", "title": "Engine", "description": "Configured scoring engine (`modal`, `remote`, or `mock`)." } }, "type": "object", "required": [ "ok", "region", "engine" ], "title": "HealthResponse" }, "ModelCard": { "properties": { "id": { "type": "string", "title": "Id", "description": "Immutable model snapshot ID (e.g. `mouse-preview-2026-10-13`)." }, "released": { "type": "string", "title": "Released", "description": "ISO-8601 release date (`YYYY-MM-DD`)." }, "status": { "type": "string", "enum": [ "preview", "ga", "deprecated", "planned" ], "title": "Status", "description": "Lifecycle status." }, "base": { "type": "string", "title": "Base", "description": "Model family (`mouse-1`)." }, "max_state_tokens": { "type": "integer", "title": "Max State Tokens", "description": "Maximum `state` tokens supported (`65,536`)." }, "modalities": { "items": { "type": "string" }, "type": "array", "title": "Modalities", "description": "Supported input modalities (`['text']`)." }, "retire_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retire After", "description": "ISO-8601 earliest retirement date (`null` while active; at least 12 months after successor)." } }, "type": "object", "required": [ "id", "released", "status", "base", "max_state_tokens", "modalities" ], "title": "ModelCard" }, "ModelsResponse": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "description": "Object type (`list`)." }, "alias": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Alias", "description": "Map of active model aliases (`mouse-1`, `mouse`) to their target snapshot IDs." }, "data": { "items": { "$ref": "#/components/schemas/ModelCard" }, "type": "array", "title": "Data", "description": "List of immutable model snapshots." }, "today": { "type": "string", "title": "Today", "description": "Current server date (`YYYY-MM-DD`)." } }, "type": "object", "required": [ "object", "alias", "data", "today" ], "title": "ModelsResponse" }, "MouseAnswerMeta": { "properties": { "calibrated": { "type": "boolean", "title": "Calibrated", "description": "Whether a signed calibration profile matched this question signature." }, "p_top": { "type": "number", "title": "P Top", "description": "Top option probability `max(p)`. When `calibrated` is `true`, `probabilities` (and therefore `p_top`) are temperature-scaled on your labels." }, "abstain": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Abstain", "description": "`true` when `p_top` falls below the profile's fitted cutoff; `false` when at or above; `null` when uncalibrated." }, "confidence_winning": { "type": "number", "title": "Confidence Winning", "description": "Winning-option probability `max(p)` (the Cloudflare Clef `confidence` convention). Equal to `p_top`; named so Clef thresholds port without arithmetic." }, "confidence_normalized": { "type": "number", "title": "Confidence Normalized", "description": "`(max(p) - 1/n) / (1 - 1/n)` over the `n` options (the TypeSafe `confidence` convention), on every answer type including `noul`." } }, "type": "object", "required": [ "calibrated", "p_top", "confidence_winning", "confidence_normalized" ], "title": "MouseAnswerMeta" }, "NoulAnswer": { "properties": { "type": { "type": "string", "const": "noul", "title": "Type", "description": "Answer primitive type (`noul`)." }, "noul": { "type": "number", "title": "Noul", "description": "Probability in `0..1` that the statement/question is `true` (yes)." }, "probabilities": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Probabilities", "description": "`{\"false\": 1 - noul, \"true\": noul}`." }, "logits": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Logits", "description": "Unnormalized log-scores for `false` and `true`; `softmax(logits) == probabilities`." }, "mouse": { "$ref": "#/components/schemas/MouseAnswerMeta", "description": "Mouse calibration and abstention metadata." } }, "type": "object", "required": [ "type", "noul", "probabilities", "logits", "mouse" ], "title": "NoulAnswer" }, "NoulQuestion": { "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "title": "Instructions", "description": "The question or statement to evaluate against `state`. Accepts a string, structured object, or array." }, "type": { "type": "string", "const": "noul", "title": "Type", "description": "Question primitive type (`noul`, binary yes/no predicate)." }, "criteria": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Criteria", "description": "Optional descriptions clarifying what `'true'` (yes) and `'false'` (no) mean." } }, "additionalProperties": false, "type": "object", "required": [ "type" ], "title": "NoulQuestion" }, "ScoreAnswer": { "properties": { "type": { "type": "string", "const": "score", "title": "Type", "description": "Answer primitive type (`score`)." }, "score": { "type": "number", "title": "Score", "description": "Expectation-weighted mean level index: `sum(i * p_i)` in `0..N-1`." }, "legend": { "additionalProperties": true, "type": "object", "title": "Legend", "description": "Map of string level indices (`'0'`, `'1'`, ...) to their level descriptions." }, "probabilities": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Probabilities", "description": "Probability distribution across level indices (sums to `1.0`)." }, "logits": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Logits", "description": "Unnormalized per-level log-scores; `softmax(logits) == probabilities`." }, "confidence": { "type": "number", "title": "Confidence", "description": "Normalized ordinal concentration score in `0..1` based on mean absolute distance from the mode level." }, "mouse": { "$ref": "#/components/schemas/MouseAnswerMeta", "description": "Mouse calibration and abstention metadata." } }, "type": "object", "required": [ "type", "score", "legend", "probabilities", "logits", "confidence", "mouse" ], "title": "ScoreAnswer" }, "ScoreQuestion": { "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "title": "Instructions", "description": "The question or statement to evaluate against `state`. Accepts a string, structured object, or array." }, "type": { "type": "string", "const": "score", "title": "Type", "description": "Question primitive type (`score`, ordered rubric)." }, "criteria": { "items": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "array", "minItems": 1, "title": "Criteria", "description": "Ordered array of 2\u201310 concrete level descriptions from lowest (`0`) to highest (`N - 1`)." } }, "additionalProperties": false, "type": "object", "required": [ "type", "criteria" ], "title": "ScoreQuestion" }, "SystemOneRequest": { "properties": { "model": { "type": "string", "title": "Model", "description": "Model alias (`mouse-1`, `mouse`) or immutable snapshot ID (`mouse-preview-2026-10-13`).", "default": "mouse-1" }, "state": { "title": "State", "description": "The input context to evaluate: a string, JSON object, or array up to 65,536 tokens. `input` is accepted as an alias." }, "questions": { "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/ChoiceQuestion" }, { "$ref": "#/components/schemas/NoulQuestion" }, { "$ref": "#/components/schemas/ScoreQuestion" } ], "discriminator": { "propertyName": "type", "mapping": { "choice": "#/components/schemas/ChoiceQuestion", "noul": "#/components/schemas/NoulQuestion", "score": "#/components/schemas/ScoreQuestion" } } }, "type": "object", "minProperties": 1, "title": "Questions", "description": "Map of question IDs to typed `choice`, `noul`, or `score` questions (up to 128 per request). Evaluated in parallel and in isolation. Also accepted: an array of questions carrying `id`/`name`, `predicate`/`boolean` for `noul`, `text` for `instructions`, and `options`/`choices`/`levels` for `criteria`." }, "calibration": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Calibration", "description": "Optional signed calibration profile (`calp1..`) returned by `POST /v1/calibrations`." }, "order_invariant": { "type": "boolean", "title": "Order Invariant", "description": "Score every multi-option `choice` question a second time with its options reversed and average the two distributions, removing option-order sensitivity. The reversed questions are billed again; the `state` prefix is shared.", "default": false } }, "type": "object", "required": [ "state", "questions" ], "title": "SystemOneRequest" }, "SystemOneResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique decision identifier (`dec_...`)." }, "object": { "type": "string", "const": "systemone.response", "title": "Object", "description": "Object type (`systemone.response`)." }, "model": { "type": "string", "title": "Model", "description": "Exact immutable model snapshot ID that evaluated the request (also in `Mouse-Model-Version`)." }, "answers": { "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/ChoiceAnswer" }, { "$ref": "#/components/schemas/NoulAnswer" }, { "$ref": "#/components/schemas/ScoreAnswer" } ], "discriminator": { "propertyName": "type", "mapping": { "choice": "#/components/schemas/ChoiceAnswer", "noul": "#/components/schemas/NoulAnswer", "score": "#/components/schemas/ScoreAnswer" } } }, "type": "object", "title": "Answers", "description": "Map of question IDs to typed `choice`, `noul`, or `score` answers." }, "usage": { "$ref": "#/components/schemas/UsageResponse", "description": "Itemized token counts and USD cost." }, "latency_ms": { "type": "number", "title": "Latency Ms", "description": "End-to-end server evaluation latency in milliseconds." }, "warnings": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Warnings", "description": "Optional list of ignored unknown top-level request fields." } }, "type": "object", "required": [ "id", "object", "model", "answers", "usage", "latency_ms" ], "title": "SystemOneResponse" }, "UsageResponse": { "properties": { "input_tokens": { "type": "integer", "title": "Input Tokens", "description": "Total billed input tokens (`state_tokens + question_tokens + framing_tokens + image_tokens`)." }, "state_tokens": { "type": "integer", "title": "State Tokens", "description": "Tokens in `state`, billed once per request regardless of question count." }, "question_tokens": { "type": "integer", "title": "Question Tokens", "description": "Tokens across all question `instructions` and `criteria`." }, "framing_tokens": { "type": "integer", "title": "Framing Tokens", "description": "Structural framing tokens (`4` per request + `3` per question + `2` per option)." }, "image_tokens": { "type": "integer", "title": "Image Tokens", "description": "Image tokens (`0` for text/JSON requests).", "default": 0 }, "cached_tokens": { "type": "integer", "title": "Cached Tokens", "description": "State tokens served from the 5-minute in-memory prefix cache (`$0.02 / 1M`)." }, "output_tokens": { "type": "integer", "title": "Output Tokens", "description": "Always `0` (decision models do not decode output tokens).", "default": 0 }, "cost_usd": { "type": "number", "title": "Cost Usd", "description": "Exact USD cost for this request (`$0.10 / 1M` uncached input, `$0.02 / 1M` cached)." } }, "type": "object", "required": [ "input_tokens", "state_tokens", "question_tokens", "framing_tokens", "cached_tokens", "cost_usd" ], "title": "UsageResponse" } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_mouse_...", "description": "Send `Authorization: Bearer sk_mouse_...` on every `/v1/*` request. Create keys at [mouse.dev/console/keys](https://www.mouse.dev/console/keys)." } } }, "tags": [ { "name": "Decisions", "description": "Evaluate `choice`, `noul` (yes/no), and `score` questions against a `state` in one forward pass." }, { "name": "Calibrations", "description": "Fit a signed confidence cutoff profile (`calp1.`) on 200+ labeled examples using 5-fold cross-fitting." }, { "name": "Models", "description": "Inspect immutable model snapshot IDs and active aliases (`mouse-1`, `mouse`)." }, { "name": "System", "description": "Unauthenticated liveness probe." } ], "servers": [ { "url": "https://api.mouse.dev", "description": "US-East (Zero Data Retention)" } ], "security": [ { "apiKey": [] } ] }