Decisions that know when to ask.

RequestResponse

cURLTypeScriptPython

curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "restricted_merchant",
    "input": {
      "merchant": "DRAFTKINGS",
      "mcc": "7995"
    }
  }'

const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    decision: "restricted_merchant",
    input: { merchant: "DRAFTKINGS", mcc: "7995" },
  }),
});

const { answer, probability, reasons, abstain } =
  await res.json();

import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json={
        "decision": "restricted_merchant",
        "input": {"merchant": "DRAFTKINGS", "mcc": "7995"},
    },
    timeout=10,
)
result = res.json()

Response200 OK

{
  "decision": "restricted_merchant",
  "type": "predicate",
  "answer": true,
  "probability": 0.97,
  "reasons": [
    "mcc_7995",
    "rule_gambling_category",
    "kind_sportsbook"
  ],
  "abstain": false
}

An example call. The probability is an illustration.1

Nine decisions built.

Five more are built

Built means written and tested against a stand-in model in our test suite. None is running at a bank, credit union or health company yet, and the five newer decisions are not benchmarked.

The Understanding API hasn’t been run on our eval yet. See the eval

How a call is routed.

Packet routes

Moving dots are illustrative, not traffic. Each decision returns answer · probability · reasons · abstain.

What every answer carries

Under your line, a person decides.

How the line works

A sweepstakes merchantabstain: true

Reason codes on every decision.

All reason codes

Reason codesreceipt_match

amount_exact
amount_within_3pct
amount_differs
name_match
name_differs
within_a_day
within_3_days
over_3_days
no_single_charge
rule_agrees
rule_differs
rule_no_purchases
model_declined

Your own question.

The same six fields, without our domain facts or reason codes.

How to write one

Six fields on every answer.

decisionstring or null
typestring
answerboolean, string, number or null
probabilitynumber or null
reasonsarray of strings
abstainboolean

JSON over HTTPS at POST /v1/understand, or up to 100 calls at once at POST /v1/understand/batch, with your key as a Bearer token. Any HTTP client works.

Read the API reference

Tell us what you’d decide first.

Write to us. Send hello@theunderstanding.company your company and the decisions you’d send first.

Questions.

Is the endpoint live?

Not yet. The endpoint, the developer console and the MCP server are built and tested, but not deployed. When they open, you sign up in the console, make your own keys and get $5 of free credit.

What does it cost?

The planned price is $0.10 per million input tokens, with no charge for output. A new account gets $5 of free credit. Answers a rule settles without the model, calls that fail and replayed retries cost nothing. Nothing is charged until the API opens.

What data does it need?

Most decisions ask only for a descriptor, a category code, amounts and dates. support_route, member_route and return_window also take text you choose to send, and the three health decisions take derived numbers or generic labels. Send no names, account numbers or balances. Bodies over 256 KB are refused. The three health decisions are built but not open, so do not send protected health information, including in your own questions.

What happens to our data?

For each answered call we log the decision name, the answer type, the abstain flag, the model, whether a rule settled it and how long the model took; for a failed call, the error’s type and status. Never your input. Every response is marked no-store. By default, the API requests routing only to model providers with zero-data-retention and no-training agreements; that isn’t yet verified by a live call. We’ll confirm the details in writing before your first live call.

Can I use it for credit decisions?

No. Credit underwriting and adverse action carry their own notice rules under the Equal Credit Opportunity Act and Regulation B. The API doesn’t make those decisions, and its answers shouldn’t feed a credit line, an overdraft limit or an account closure. It doesn’t diagnose or verify identity either.

All questions