# Moonbounce Decisions API

- [Introduction](https://docs.moonbounce.ai/index.md): Score 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 spec one node at a time, from a single feature to Northpine's full refund-exception spec.
- [From answers to an outcome](https://docs.moonbounce.ai/learn/scores-and-outcomes.md): How feature answers become a score, and how your cut points turn that score into an outcome.
- [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 two hashes, what changes each one, and how to register, pin and ship them 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 spec, how a preview tests a change against past cases, and how an accepted change reaches production.
- [Node types and patterns](https://docs.moonbounce.ai/learn/node-types.md): Every node type, the ones you can use today and the ones coming soon, and patterns for putting them together.
- [Engines, keys and environments](https://docs.moonbounce.ai/learn/engines-and-environments.md): Which engine answers your features 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 spec](https://docs.moonbounce.ai/api-reference/specs/hash-a-decision-spec.md): Returns the structure hash, every node's hash and the default-weights hash of a spec, without registering it or touching data. Public: needs no API key. Key order, whitespace around a string, Unicode normalization (NFC), the order of `inputs` and combine `terms`, defaults spelled out (`effect: "rais…
- [List registered structures](https://docs.moonbounce.ai/api-reference/specs/list-registered-structures.md): Reads only. Lists a decision's registered structures, newest first, without spec bodies; getStructure returns the spec. The decision must have a binding in the key's environment. Its structure registry is shared across the organization's environments. Pass next_cursor as cursor while has_more is tru…
- [Register a spec structure](https://docs.moonbounce.ai/api-reference/specs/register-a-spec-structure.md): Stores a spec's structure under the decision so evaluations can name it by 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 default. Returns hashe…
- [Get a registered structure and its spec](https://docs.moonbounce.ai/api-reference/specs/get-a-registered-structure-and-its-spec.md): Reads only. Returns the authored spec, hashes and `meta` of a registered structure (404 VERSION_UNKNOWN otherwise). Older stored specs use the current vocabulary; rows predating authored-order storage may have a different node order.
- [List decisions in this environment](https://docs.moonbounce.ai/api-reference/specs/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 node 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 node. Evaluations run on it from the next call, unless they pin weights fit for one engine profile: those keep running…
- [Evaluate an item against a decision](https://docs.moonbounce.ai/api-reference/evaluate/evaluate-an-item-against-a-decision.md): Spends engine calls and, with dry_run: true, stores no evaluation; otherwise stores an evaluation. Scores one item with a spec (inline, or by registered hash), returning the score, outcome and every node's value. Fresh responses include recorded cost; engine_calls counts upstream calls, which can an…
- [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 the submitted subject when stored. Subject is absent when content was not stored (store_content: false); another environment's evaluation is 404, so a test key never reads production traff…
- [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 the stored subject. Deleted evaluations are omitted. since is inclusive and until is exclusive. Pass next_cursor as cursor while has_more is true.
- [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, weights, suggested versions): one item per submission, oldest first, with its claims, the evaluation it judged (version hashes, engine profile, cut points, sco…
- [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. Fresh responses include recorded cost per result and a batch total; engine_calls counts upstream calls, which can answer several features, and cache_hits…
- [List review items](https://docs.moonbounce.ai/api-reference/review/list-review-items.md): With state=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 (see…
- [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 and weights a review item was decided with](https://docs.moonbounce.ai/api-reference/review/get-the-structure-and-weights-a-review-item-was-decided-with.md): Returns the structure and weights the item's evaluation was decided with: the full structure and weights hashes, each feature as authored (name, prompt, answer type, guidance, criteria) in authored order with its weight in the score's combine, and the cut points with their outcomes, lowest first. Ne…
- [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. No `action` claims; no `verdict` on a blind item or an abstained evaluation (its prediction has no outcome). Disagreeing (a reject verdict, another outcome, or a target that contradicts an extreme outcome) needs…
- [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 spec from its feedback (a feature rewrite or a new feature), 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 of a du…
- [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 spec change against past feedback](https://docs.moonbounce.ai/api-reference/suggestions/preview-a-spec-change-against-past-feedback.md): Replays a spec 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 spec (with its weights pin and cut points) and its base over the decision's reviewed and seeded cases in the key's environment…
- [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.