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.

You are a coding agent. You want to answer ‘is this person eligible for X?’ This page is the full sequence. The three-call pattern:
  1. Discover the schema — what fields does the ruleset need?
  2. Collect values — either from user input, context, or an upstream tool.
  3. Decide — send field values, receive a decision envelope.
Optional fourth step: explain — when the decision is not_eligible and the user asks why. Uses the public FSM child-eligibility ruleset. No API key needed.

​
1. Discover the schema

curl https://api.aethis.ai/api/v1/public/rulesets/aethis/uk-fsm/child-eligibility/schema

{
  "ruleset_id": "aethis/uk-fsm/child-eligibility",
  "fields": [
    {
      "field_id": "child.age",
      "field_type": "int",
      "description": "Child's age in whole years at the start of the relevant academic year (1 September).",
      "question": "Child's age in whole years at the start of the relevant academic year (1 September).",
      "enum_values": null
    },
    {
      "field_id": "child.school_type",
      "field_type": "enum",
      "description": "Type of school the child attends.",
      "enum_values": ["state_funded", "independent", "home_educated"]
    }
  ]
}
What the agent needs: a map from field_id → value. For enum fields, only values listed in enum_values are accepted. For int / bool, standard JSON. Via MCP this is one tool call: 
aethis_schema({ ruleset_id: "aethis/uk-fsm/child-eligibility" })

​
2. Collect field values

Agent-side logic — the API doesn’t care how you got the values. In practice: ask the user, read from a session object, or derive from upstream context. If a field is missing, the decision can still return (as undetermined) — just be ready to ask for it next.

​
3. Decide

curl -X POST https://api.aethis.ai/api/v1/public/decide \
  -H "Content-Type: application/json" \
  -d '{
    "ruleset_id": "aethis/uk-fsm/child-eligibility",
    "field_values": {
      "child.age": 10,
      "child.school_type": "state_funded"
    }
  }'

{
  "decision": "eligible",
  "fields_provided": 2,
  "fields_evaluated": 2,
  "slug": "aethis/uk-fsm/child-eligibility",
  "ruleset_version": "unknown",
  "engine_version": "aethis-core@0.8.1",
  "decision_id": "dec_...",
  "inputs_hash": "sha256:...",
  "decision_time": "2026-04-19T22:00:00.000Z"
}
Three possible outcomes:
  • eligible — all criteria satisfied
  • not_eligible — one or more criteria failed
  • undetermined — engine couldn’t decide (missing field, discretionary clause, or case outside the compiled rules)
When you get undetermined, inspect missing_fields in the response. Add the missing values and call again. Via MCP: 
aethis_decide({
  ruleset_id: "aethis/uk-fsm/child-eligibility",
  field_values: { "child.age": 10, "child.school_type": "state_funded" },
  include_trace: true
})
include_trace: true adds per-group outcomes so you can show the user why.

​
4. (Optional) Explain the decision

For a not_eligible where the user asks “why”: 
# Note: /explain-failure currently requires the concrete ruleset_id on its
# path, not a slug. Get it from the /decide envelope's ruleset_id field
# (alongside the slug you called with).
curl -X POST https://api.aethis.ai/api/v1/public/rulesets/$BUNDLE_ID/explain-failure \
  -H "Content-Type: application/json" \
  -d '{
    "field_values": { "child.age": 16, "child.school_type": "state_funded" },
    "expected_outcome": "eligible"
  }'
Returns human-readable reasons for the failure, keyed by criterion, plus a DSL mechanism hint. Via MCP (works with either slug or ruleset_id — the MCP tool resolves slugs client-side): 
aethis_explain_failure({
  ruleset_id: "aethis/uk-fsm/child-eligibility",
  field_values: { "child.age": 16, "child.school_type": "state_funded" },
  expected_outcome: "eligible"
})

​
Composing multiple sections (rulebook)

If your domain has more than one section and you want one decision over the composition (e.g. FSM: child eligibility AND (household criteria OR universal infant)), use the rulebook_id field instead of ruleset_id. Rulebook evaluation always requires an API key — see Nomenclature for why. 
curl -X POST https://api.aethis.ai/api/v1/public/decide \
  -H "Content-Type: application/json" \
  -H "x-api-key: $AETHIS_API_KEY" \
  -d '{
    "rulebook_id": "aethis/uk-fsm",
    "field_values": { ... }
  }'
The response includes a section_results array with each section’s individual outcome.

​
Next steps