Evaluate an item against a decision

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 answer several features, and cache_hits is 0 today. A dry run stores only usage, returns a dry_ id and dry_run: true, and refuses Idempotency-Key. It does not register an inline spec, create a binding or cache answers. Otherwise an inline spec 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.

POST /v1/evaluate

Evaluate an item against a decision

cURL

curl --request POST \
  --url https://api.moonbounce.ai/v1/evaluate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "decision_id": "<string>",
  "subject": [
    {
      "type": "text",
      "text": "<string>",
      "name": "<string>",
      "sensitive": true
    }
  ],
  "item_id": "<string>",
  "spec": {
    "format": "moonbounce.spec/0",
    "nodes": {},
    "output": "<string>",
    "guidance": "<string>",
    "target": "<string>",
    "meta": {
      "title": "<string>",
      "description": "<string>",
      "owner": "<string>",
      "tags": [
        "<string>"
      ],
      "display": {}
    }
  },
  "weights": "default",
  "context": [
    {
      "type": "text",
      "text": "<string>",
      "name": "<string>",
      "sensitive": true
    }
  ],
  "metadata": {},
  "summary": "<string>",
  "dry_run": true,
  "structure": "<string>"
}
'

200

{
  "environment": "production",
  "id": "<string>",
  "decision_id": "<string>",
  "version": {
    "structure": "<string>",
    "weights": "<string>",
    "weights_source": "pinned",
    "weights_fitted": true,
    "binding": 2,
    "engine_profile": "<string>"
  },
  "status": "scored",
  "nodes": {},
  "engines": {},
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123
  },
  "item_id": "<string>",
  "score": 123,
  "outcome": "<string>",
  "outcomes": {
    "below": "<string>",
    "cuts": [
      {
        "at": 123,
        "outcome": "<string>"
      }
    ],
    "abstain": "<string>"
  },
  "cost": {
    "engine_calls": 1,
    "cache_hits": 1,
    "input_tokens": 1,
    "usd_micros": 1
  },
  "summary": "<string>",
  "metadata": {},
  "warnings": [
    {
      "code": "<string>",
      "message": "<string>",
      "param": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

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

idempotency-key · string

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 string length: 1 - 255

Pattern: ^[\x20-\x7e]+$

prefer · string

wait=<seconds> (RFC 7240) shortens the request's 10 s budget.

Maximum string length: 256

Body

application/json

Option 1

Option 2

decision_id · string · required

Pattern: ^[a-z][a-z0-9_.-]{0,127}$

subject · object[] · required

Required array length: 1 - 64 elements

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Show child attributes

item_id · string · required

Required string length: 1 - 256

spec · object · required

Show child attributes

weights · enum<string> string · default: default

Available options: default

outcomes · object

Show child attributes

context · object[]

Maximum array length: 64

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Show child attributes

metadata · object

Caller key-values, stored with the evaluation and never shown to the model. Keys starting mb. are reserved for Moonbounce provenance: mb.commit, mb.branch, mb.service and mb.release, which say where a call came from.

Show child attributes

summary · string

Required string length: 1 - 140

dry_run · boolean

Spends engine calls and stores only usage, with no evaluation or feedback target. Refuses Idempotency-Key.

structure · string

Pattern: ^sha256:[0-9a-f]{64}$

Response

200

application/json

The evaluation

Option 1

Option 2

environment · enum<string> · required

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.

Available options: production, test

id · string · required

Pattern: ^evl_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

decision_id · string · required

Pattern: ^[a-z][a-z0-9_.-]{0,127}$

version · object · required

Show child attributes

status · enum<string> · required

Available options: scored, no_outcomes, abstained

nodes · object · required

The value of each of the spec's named nodes, features and aggregators alike, keyed by node name. Every value carries its type; a node with an answer has value, one without has abstained or failed.

Show child attributes

engines · object · required

Show child attributes

usage · object · required

Show child attributes

item_id · string · required

score · number

outcome · string

Pattern: ^[a-z][a-z0-9_]{0,63}$

outcomes · object

Show child attributes

cost · object

Always present on fresh responses; absent only on an idempotent replay of a response stored before costs were reported.

Show child attributes

summary · string

metadata · object

Caller key-values, stored with the evaluation and never shown to the model. Keys starting mb. are reserved for Moonbounce provenance: mb.commit, mb.branch, mb.service and mb.release, which say where a call came from.

Show child attributes

warnings · object[]

Show child attributes