Decisions

A decision is one named question answered with a calibrated probability. All six are POST /v1/decisions/<name>, take JSON, need the decisions:write scope and return the same envelope. Each is billed only when it returns an answer.

Decision	Price per call	Question
qualify_firm	$0.005	Is this firm in my ICP?
score_signal	$0.005	Does this event matter, and is now the time?
pick_person	$0.005	Who at this firm should I write to?
triage_reply	$0.003	What does this reply mean?
right_person	$0.003	Is this the right person to contact?
should_send	$0.003	Should this message go out now?

Which one to call

Your agent is about to…	Call	Branch on
spend effort on a company	qualify_firm	answer: fit or not_fit
act on something that happened to a company	score_signal	answer, then act_now and window_days
choose who at a firm to contact	pick_person	people[0], answer: pick or no_pick
handle a reply	triage_reply	answer: the reply state, or needs_review
check one contact before using them	right_person	answer: right_person or not_right_person
send a prepared message	should_send	answer: send or hold, then hold_reason

The common envelope

Every decision returns these fields, plus a few specific to the decision.

Field	Meaning
id	The decision id (dec_...). Report outcomes against it.
decision	The decision name.
version	The API version that answered.
question_set_version	The question set that answered. Match it to the eval results.
p	Calibrated probability. Always present.
answer	p against your threshold. Branch on this.
reason_code	Fixed enum per decision (listed on each decision page).
reason	A short template sentence. Never free text from a large model.
evidence	Sources with URL and date. source is an index slug or request.
calibration	basis (org, segment or global), n_outcomes, threshold.
cost	decision_usd, vendor_usd, total_usd.
balance_usd	Balance after this call.
latency_ms	Server time for the call.

Rules that hold for every decision

• Idempotency. Send Idempotency-Key (a UUID). A repeat within 24 hours returns the stored response and bills nothing. Reusing a key with a different body returns 409 idempotency_conflict.
• Spend caps. Send X-Max-Cost-USD. A call that would cost more is refused with 402 max_cost_exceeded before any spend.
• Misses are free. No answer, an error, or a refused call bills nothing.
• Decision model down. You get 503 decision_unavailable with Retry-After. Retry with the same Idempotency-Key. Nothing is billed.
• Limits. Request bodies up to 256 KB, rosters up to 50 people, threads up to 40 messages of 8 KB each.
• Fetch later. GET /v1/decisions/{id} returns any past decision, free.