# Moonbounce Decisions API - [Introduction](https://docs.moonbounce.ai/index.md): Evaluate content against a decision you describe in code, and teach it with feedback. - [Quickstart](https://docs.moonbounce.ai/quickstart.md): From an API key to your first evaluation and feedback. - [How Moonbounce works](https://docs.moonbounce.ai/learn/how-it-works.md): The whole loop on one page, from a decision in your code to a better version you merge. - [Describe a decision](https://docs.moonbounce.ai/learn/decisions.md): Build a decision's structure one piece at a time, from a single question to a full refund decision. - [Aggregations](https://docs.moonbounce.ai/learn/aggregations.md): Every aggregation type, what its value means, how missing answers flow through it, and patterns for putting them together. - [From answers to an outcome](https://docs.moonbounce.ai/learn/scores-and-outcomes.md): How question answers become a value, how bands, rules and match turn it into an outcome, and what the status says. - [Evaluate content](https://docs.moonbounce.ai/learn/evaluations.md): What you send to POST /v1/evaluate, what comes back, and how to retry and handle failures safely. - [Versions and hashes](https://docs.moonbounce.ai/learn/versions.md): How a decision's version is named by its structure hash, what changes it, and how to register and ship a structure from your repository. - [Feedback](https://docs.moonbounce.ai/learn/feedback.md): Tell Moonbounce what was true about an evaluation, and what each kind of feedback counts for. - [Review](https://docs.moonbounce.ai/learn/review.md): How Moonbounce picks a few items a day for you to judge, and how blind spot checks measure agreement. - [Suggestions and previews](https://docs.moonbounce.ai/learn/improving.md): How feedback becomes a proposed change to your structure, how a preview tests a change against past cases, and how an accepted change reaches production. - [Engines, keys and environments](https://docs.moonbounce.ai/learn/engines-and-environments.md): Which engine answers your questions and how to switch it, which key can call which operation, and how test traffic stays apart from production. - [Connect your agent](https://docs.moonbounce.ai/connect-your-agent.md): Use the API as MCP tools from a coding agent. - [Glossary](https://docs.moonbounce.ai/learn/glossary.md): Every term from these guides, in one place, with where each is explained. - [API reference overview](https://docs.moonbounce.ai/reference/overview.md): How the reference is generated, how to authenticate, and what to expect while the API is in early access. - [Health check](https://docs.moonbounce.ai/api-reference/health/health-check.md): Public, no customer data. Reports the deployed version (the deploy tag, else the Worker version id) and whether a Postgres round trip through the Worker's own Hyperdrive binding succeeded within about 2 seconds and showed the app role holding the write privileges the API needs. 503 with `db: unavail… - [Hash a decision structure](https://docs.moonbounce.ai/api-reference/structures/hash-a-decision-structure.md): Returns the structure hash and every question's hash, without registering it or touching data. Public: needs no API key. Key order, Unicode normalization (NFC) of instructions, criteria and attribute sources, the order of `reads` and of aggregation `inputs`, and defaults spelled out (`invert: false`… - [List registered structures](https://docs.moonbounce.ai/api-reference/structures/list-registered-structures.md): Reads only. Lists a decision's registered structures, newest first, with their question hashes but not their definitions; getStructure returns the definition. The decision must have a binding in the key's environment. Its structure registry is shared across the organization's environments. Pass next… - [Register a decision structure](https://docs.moonbounce.ai/api-reference/structures/register-a-decision-structure.md): Stores a structure under the decision so evaluations can name it in `moonbounce.structure_hash`. Idempotent by content: 201 when this call registered it, 200 when it already existed. The first registration for an environment also creates the decision's engine binding there from the deployment defaul… - [Get a registered structure](https://docs.moonbounce.ai/api-reference/structures/get-a-registered-structure.md): Reads only. Returns a registered structure's definition, in authored key order, and its hashes (404 STRUCTURE_UNKNOWN otherwise). - [List decisions in this environment](https://docs.moonbounce.ai/api-reference/structures/list-decisions-in-this-environment.md): Reads only. Lists decisions with a binding in the key's organization and environment, newest decision first. Structures are the decision's shared registry count across environments. Pass next_cursor as cursor while has_more is true. - [List the engines a decision can run on](https://docs.moonbounce.ai/api-reference/engines/list-the-engines-a-decision-can-run-on.md): The engines this deployment offers, their models and what each model reports: the resolved model, whether it is pinned, the question types and content it reads, and its list price. Choose one for a decision with `POST /v1/decisions/{decision_id}/binding/revisions`. - [Get the engine a decision runs on](https://docs.moonbounce.ai/api-reference/engines/get-the-engine-a-decision-runs-on.md): The decision's current binding revision in the calling key's environment. 404 until a structure is registered there (the first registration binds it to the deployment default). - [Choose the engine a decision runs on](https://docs.moonbounce.ai/api-reference/engines/choose-the-engine-a-decision-runs-on.md): Sets the engine and model a decision runs on in this environment, as a new binding revision. Appends a binding revision for the calling key's environment, with one engine for every question. Evaluations run on it from the next call, and a switch also moves seeds, previews and suggestions. The weight… - [Evaluate an item against a decision](https://docs.moonbounce.ai/api-reference/evaluate/evaluate-an-item-against-a-decision.md): A superset of System One's POST /v1/systemone. Spends engine calls and, with moonbounce.dry_run: true, stores no evaluation; otherwise stores an evaluation. Answers each question over the state (each question sees only the values its `reads` paths name, such as `state.message` or `state.order.custom… - [Get a past evaluation](https://docs.moonbounce.ai/api-reference/evaluate/get-a-past-evaluation.md): Reads only. Returns an evaluation of this organization and the key's environment, including assignment_mode and content: {state, attribute_values?} when inputs were stored, or content: null when they were not (store_state: false). A submitted JSON null is content: {state: null}; another environment'… - [List a decision's evaluations](https://docs.moonbounce.ai/api-reference/evaluate/list-a-decisions-evaluations.md): Reads only. Lists evaluations in the key's organization and environment, newest first, without content. Use getEvaluation for stored inputs in content: {state, attribute_values?}, or null when not stored. Deleted evaluations are omitted. since is inclusive and until is exclusive. Pass next_cursor as… - [Submit feedback on an evaluation or item](https://docs.moonbounce.ai/api-reference/feedback/submit-feedback-on-an-evaluation-or-item.md): Say what the right answer was. The sources that count toward an evaluation's consensus, which previews and suggestions learn from, are `owner` (through this route), reviewers answering through the review routes (the Review app), and seed examples; `app_native` and `app_resolution` provide supporting… - [Get a feedback submission as stored](https://docs.moonbounce.ai/api-reference/feedback/get-a-feedback-submission-as-stored.md): Reads back any feedback submission in the key's environment: one from `POST /v1/feedback`, a seed example's from `POST /v1/decisions/{decision_id}/seeds`, or a review answer. `claims` are in the order and shape they were sent, and `claim_count` says how many there are. `resolved_from_item` says the… - [Export a decision's feedback as training data](https://docs.moonbounce.ai/api-reference/feedback/export-a-decisions-feedback-as-training-data.md): Lists feedback with its claims and evaluated cases; reads only. The raw feedback on a decision, for a producer's training data (calibration, suggested versions): one item per submission, oldest first, with its claims (an expected_answer with the hash of the question it judged), the evaluation it jud… - [Seed a decision with labeled examples](https://docs.moonbounce.ai/api-reference/feedback/seed-a-decision-with-labeled-examples.md): Imports labeled starting examples (seeds): each runs through the engines (spends engine calls) and is stored as an evaluation with seed feedback. Send the structure inline (`questions`, `attributes`, `aggregations`, `result`; registered on first sight, as evaluate does) or a registered structure's h… - [List review items](https://docs.moonbounce.ai/api-reference/review/list-review-items.md): With status=open (the default), the reviewer's open items, oldest fill first and in rank order within it. An open listing first tops the queue up to the daily budget (12 per decision, 25 in total, per UTC day), expiring items queued more than 3 days ago. Listing does not count as showing an item (se… - [Get a review item](https://docs.moonbounce.ai/api-reference/review/get-a-review-item.md): One of the reviewer's items in any state. A blind item shows its prediction only once answered. Another reviewer's item is 404. - [Get the structure a review item was decided with](https://docs.moonbounce.ai/api-reference/review/get-the-structure-a-review-item-was-decided-with.md): Returns the structure the item's evaluation was decided with, as authored: its full hash, the questions with their instructions, criteria and the `state.` paths (or deeper, `state.order.id`) each reads, the attributes, every aggregation (weights, band cuts, rules) and the result. Never the eval… - [Mark a review item as shown](https://docs.moonbounce.ai/api-reference/review/mark-a-review-item-as-shown.md): Records that a review item was shown to the reviewer (once); it changes whether an expired blind item can return to the queue. Idempotent acknowledgement that the item was put in front of the reviewer: sets shown_at the first time and returns the stored value after that. An item that was shown and t… - [Submit a review](https://docs.moonbounce.ai/api-reference/review/submit-a-review.md): Records the reviewer's claims for an open item and returns the item with its prediction: confirm with `expected_outcome` set to Moonbounce's outcome (or `verdict: approve`), change or answer a spot check with `expected_outcome` set to yours, correct one question with `expected_answer`, and flag cont… - [Withdraw a review answer](https://docs.moonbounce.ai/api-reference/review/withdraw-a-review-answer.md): Undoes the reviewer's own recent answer, within 10 minutes of the original answer. Send the current chain head as feedback_id (from handled.feedback_id). Corrections do not renew the window. A stale head, expired window, skipped, expired, unanswered or already withdrawn item is 409; another reviewer… - [Change your own earlier review answer](https://docs.moonbounce.ai/api-reference/review/change-your-own-earlier-review-answer.md): Changes your own earlier answer on an item, at any time: the new answer supersedes your last one, and the original is kept as history. On a spot check your first, blind answer still measures Moonbounce's accuracy; the change is marked as made after the reveal. Send the current chain head as feedback… - [Skip a review item](https://docs.moonbounce.ai/api-reference/review/skip-a-review-item.md): `unsure` records an unsure submission with no claims; `skip` records nothing. The same skip again returns the first answer; skipping an answered or expired item, or with another reason, is 409. - [Add the reason for a blind disagreement](https://docs.moonbounce.ai/api-reference/review/add-the-reason-for-a-blind-disagreement.md): Fills in the reason of an answered blind item whose submission disagreed without one (reason_pending). The claims stay as submitted. Once only: the same reason again returns 200, anything else (or an item not waiting for a reason) is 409. - [List suggestions for a decision](https://docs.moonbounce.ai/api-reference/suggestions/list-suggestions-for-a-decision.md): Newest first, the key's environment's suggestions only. On a production key, acceptance is recorded before the list is read: a suggestion whose candidate hashes have since served primary production traffic comes back `accepted`. A test key's suggestions are never accepted. `stale` is set on a sugges… - [Generate a suggestion on demand](https://docs.moonbounce.ai/api-reference/suggestions/generate-a-suggestion-on-demand.md): Proposes one change to the decision's structure from its feedback (a question rewrite or a new question), with its preview as evidence. `suggestion` is null when there is nothing worth proposing, and `reason` says why. The same candidate proposed earlier in the key's environment is returned instead… - [Get a suggestion](https://docs.moonbounce.ai/api-reference/suggestions/get-a-suggestion.md): Another environment's suggestion is 404, like another organization's. On a production key, acceptance is recorded before it is read. `stale` is set when feedback on a case it was evaluated on changed after its evidence was read; its evidence is never rescored, so preview it again. - [Mark a suggestion pulled or rejected](https://docs.moonbounce.ai/api-reference/suggestions/mark-a-suggestion-pulled-or-rejected.md): proposed -> pulled, proposed or pulled -> rejected; repeating the current status is a no-op. Anything else is 409. `accepted` is never set by a caller: it is observed in live calls on production keys. Another environment's suggestion is 404. - [Preview a structure change against past feedback](https://docs.moonbounce.ai/api-reference/suggestions/preview-a-structure-change-against-past-feedback.md): Replays a structure change over past cases with feedback: it spends engine calls, stores a run, and burns the held-out cases it lists. Not a dry run of evaluate. Replays a local structure and its base over the decision's reviewed and seeded cases in the key's environment (a test key previews against… - [Get the improvement loop's status](https://docs.moonbounce.ai/api-reference/suggestions/get-the-improvement-loops-status.md): Accepted suggestions with their evidence labels, review counts, spot-check agreement (on the version that last served production before the first acceptance vs on accepted candidates, by the version that served each production review) and the stop check: after `threshold` reviews with no suggestion… - [Engine and model cost for a decision, per evaluation and in total](https://docs.moonbounce.ai/api-reference/usage/engine-and-model-cost-for-a-decision-per-evaluation-and-in-total.md): Engine cost of one decision's evaluations and previews over a window; reads only. What the decision's evaluations cost over a window, for the key's organization and environment. Amounts are US dollars in micros (`usd_micros`: millionths of a dollar). Costs are what our engines reported, priced by ea… - [Identify the calling key or sign-in](https://docs.moonbounce.ai/api-reference/keys/identify-the-calling-key-or-sign-in.md): Who is calling: the organization, environment (production or test), key id, actor and scopes of this API key, or of the sign-in when an agent connects over OAuth (then key_id is an oauth: id, not a revocable key). Reads nothing and spends nothing; call it first to learn which environment your calls… ## OpenAPI Specs - [openapi](/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.