Warddocs
Concepts

The decision envelope

Every POST /decide answer has the same top-level fields. Branch on decision; read result for the details of each capability.

Field Type Meaning
id string Decision id (dec_…). Use it for feedback, evidence and Ask
object "decision"
model string The release that answered, e.g. ward-1.4.6
components object Version of each part that ran (screening, statement_matrix, …)
type string The decision type
created integer Unix time
decision APPROVE | STEP_UP | DECLINE What to do
score number | null The capability's score (0–1)
score_kind string | null What the score is: calibrated, heuristic, name_similarity, kya, … See Scores
band string low / medium / high for statement, credit and merchant
signals string[] Codes of what fired, e.g. STM_PASS_THROUGH, EMAIL_DISPOSABLE
typologies string[] Typology ids the signals point to (fraud and AML catalogs)
needs object[] Fields not sent that would sharpen the answer, each with why
coverage object How much of the input Ward could read (sufficient, limited, insufficient)
subject object | null The customer's profile when subject_ref is known
session_id string | null Echo
result object The capability's full native answer
client_model object Your account's trained model, advisory (see Feedback)
policy_matches object[] Your own policies the case touches (cited, never applied)
review_sample boolean Marked for random review (selection-bias control)
context object The session meter: window_tokens, used_tokens, remaining_tokens, used_pct, balance_usd
latency_ms, timing number, object Total time and inference time

Reading result

Each capability page documents its result. Fields common to several:

  • checks: which lists ran and their status (checked, not_checked, failed). "No hits" with not_checked is not clear.
  • notes: assumptions Ward made (date order, currency, a column it guessed).
  • signals inside result: full objects with code, weight, detail and the rows they cite; the envelope's signals is the list of codes.

Fields the client model adds

When your validated model sets the decision (see Feedback), the envelope also carries:

Field Meaning
decided_by client_model
decision_rules, score_rules What the rules decided and scored, kept for audit
hard_stops Signals that kept the stricter of the two decisions (strong sanctions match, device or IP linked to fraud, invalid cryptogram, ATC replay)
review_floors Signals that kept the decision at STEP_UP or above (a potential sanctions match, a high-risk jurisdiction)

Risk lines (Ward 1.5, beta)

Off by default; enabled per deployment. With it on, the answer adds typed answers per risk and changes no existing field.

Field Type Meaning
risks.fraud, risks.aml, risks.sanctions object One entry per risk the call assessed. A payment has fraud, and sanctions for bank transfers; a statement has aml, fraud and sanctions; a screen has sanctions
risks.<line>.status final | partial | insufficient_data Whether the line could answer. partial: only part of the evidence was readable on this call (on a bank transfer, AML shows the payee's jurisdiction only). insufficient_data is never a clear result
risks.<line>.review_floors, hard_stop string[], boolean What on this line keeps the decision at STEP_UP or above, or declines it
risks.<line>.outcome Choice The line's own answer, for example {"type": "choice", "choice": "strong_match"}. A reference-calibrated card fraud line adds probabilities per option and confidence: how sure Ward is that the case sits on the chosen side of each cut-off. The choice always comes from the cut-offs; a near-even split marks a close call
risks.<line>.raw_score number | null The line's score before any calibration
risks.<line>.p, interval number | null, [low, high] A probability when score_kind is calibrated or reference_calibrated, with a 90% interval for the latter. null for a heuristic score with no reference map
risks.<line>.calibration object For reference_calibrated: set, simulated, heldout_ece, reference_rate, prior and prior_source (default or client), the block's cases and bad, and the map hash
risks.<line>.score_kind, evidence_tier, advisory How far the score can be read (see Scores)
risks.<line>.signals, typologies string[], object[] What fired on this line; each typology with its catalog domain (agentic, card, crypto, financial)
risks.<line>.gates boolean Whether this line can move decision
risks.aml.priority Score AML review priority: clear, monitor, alert, escalate (cuts 0.30, 0.60, 0.80 on the line's raw score), with level probabilities when the line is reference-calibrated. On a payment it needs account.movements (10 or more over 30 days or more); with_this_payment lists the signals the payment itself brings. Advisory: gates is false
outcome Choice or Score For screen, statement, ato and agent: the answer in the type's own words (potential_match, the statement band as a level 0 to 2, likely_account_takeover, verified_with_flags)
answers object Yes or no questions answered on the call, as Nouls: {"type": "noul", "noul": 0.08} is the probability of yes. First-party misuse and takeover when their models are on, and the questions you sent
risks.fraud.typology Choice On payments: the typology as a walk down the catalogs (path: domain, family, typology), one level of probabilities per step, the first scaled by the line's probability (none is the rest). Shares of signal strength, not a calibrated distribution
not_assessed object[] Risks this call could not judge, each with why. A single payment has no AML reading; a card payment is not screened
initiator, treatment object For payments: who initiated it, and what to do when a scam leads (also in result)
decision_ward_1, aml_gated string, boolean With model: "ward-2" only: what ward-1 would have decided when the two differ, and whether the AML line set the decision (see Models)

Stability

Field names are stable within a major version. New fields can appear at any time; ignore what you do not know. Pin model to a release to keep thresholds and weights fixed (see Models).