Response contract

Every ask and MCP answer conforms to this. It is the contract our benchmark measures — so it is documented here, verifiably, not just asserted.

refuse, don't guess

Calling ask

One HTTP call. channel is agent (public facts only) or human (public + humans-only). question max 2000 characters. No API key needed within the free per-IP daily quota.

POST https://intesta.io/api/v1/entities/{domain}/ask
Content-Type: application/json

{ "question": "What is the minimum payout for Monero (XMR)?", "channel": "agent" }

The MCP tool ask (endpoint https://intesta.io/mcp) takes the same domain + question and returns the same body.

Example response per outcome

`answered`

{
  "refused": false, "outcome": "answered", "stale": false,
  "as_of": "2026-09-08T12:01:51Z",
  "facts": [{"id": "1536f2b8-…", "statement": "Monero (XMR): minimum payout 0.1 XMR.",
             "category": "economics", "source": "https://smoozypool.es/api/pools",
             "verification_source": "refresher", "effective_expiry": "2026-09-15T12:01:51Z",
             "evidence_class": "auto_collected", "stale": false}],
  "answer": "Monero (XMR): minimum payout 0.1 XMR.", "retrieval": "lexical"
}

`answered_with_stale_flag`

{
  "refused": false, "outcome": "answered_with_stale_flag", "stale": true,
  "as_of": "2026-08-01T00:00:00Z",
  "facts": [{"id": "…", "statement": "…", "stale": true,
             "effective_expiry": "2026-08-08T00:00:00Z"}],
  "answer": "…", "retrieval": "lexical"
}  // only for stale_mode=flag, non-volatile categories

`refused_not_attested`

{
  "refused": true, "outcome": "refused_not_attested", "stale": false,
  "reason": "no_matching_fact", "off_topic": false, "facts": [], "answer": null,
  "message": "The fact passport contains no matching fact for this question…"
}

`refused_stale`

{
  "refused": true, "outcome": "refused_stale", "stale": true,
  "reason": "stale_fact", "as_of": "2026-08-01T00:00:00Z", "facts": [], "answer": null,
  "message": "A matching fact exists but is older than its freshness budget; withheld…"
}

Outcomes — exactly four

outcome	when	shape
`answered`	A fresh, attested fact matched the question's subject AND attribute.	facts[] non-empty, stale=false
`answered_with_stale_flag`	A matching fact is past its freshness budget but the entity's stale_mode is 'flag' and the category is not volatile — served WITH stale=true so the caller can decide.	facts[] non-empty, stale=true
`refused_not_attested`	No fact matches the (subject, attribute) — including: subject absent, attribute absent, off-topic (off_topic=true), or a false-premise with nothing attested. The engine never guesses.	facts=[], refused=true
`refused_stale`	A matching fact EXISTS but is older than last_verified_at + max_age(category) and is withheld rather than served stale (volatile categories always refuse).	facts=[], refused=true, stale=true

off_topic is a boolean FLAG, not a fifth outcome: an off-topic question returns outcome=refused_not_attested with off_topic=true.

Machine fields

field	type	meaning / when present
`refused`	`bool`	true on both refused_* outcomes, false on both answered_*.
`outcome`	`enum`	EXACTLY one of the four above. No other value is ever returned.
`stale`	`bool`	true on refused_stale and answered_with_stale_flag; computed on read from last_verified_at + max_age(category) vs now — never a stored flag.
`as_of`	`iso8601 \| null`	freshness timestamp of the served/withheld fact set; null on refused_not_attested.
`reason`	`str \| null`	machine reason: no_matching_fact \| stale_fact \| off_topic.
`off_topic`	`bool`	flag only — an off-topic question is outcome=refused_not_attested with off_topic=true. NOT a separate outcome.
`message`	`str \| null`	human-readable text on a refusal; null when answered.
`answer / answer_text`	`str \| null`	the composed answer on answered_*; null on refusals.
`retrieval`	`enum`	how facts were found: lexical \| semantic \| none (a mechanism label, independent of outcome).
`escalate`	`bool`	true if the question tripped a human-escalation trigger.
`facts[].id`	`uuid`	the matched fact's stable id.
`facts[].source / source_ref`	`str`	provenance URL/reference of the fact.
`facts[].evidence_class / attestation_status`	`enum`	auto_collected \| owner_claimed \| attested.
`facts[].verification_source`	`enum`	who last confirmed freshness: refresher \| backfill \| manual \| owner.
`facts[].valid_from / as_of / expires_at`	`iso8601 \| null`	validity window of the fact.
`facts[].effective_expiry`	`iso8601 \| null`	when the fact stops being served fresh = min(expires_at, last_verified_at + max_age(category)). Same field as in llms.txt.
`facts[].stale`	`bool`	per-fact staleness, computed on read.

Freshness

stale and effective_expiry are computed on read from last_verified_at + max_age(category) vs now — never a stored flag maintained by a job. Volatile categories (economics, logistics) always refuse when stale; others follow the entity's stale_mode (refuse | flag).

category	max_age
availability / stock (`logistics`)	1d
prices, payouts, deadlines (`economics`)	7d
policy (`policy`)	30d
infrastructure (`infrastructure`)	30d
security (`security`)	30d
other (`other`)	30d
product (`product`)	60d
company (`company`)	180d
legal (`legal`)	180d