curl --request POST \
--url https://api.moonbounce.ai/v1/evaluate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"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
}
}
EOF{
"environment": "production",
"id": "<string>",
"answers": {},
"aggregations": {},
"moonbounce": {
"decision_id": "<string>",
"item_id": "<string>",
"structure_hash": "<string>",
"metadata": {},
"summary": "<string>"
},
"version": {
"structure_hash": "<string>",
"binding": 2,
"engine_profile": "<string>"
},
"engines": {},
"usage": {
"input_tokens": 123,
"output_tokens": 123
},
"status": "computed",
"value": 123,
"dry_run": "<unknown>",
"via": "<string>",
"cost": {
"engine_calls": 1,
"cache_hits": 1,
"input_tokens": 1,
"usd_micros": 1
},
"calls": [
{
"questions": [
"<string>"
],
"reads": [
"state.message"
],
"input_tokens": 1
}
],
"outcome": "<unknown>",
"missing": [
"questions.asks_for_refund"
]
}{
"run_id": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"dry_run": true,
"environment": "production",
"decision_id": "<string>",
"version": {
"structure_hash": "<string>",
"engine_profile": "<string>",
"binding": 1
},
"counts": {
"total": 1,
"decided": 1,
"computed": 1,
"abstained": 1,
"failed": 1,
"labeled": 1
},
"cost": {
"engine_calls": 1,
"cache_hits": 1,
"input_tokens": 1,
"usd_micros": 1
},
"results": [
{
"item_id": "<string>",
"status": "decided",
"evaluation_id": "<string>",
"id": "<string>",
"outcome": "<string>",
"value": 123,
"via": "<string>",
"missing": [
"<string>"
],
"answers": {},
"attributes": {},
"cost": {
"engine_calls": 1,
"cache_hits": 1,
"input_tokens": 1,
"usd_micros": 1
},
"evaluation": {
"environment": "production",
"id": "<string>",
"answers": {},
"aggregations": {},
"moonbounce": {
"decision_id": "<string>",
"item_id": "<string>",
"structure_hash": "<string>",
"metadata": {},
"summary": "<string>"
},
"version": {
"structure_hash": "<string>",
"binding": 2,
"engine_profile": "<string>"
},
"engines": {},
"usage": {
"input_tokens": 123,
"output_tokens": 123
},
"status": "computed",
"value": 123,
"dry_run": "<unknown>",
"via": "<string>",
"cost": {
"engine_calls": 1,
"cache_hits": 1,
"input_tokens": 1,
"usd_micros": 1
},
"calls": [
{
"questions": [
"<string>"
],
"reads": [
"state.message"
],
"input_tokens": 1
}
],
"outcome": "<unknown>",
"missing": [
"questions.asks_for_refund"
]
},
"error": {
"code": "<string>",
"message": "<string>",
"retryable": true
}
}
],
"cases": {
"total": 1,
"excluded": {
"withdrawn": 2,
"retired": 2,
"excluded": 2,
"contested": 2,
"no_consensus": 2,
"no_outcome": 2,
"outcome_not_in_result": 2,
"no_deciding_ballot": 2,
"attribute_inputs_unavailable": 2,
"no_split": 2,
"duplicate_group": 2
},
"next_cursor": "<string>"
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}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=<seconds> 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.<i>. 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.
curl --request POST \
--url https://api.moonbounce.ai/v1/evaluate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"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
}
}
EOF{
"environment": "production",
"id": "<string>",
"answers": {},
"aggregations": {},
"moonbounce": {
"decision_id": "<string>",
"item_id": "<string>",
"structure_hash": "<string>",
"metadata": {},
"summary": "<string>"
},
"version": {
"structure_hash": "<string>",
"binding": 2,
"engine_profile": "<string>"
},
"engines": {},
"usage": {
"input_tokens": 123,
"output_tokens": 123
},
"status": "computed",
"value": 123,
"dry_run": "<unknown>",
"via": "<string>",
"cost": {
"engine_calls": 1,
"cache_hits": 1,
"input_tokens": 1,
"usd_micros": 1
},
"calls": [
{
"questions": [
"<string>"
],
"reads": [
"state.message"
],
"input_tokens": 1
}
],
"outcome": "<unknown>",
"missing": [
"questions.asks_for_refund"
]
}{
"run_id": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"dry_run": true,
"environment": "production",
"decision_id": "<string>",
"version": {
"structure_hash": "<string>",
"engine_profile": "<string>",
"binding": 1
},
"counts": {
"total": 1,
"decided": 1,
"computed": 1,
"abstained": 1,
"failed": 1,
"labeled": 1
},
"cost": {
"engine_calls": 1,
"cache_hits": 1,
"input_tokens": 1,
"usd_micros": 1
},
"results": [
{
"item_id": "<string>",
"status": "decided",
"evaluation_id": "<string>",
"id": "<string>",
"outcome": "<string>",
"value": 123,
"via": "<string>",
"missing": [
"<string>"
],
"answers": {},
"attributes": {},
"cost": {
"engine_calls": 1,
"cache_hits": 1,
"input_tokens": 1,
"usd_micros": 1
},
"evaluation": {
"environment": "production",
"id": "<string>",
"answers": {},
"aggregations": {},
"moonbounce": {
"decision_id": "<string>",
"item_id": "<string>",
"structure_hash": "<string>",
"metadata": {},
"summary": "<string>"
},
"version": {
"structure_hash": "<string>",
"binding": 2,
"engine_profile": "<string>"
},
"engines": {},
"usage": {
"input_tokens": 123,
"output_tokens": 123
},
"status": "computed",
"value": 123,
"dry_run": "<unknown>",
"via": "<string>",
"cost": {
"engine_calls": 1,
"cache_hits": 1,
"input_tokens": 1,
"usd_micros": 1
},
"calls": [
{
"questions": [
"<string>"
],
"reads": [
"state.message"
],
"input_tokens": 1
}
],
"outcome": "<unknown>",
"missing": [
"questions.asks_for_refund"
]
},
"error": {
"code": "<string>",
"message": "<string>",
"retryable": true
}
}
],
"cases": {
"total": 1,
"excluded": {
"withdrawn": 2,
"retired": 2,
"excluded": 2,
"contested": 2,
"no_consensus": 2,
"no_outcome": 2,
"outcome_not_in_result": 2,
"no_deciding_ballot": 2,
"attribute_inputs_unavailable": 2,
"no_split": 2,
"duplicate_group": 2
},
"next_cursor": "<string>"
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"reason": "<string>",
"param": "<string>",
"details": {
"issues": [
{
"param": "<string>",
"code": "<string>",
"message": "<string>"
}
]
}
}
}Authorizations
An API key, sent as Authorization: Bearer <key>. Each operation lists the scope its key needs: decisions:evaluate (evaluate and read evaluations), decisions:feedback (your app's feedback) or decisions:develop (everything else, including owner feedback and the review queue). An operation listing no scope takes any scoped key. A key with no scope, or without the operation's, gets 403 INSUFFICIENT_SCOPE.
Headers
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.
1 - 255^[\x20-\x7e]+$wait=<seconds> (RFC 7240) shortens a single item's 10 s budget; a run ignores it.
256Body
- Option 1
- Option 2
- Option 3
- Option 4
System One questions, keyed by name.
Show child attributes
Show child attributes
The final feature's path, such as aggregations.band.
1 - 80"questions.asks_for_refund"
"aggregations.band"
The content the questions evaluate: any JSON value, including a string or JSON null, as in System One. A question with reads (state.<key> paths, or deeper such as state.order.id) sees only those values, nested as in the state.
Show child attributes
Show child attributes
Values your app supplies with each call in attribute_values. The model never sees them.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
An assertion, not a choice: the decision's engine binding picks the model (set it with POST /v1/decisions/{decision_id}/binding/revisions). Leave it out to use the binding. When sent, every question's bound model must be this one, or the call is a 400 invalid_request with param model, before any engine call and before anything is written: a refused call registers nothing (not even an inline structure seen for the first time, or the binding it would create) and creates no content key. Accepted for System One compatibility.
1 - 128This call's attribute values. Each must match its declaration; a declared one without a default is required.
Show child attributes
Show child attributes
Response
The evaluation
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
The environment of the key that made the call: production or test. Evaluations, feedback, reviews and suggestions are separate per environment; registered structures are shared.
production, test ^evl_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$Each question's answer, as System One returns it.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
computed Must be absent: only a dry run sets dry_run.
A zero-based rule index, cases.<label> for an exact matched case, or else for the fallback.
Always present on fresh responses; absent only on an idempotent replay of a response stored before costs were reported.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Must be absent: a computed result is a number, with no outcome.
The questions the result depends on (through result and every aggregation on its path) that have no answer, abstained or failed, as questions.x paths in authored question order. Absent when none is missing; reported for every status. A caller who must not act on partial evidence checks that it is absent, for example status === "decided" && !missing.
A feature's path: questions.<name>, attributes.<name> or aggregations.<name>.
1 - 80