Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aethis.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every response from POST /api/v1/public/decide (and POST /rulesets/{id}/explain-failure) carries a small set of envelope fields that let callers reference, verify, and replay a specific decision — without the server having to echo potentially-PII inputs back. If you’re building anything regulated, audited, or support-ticketable, read this page.

​
The fields

FieldTypeExampleReplay-critical
decision_idstringdec_k3h9s2MnPq_7xZbA✅
inputs_hashstringsha256:5f4dcc3b...✅
engine_versionstringaethis-core@0.7.1✅
ruleset_id + ruleset_version or rulebook_idstringaethis/uk-fsm/child-eligibility, 1✅
decision_timestring (ISO-8601 UTC)2026-04-17T12:34:56.789Zinformational*
*decision_time is only replay-critical when a rule references wall-clock time.

​
decision_id

Unique per invocation, format dec_<16 urlsafe chars>. Fresh on every call — two identical requests get different IDs even when the server serves the response from its decision cache. Use it in bug reports, support tickets, and client-side logs. The server emits a structured log line keyed by decision_id, so operators can trace a user-quoted ID back to full context.

​
inputs_hash

Algorithm-prefixed SHA-256 over the RFC 8785 canonical form of field_values. Invariant under key reordering, whitespace, and 1 vs 1.0 vs 1e0. Lets a caller prove “this decision was computed from exactly these inputs” without the server persisting or echoing the values. The sha256: prefix is forward-compatibility for when the algorithm rotates — parsers should split on : and route by algorithm.

​
engine_version

Product-prefixed semver, format aethis-core@<semver>. Same value for the lifetime of a server process. Different engine versions can produce different outcomes for identical inputs and rule artefacts if DSL semantics or solver behaviour change — reliable replay requires matching the engine version.

​
ruleset_version / rulebook_id

Ruleset calls return ruleset_id + ruleset_version; rulebook calls return rulebook_id. Together with engine_version, these pin the exact rule artefact used.

​
How to replay a decision

The envelope is designed for two-party replay: the caller keeps the inputs they sent, the server re-runs the engine when asked.
  1. Retain the original field_values and the full envelope on the caller side.
  2. Re-run POST /decide with the same field_values and ruleset_id.
  3. Verify:
    • inputs_hash matches the retained value → inputs are identical
    • engine_version matches → engine build is the same
    • ruleset_id + ruleset_version match → rule artefact is the same
    • The new decision equals the original → decision is reproducible
The new response will have a different decision_id and decision_time — those are per-invocation and deliberately excluded from the replay contract.

​
Caching interaction

The server caches responses for identical (ruleset_id, field_values, flags) combinations for up to 10 minutes. Per-call envelope fields (decision_id, decision_time, inputs_hash, engine_version) are stripped before caching and stamped fresh on every response. A cache hit is invisible from the envelope’s perspective — the ID is fresh, the hash is computed from the caller’s actual inputs, the timestamp is current.

​
Example

{
  "decision": "eligible",
  "fields_provided": 2,
  "fields_evaluated": 2,
  "decision_id": "dec_k3h9s2MnPq_7xZbA",
  "inputs_hash": "sha256:5f4dcc3b5aa765d61d8327deb882cf99",
  "engine_version": "aethis-core@0.7.1",
  "ruleset_id": "aethis/uk-fsm/child-eligibility",
  "ruleset_version": "1",
  "decision_time": "2026-04-17T12:34:56.789Z"
}

​
What to log on your side

For audited workloads, retain at minimum:
  • decision_id — your handle for this decision
  • inputs_hash — proves the inputs later
  • engine_version + ruleset_id/ruleset_version — pins the artefact
  • Your own request correlation ID (e.g. application trace ID)
Retain the raw field_values separately if your compliance regime requires input-level audit; inputs_hash alone is sufficient for reproducibility proof, but not for “what exactly did the user submit” questions.