Merge API Documentation

Decision models return typed answers about a state you supply, such as a ticket, log line, or JSON object. Use them to route, triage, score, or gate work when you need a value, not text. They return a probability distribution, so they’re cheaper and faster than asking a chat model for JSON.

Send a decision request

Send state, the content being judged, and questions, a map of named questions whose keys come back as the keys of answers.

curl https://api-gateway.merge.dev/v1/decisions \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "Our invoice shows $4,200 but the contract says $3,800. Third month running. Fix this today or we cancel.",
    "questions": {
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this message?",
        "criteria": ["not urgent", "somewhat urgent", "urgent", "critical"]
      },
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Invoice and payment issues",
          "support": "Product and technical issues",
          "sales": "Upgrades and renewals"
        }
      },
      "churn_risk": {"type": "noul", "instructions": "Is this customer at risk of churning?"}
    }
  }'

The cURL request returns:

{
  "object": "decision",
  "model": "jev-1.13.0",
  "vendor": "typesafe",
  "answers": {
    "urgency": {
      "type": "score",
      "score": 2.84,
      "confidence": 0.84,
      "legend": {"0": "not urgent", "1": "somewhat urgent", "2": "urgent", "3": "critical"},
      "probabilities": {"0": 0.0, "1": 0.0, "2": 0.16, "3": 0.84}
    },
    "team": {
      "type": "choice",
      "choice": "billing",
      "confidence": 1.0,
      "probabilities": {"billing": 1.0, "support": 0.0, "sales": 0.0}
    },
    "churn_risk": {"type": "noul", "noul": 0.95}
  },
  "usage": {"input_tokens": 403, "output_tokens": 70, "total_tokens": 473, "cost": 1.6926e-05}
}

score is a probability-weighted position on your scale, not a bucket index. noul is the probability of yes, with no separate confidence. confidence is computed differently for score and choice, so calibrate thresholds per type, or read probabilities. model is the concrete version that answered, not the vendor alias you sent, such as jev-latest. Pin a version, since a new one moves your calibrated thresholds.

Reference

Type	Answer	`criteria`
`noul`	A probability from 0 to 1 that the answer is yes	Optional object keyed `true` and `false`
`choice`	One option plus the distribution over all of them	Required object of at least two options, each mapped to the description the model uses to tell them apart
`score`	A position on your scale plus the distribution over levels	Required array of at least two ordered levels

Every question needs non-empty instructions.

Field	Notes
`model`	Required. A decision model, such as `typesafe/jev-1.13`. Gateway `@alias/...` IDs return `400 alias_not_supported`.
`state`	Required. String, object, or array.
`questions`	Required. Up to 100 per request.
`vendor`	Pin the execution vendor. A mismatch returns `400 vendor_unavailable`.
`customer`	Customer UUID to scope the key, budget, and usage to

Limit or error	Value
Token budget	64k tokens across `state` and all questions. Over it returns `400 max_tokens_exceeded`.
Unknown fields, such as `stream`	`422`, rather than being ignored
Missing `criteria`, fewer than two options, or an unknown type	`422` before any vendor call
Vendor-side validation failure	`400 validation_error`
Decision model sent to `/v1/responses`	`400 unsupported_endpoint_for_model`
DLP match	`422 blocked_by_dlp_policy`, including for organizations in redact mode

Decision models aren’t routing-policy candidates, don’t stream, and take no sampling parameters. They run on Merge-managed keys only, with no BYOK, and aren’t available to organizations with zero data retention. Input and output bill at the route’s rates (output is $0 on typesafe/jev-1.13 today), reported as usage.cost in USD. GET /v1/models lists decision models with output: ["decision"], paged at 50 by default, so pass limit (up to 500) when you search.

Next steps

Structured outputs

Schema-constrained JSON from a chat model when you need generated content

Errors

Every error code Gateway returns and what to do