> ## Documentation Index > Fetch the complete documentation index at: https://docs.moonbounce.ai/llms.txt > Use this file to discover all available pages before exploring further. # Evaluate an item, or run a version over many items > Two shapes. **One item** (`state`, `moonbounce.item_id`). **A run** (`items`, or `cases`): up to 200 items under one version, each exactly as one call would be, with a `run_id` for loss_report (described at the end). Evaluates one item against a decision: answers each question over the item's `state` (each question sees only the values its `reads` paths name, such as `state.message` or `state.order.customer.tier`, nested as in the state), evaluates the aggregations, and returns every answer, every aggregation's value and the result's status, value and outcome. The structure travels inline (`questions`, `attributes`, `aggregations`, `result`) or by hash in `moonbounce.structure_hash`, never both. The request is a superset of System One's POST /v1/systemone: a plain System One request plus a `result` and the `moonbounce` object is a valid call. `model` asserts the decision's bound model rather than choosing one (see `model`); choose the engine with `POST /v1/decisions/{decision_id}/binding/revisions` (the MCP tool `set_binding`). A decision gets its first binding in an environment, to the deployment's default engine, the first time a structure is registered for the decision there: by `POST /v1/decisions/{decision_id}/structures` (the MCP tool `register_structure`), or by any evaluate or import_examples call that is not a dry run in an environment that has no binding yet, inline or by hash. A call refused for its `model` or for an engine the binding cannot use registers no structure and creates no binding, and neither does an inline structure whose content is refused. Questions are for judgments a model makes; facts your app already knows, such as an order total or a refund count, belong in `attributes` and are compared exactly by `rules` conditions (`gte`, `lt`, `is`, `in`). Spends engine calls and, with moonbounce.dry_run: true, stores no evaluation; otherwise stores an evaluation. Questions with the same reads share one System One call. Fresh responses include recorded cost. A dry run stores only usage, returns a dry_ id and dry_run: true, and refuses Idempotency-Key. It does not register an inline structure, create a binding or cache answers. Otherwise an inline structure is registered on first sight and the response follows the evaluation commit. A replay with the same Idempotency-Key returns the first result with the Idempotent-Replayed header. Each request has a 10 s budget; `Prefer: wait=` shortens it. **A run:** send `items` in place of `state` (each `{item_id, state, attribute_values?, expected?, label_source?}`, `item_id` unique in the run), the structure inline as for one item or by `moonbounce.structure_hash`, and `moonbounce.decision_id`. Each item is evaluated exactly as it would be on its own: stored as an evaluation, or with `moonbounce.dry_run: true` a dry run that stores only usage; each result carries its `id` (`evl_` or `dry_`). Score versions with dry runs: a stored run's evaluations are real traffic. `expected` (an outcome) and `label_source` (`human`, `synthetic` or `unknown`) are the item's label, kept with the run for loss_report, never used to evaluate and never recorded as feedback. Every item's content is checked before any engine call: content the structure refuses is 400 CONTENT_INVALID naming `items.`. An item whose engines fail is that item's result (status `failed`, with an `error` whose `code` says why and `retryable` whether sending it again may help); the call fails only on an invalid request, auth, admission or a store error. The run is kept until `expires_at`: pass its `run_id` to loss_report to judge it, so the results never pass through your context; a stored run's evaluations stay after it expires. `include` adds each result's `answers`, `attributes`, or `evaluation` (everything one evaluate returns for that item). Each item that succeeded is billed as one evaluate or dry run would be; a failed item's engine spend is recorded and shown as its `cost` (money). An outage of any kind (unavailable, rate limited, timeout, auth) is `retryable`; only the content's own failure is not. A run has its own 60 s budget (`Prefer: wait` doesn't apply) and takes no `model`; items it could not start fail with `NOT_STARTED`, and a case it ran out of time for with `ENGINE_UNAVAILABLE` (both retryable): send them in a new run with a new Idempotency-Key. A run answers 201, and its Idempotency-Key replays the first response without spending again. **Stored cases:** send `cases` in place of `items` to evaluate the decision's labeled cases (the ones list_cases lists): `{evaluation_ids}`, or list_cases' filters (`outcomes`, `structure_hash`, `label_source`, `since`, `until`) with `limit` (default 200) and `cursor` (`cases.next_cursor` from the previous run). They are always dry runs: each case is replayed as a preview replays it, reusing the answer it stored for a question that hasn't changed (same engine and model) and asking the rest; `refresh` names questions to ask afresh. Each result carries the case's `evaluation_id`, and the run keeps its label, label source and answer corrections, so a preview equals a case run under the base (refreshing the questions the candidate changed or dropped), one under the candidate, and loss_report over the two, when both runs set `cases.outcomes` to the outcomes either version can produce and cover the same cases (a preview judges the newest 500: page both runs through them while no label changes; a page is not a snapshot), and both versions can read every case's stored content. ## OpenAPI ````yaml /openapi.json post /v1/evaluate openapi: 3.1.0 info: title: Moonbounce Decisions API version: 0.0.0 description: >- Moonbounce decisions: evaluate an item's state against a decision structure (System One questions, attributes you supply and aggregations over both), record feedback and import labeled examples, review a ranked queue, and improve the structure through suggestions that ship as code diffs, each with a preview (backtest) and an evidence label. **Authentication.** Send an API key as `Authorization: Bearer ` on every operation except `GET /health` and `POST /v1/structures/hash`. Call the API from a server, never a browser: a key must not reach one, and the API sends no CORS headers. A key belongs to one organization and one environment: production, or test for a key with the `env:test` permission. Test traffic never counts as production traffic. **Requests.** JSON bodies (`Content-Type: application/json`) of at most 1 MB, parsed strictly: duplicate keys, lone surrogates, integers outside ±(2^53 - 1), `__proto__` keys, U+0000 and nesting deeper than 64 are a 400. **Retries.** Send an `Idempotency-Key` on every POST under /v1 that takes one (all but `POST /v1/structures/hash` and `POST /v1/review/items/fill`, whose retry is another fill within the day's budget). Keep it for the request's retries. The same key with the same request returns the first stored result, marked `Idempotent-Replayed: true`, for 24 hours (410 if that result was since deleted); with another request it is 422 IDEMPOTENCY_KEY_REUSED. Keys are scoped to the organization and environment across every operation, so use a fresh key per request. A request that failed before its result was stored runs again when retried. 429 and 503 under /v1 may carry `Retry-After` (seconds); a daily QUOTA_EXCEEDED cap instead names its reset time. **Errors.** Every error under /v1 is `{"error": {"type", "message", "reason"?, "param"?, "details"?}}` (ErrorBody); `GET /health` answers its own shape. Every response carries a `Request-Id` header. Rate limits apply per key, and per client IP for requests without a valid key; a 429 RATE_LIMITED carries `Retry-After`. servers: - url: https://api.moonbounce.ai description: Production security: [] paths: /v1/evaluate: post: tags: - evaluate summary: Evaluate an item, or run a version over many items description: >- Two shapes. **One item** (`state`, `moonbounce.item_id`). **A run** (`items`, or `cases`): up to 200 items under one version, each exactly as one call would be, with a `run_id` for loss_report (described at the end). Evaluates one item against a decision: answers each question over the item's `state` (each question sees only the values its `reads` paths name, such as `state.message` or `state.order.customer.tier`, nested as in the state), evaluates the aggregations, and returns every answer, every aggregation's value and the result's status, value and outcome. The structure travels inline (`questions`, `attributes`, `aggregations`, `result`) or by hash in `moonbounce.structure_hash`, never both. The request is a superset of System One's POST /v1/systemone: a plain System One request plus a `result` and the `moonbounce` object is a valid call. `model` asserts the decision's bound model rather than choosing one (see `model`); choose the engine with `POST /v1/decisions/{decision_id}/binding/revisions` (the MCP tool `set_binding`). A decision gets its first binding in an environment, to the deployment's default engine, the first time a structure is registered for the decision there: by `POST /v1/decisions/{decision_id}/structures` (the MCP tool `register_structure`), or by any evaluate or import_examples call that is not a dry run in an environment that has no binding yet, inline or by hash. A call refused for its `model` or for an engine the binding cannot use registers no structure and creates no binding, and neither does an inline structure whose content is refused. Questions are for judgments a model makes; facts your app already knows, such as an order total or a refund count, belong in `attributes` and are compared exactly by `rules` conditions (`gte`, `lt`, `is`, `in`). Spends engine calls and, with moonbounce.dry_run: true, stores no evaluation; otherwise stores an evaluation. Questions with the same reads share one System One call. Fresh responses include recorded cost. A dry run stores only usage, returns a dry_ id and dry_run: true, and refuses Idempotency-Key. It does not register an inline structure, create a binding or cache answers. Otherwise an inline structure is registered on first sight and the response follows the evaluation commit. A replay with the same Idempotency-Key returns the first result with the Idempotent-Replayed header. Each request has a 10 s budget; `Prefer: wait=` shortens it. **A run:** send `items` in place of `state` (each `{item_id, state, attribute_values?, expected?, label_source?}`, `item_id` unique in the run), the structure inline as for one item or by `moonbounce.structure_hash`, and `moonbounce.decision_id`. Each item is evaluated exactly as it would be on its own: stored as an evaluation, or with `moonbounce.dry_run: true` a dry run that stores only usage; each result carries its `id` (`evl_` or `dry_`). Score versions with dry runs: a stored run's evaluations are real traffic. `expected` (an outcome) and `label_source` (`human`, `synthetic` or `unknown`) are the item's label, kept with the run for loss_report, never used to evaluate and never recorded as feedback. Every item's content is checked before any engine call: content the structure refuses is 400 CONTENT_INVALID naming `items.`. An item whose engines fail is that item's result (status `failed`, with an `error` whose `code` says why and `retryable` whether sending it again may help); the call fails only on an invalid request, auth, admission or a store error. The run is kept until `expires_at`: pass its `run_id` to loss_report to judge it, so the results never pass through your context; a stored run's evaluations stay after it expires. `include` adds each result's `answers`, `attributes`, or `evaluation` (everything one evaluate returns for that item). Each item that succeeded is billed as one evaluate or dry run would be; a failed item's engine spend is recorded and shown as its `cost` (money). An outage of any kind (unavailable, rate limited, timeout, auth) is `retryable`; only the content's own failure is not. A run has its own 60 s budget (`Prefer: wait` doesn't apply) and takes no `model`; items it could not start fail with `NOT_STARTED`, and a case it ran out of time for with `ENGINE_UNAVAILABLE` (both retryable): send them in a new run with a new Idempotency-Key. A run answers 201, and its Idempotency-Key replays the first response without spending again. **Stored cases:** send `cases` in place of `items` to evaluate the decision's labeled cases (the ones list_cases lists): `{evaluation_ids}`, or list_cases' filters (`outcomes`, `structure_hash`, `label_source`, `since`, `until`) with `limit` (default 200) and `cursor` (`cases.next_cursor` from the previous run). They are always dry runs: each case is replayed as a preview replays it, reusing the answer it stored for a question that hasn't changed (same engine and model) and asking the rest; `refresh` names questions to ask afresh. Each result carries the case's `evaluation_id`, and the run keeps its label, label source and answer corrections, so a preview equals a case run under the base (refreshing the questions the candidate changed or dropped), one under the candidate, and loss_report over the two, when both runs set `cases.outcomes` to the outcomes either version can produce and cover the same cases (a preview judges the newest 500: page both runs through them while no label changes; a page is not a snapshot), and both versions can read every case's stored content. operationId: evaluate parameters: - schema: type: string minLength: 1 maxLength: 255 pattern: ^[\x20-\x7e]+$ description: >- Makes a retry safe. For 24 hours, the same key with the same request returns the first stored result (with Idempotent-Replayed: true); the same key with a different request is a 422 IDEMPOTENCY_KEY_REUSED. Keys are scoped to the organization and environment across every operation, so use a fresh key per request. A request that failed before its result was stored runs again when retried with its key. required: false description: >- Makes a retry safe. For 24 hours, the same key with the same request returns the first stored result (with Idempotent-Replayed: true); the same key with a different request is a 422 IDEMPOTENCY_KEY_REUSED. Keys are scoped to the organization and environment across every operation, so use a fresh key per request. A request that failed before its result was stored runs again when retried with its key. name: idempotency-key in: header - schema: type: string maxLength: 256 description: >- `wait=` (RFC 7240) shortens a single item's 10 s budget; a run ignores it. required: false description: >- `wait=` (RFC 7240) shortens a single item's 10 s budget; a run ignores it. name: prefer in: header requestBody: required: true content: application/json: examples: inline: summary: >- A dry run with the structure inline: it spends engine calls and records their usage, but registers no decision, creates no binding and stores no evaluation; drop dry_run to register the decision and store the evaluation value: state: message: >- My tent showed up two weeks late, I used it once on the trip it was for, and now it's day 39. Can I still return it? attribute_values: days_since_delivery: 39 questions: item_used: type: noul instructions: >- Has the customer used the item beyond trying it on or setting it up once? reads: - state.message defective: type: noul instructions: >- Does the customer describe a defect, damage on arrival, or the item failing under normal use? reads: - state.message attributes: days_since_delivery: type: number minimum: 0 aggregations: grant_score: type: weighted_mean inputs: - name: questions.item_used invert: true - name: questions.defective handling: type: rules rules: - when: name: attributes.days_since_delivery gt: 30 outcome: escalate - when: name: aggregations.grant_score gte: 0.72 outcome: grant - when: name: aggregations.grant_score lt: 0.38 outcome: deny else: escalate result: aggregations.handling moonbounce: decision_id: refund-exception item_id: t-001 summary: Late tent, used once, day 39 dry_run: true by_hash: summary: >- The same structure by its hash, once registered: evaluates for real and stores the evaluation value: state: message: >- My tent showed up two weeks late, I used it once on the trip it was for, and now it's day 39. Can I still return it? attribute_values: days_since_delivery: 39 moonbounce: decision_id: refund-exception item_id: t-001 structure_hash: >- sha256:bdad6e5b1b879209305f1555b43ec62666a4d74a925280c66e54cc4dc07bb1ae schema: $ref: '#/components/schemas/EvaluateBody' responses: '200': description: The evaluation headers: Idempotent-Replayed: schema: type: string enum: - 'true' description: >- Present and `true` when this is the stored result of an earlier request with the same Idempotency-Key. required: false description: >- Present and `true` when this is the stored result of an earlier request with the same Idempotency-Key. content: application/json: schema: $ref: '#/components/schemas/EvaluateResponse' '201': description: The run headers: Idempotent-Replayed: schema: type: string enum: - 'true' description: >- Present and `true` when this is the stored result of an earlier request with the same Idempotency-Key. required: false description: >- Present and `true` when this is the stored result of an earlier request with the same Idempotency-Key. content: application/json: schema: $ref: '#/components/schemas/EvaluateRunResponse' '400': description: 'Invalid request: `param` names the field at fault when one applies' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '401': description: Missing or invalid API key (reason KEY_INVALID) content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '403': description: The key may not do this content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '404': description: Not found, or not in this key's organization and environment content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '409': description: Conflict with the current state content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '410': description: >- The Idempotency-Key's first result was deleted, so it cannot be replayed content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '413': description: The HTTP body exceeds 1 MB (reason BODY_TOO_LARGE) content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '422': description: >- The request is well formed but cannot be processed (IDEMPOTENCY_KEY_REUSED requires a fresh key; REQUEST_TOO_LARGE requires a smaller request) content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '429': description: >- RATE_LIMITED: retry after Retry-After seconds; QUOTA_EXCEEDED: details.reset_at gives the daily reset time (no Retry-After) headers: Retry-After: schema: type: string description: Seconds to wait before retrying, when waiting helps. required: false description: Seconds to wait before retrying, when waiting helps. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '502': description: >- An engine failed to answer a question the result needs (type engine_failed, reason ENGINE_FAILED) content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '503': description: >- Temporarily unavailable, with Retry-After (for example reason AUTH_UNAVAILABLE, ENGINE_UNAVAILABLE or STORE_UNAVAILABLE): retry with the same Idempotency-Key headers: Retry-After: schema: type: string description: Seconds to wait before retrying, when waiting helps. required: true description: Seconds to wait before retrying, when waiting helps. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' security: - bearerAuth: - decisions:evaluate components: schemas: EvaluateBody: anyOf: - $ref: '#/components/schemas/EvaluateRequest' - $ref: '#/components/schemas/EvaluateRunRequest' EvaluateResponse: anyOf: - type: object properties: environment: $ref: '#/components/schemas/Environment' id: $ref: '#/components/schemas/EvlIdOutput' dry_run: not: {} description: 'Must be absent: only a dry run sets `dry_run`.' x-moonbounce-absent: true answers: type: object additionalProperties: $ref: '#/components/schemas/NoulAnswer' description: Each question's answer, as System One returns it. aggregations: type: object additionalProperties: $ref: '#/components/schemas/AggregationResult' via: type: string description: >- A zero-based rule index, `cases.