Evaluate a case

api.aethis.ai serves engine 0.49.1, which is the contract these pages describe; every response carries engine_version so you can confirm which build answered you. What the deployed engine serves.

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:

Discover the schema — what fields does the ruleset need?
Collect values — either from user input, context, or an upstream tool.
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 Free School Meals (FSM) child-eligibility ruleset. No API key needed.

1. Discover the schema

CLI
Python SDK
curl
MCP

aethis fields -b aethis/uk-fsm/child-eligibility

from aethis_sdk import Aethis

with Aethis() as client:
    schema = client.get_schema("aethis/uk-fsm/child-eligibility")
    for f in schema.fields:
        print(f.field_id, f.field_type, f.description)

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

Ask your coding agent (Claude Code, Cursor, Windsurf, …) in natural language:

“Use Aethis to fetch the field schema for aethis/uk-fsm/child-eligibility.”

Your agent invokes the aethis_schema tool for you:

aethis_schema({ ruleset_id: "aethis/uk-fsm/child-eligibility" })

The response (same shape across all four interfaces):

{
  "ruleset_id": "aethis/uk-fsm/child-eligibility",
  "slug": "aethis/uk-fsm/child-eligibility",
  "name": "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).",
      "weight": 1,
      "enum_values": null,
      "notes": [
        {
          "note_text": "WHY: Free school meals eligibility is tied to compulsory-school-age status, which is determined by the child's age at the start of the academic year.",
          "source": "DfE Free School Meals: guidance for local authorities",
          "metadata": { "type": "why", "section": "child_eligibility" }
        },
        {
          "note_text": "LEGAL BACKGROUND:\n\nCompulsory school age runs from 1 September following the child's 5th birthday to the last Friday of June in the academic year of their 16th birthday. Age is taken as at 1 September of the relevant academic year, not the application date.",
          "source": "Education Act 1996, s.8",
          "metadata": { "type": "legal_background", "section": "child_eligibility" }
        }
      ]
    },
    {
      "field_id": "child.school_type",
      "field_type": "enum",
      "description": "Type of school the child attends.",
      "weight": 2,
      "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. notes — each field can carry a list of structured FieldNoteOut entries. By convention each note has metadata.type ∈ {"why", "legal_background"} and a source citation. Conversational agents (e.g. an information-gathering paralegal bot) typically surface the WHY:-prefixed note verbatim when a user replies “why?” to a question, and draw on the LEGAL BACKGROUND:-prefixed note for follow-up questions about evidence and edge cases. Older bundles may return "notes": [] — your code should treat the array as optional. weight — higher = less preferred to ask. The decision engine uses this for optimal-path computation when there are multiple ways to satisfy a ruleset (e.g. ask the cheap nationality question before the expensive English-test one).

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

CLI
Python SDK
curl
MCP

aethis decide \
  -b aethis/uk-fsm/child-eligibility \
  -i '{"child.age": 10, "child.school_type": "state_funded"}' \
  --explain

from aethis_sdk import Aethis

with Aethis() as client:
    response = client.decide(
        ruleset_id="aethis/uk-fsm/child-eligibility",
        field_values={
            "child.age": 10,
            "child.school_type": "state_funded",
        },
        include_trace=True,
    )
    print(response.decision)

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"
    },
    "include_trace": true
  }'

Ask your coding agent in natural language:

“Use Aethis to check whether a 10-year-old at a state-funded school qualifies for free school meals under aethis/uk-fsm/child-eligibility. Include the trace.”

Your agent invokes the aethis_decide tool for you:

aethis_decide({
  ruleset_id: "aethis/uk-fsm/child-eligibility",
  field_values: { "child.age": 10, "child.school_type": "state_funded" },
  include_trace: true
})

All four return the same decision envelope:

{
  "decision": "eligible",
  "fields_provided": 2,
  "fields_evaluated": 2,
  "ruleset_id": "uk-fsm-child-eligibility:20260528-244428c1",
  "slug": "aethis/uk-fsm/child-eligibility",
  "ruleset_version": "v3",
  "content_digest": "sha256:EXAMPLE_DIGEST_0000000000000000000000000000000000000000000000",
  "engine_version": "aethis-core@0.48.0",
  "decision_id": "dec_...",
  "inputs_hash": "sha256:...",
  "decision_time": "2026-07-26T01:26:33Z",
  "field_errors": null
}

Illustrative values — content_digest is a placeholder and the published ruleset_id / ruleset_version depend on what is live when you call. Field names and meanings are exact.ruleset_version is never "unknown" for a published leaf ruleset, and replay pins to content_digest, which changes on every republish. Both are served by api.aethis.ai today.

Three possible outcomes:

eligible — all criteria satisfied
not_eligible — one or more criteria failed
undetermined — engine couldn’t decide (missing field, discretionary clause, a blocking input error, or a case outside the compiled rules)

Check field_errors first. If it is non-null, an input could not be applied — an unknown field name or a value that failed its type — and the decision is forced to undetermined regardless of everything else in the envelope. A positive verdict never appears beside a blocking error, so treat a non-null field_errors as “fix the input and call again”, not as a partial answer. When you get undetermined with field_errors: null, inspect missing_fields. Add the missing values and call again. include_trace 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”:

CLI
Python SDK
curl
MCP

aethis decide \
  -b aethis/uk-fsm/child-eligibility \
  -i '{"child.age": 16, "child.school_type": "state_funded"}' \
  --explain

The CLI’s --explain flag calls /decide with trace, then /explain-failure when the outcome is not_eligible, and renders both in one pass.

Requires aethis-sdk >= 0.6.0.

/explain-failure resolves a slug the same way /decide, /schema, and /explain do — pass either the slug or the concrete ruleset_id from the /decide envelope.

from aethis_sdk import Aethis

with Aethis() as client:
    response = client.decide(
        ruleset_id="aethis/uk-fsm/child-eligibility",
        field_values={"child.age": 16, "child.school_type": "state_funded"},
        include_trace=True,
    )
    if response.decision == "not_eligible":
        # Either the slug or the concrete ruleset_id from the envelope works.
        explanation = client.explain_failure(
            ruleset_id=response.ruleset_id,
            field_values={"child.age": 16, "child.school_type": "state_funded"},
            expected_outcome="eligible",
        )
        print(explanation)

Either the slug (URL-encoded, %2F for /) or the concrete ruleset_id from the /decide envelope resolves here.

curl -X POST https://api.aethis.ai/api/v1/public/rulesets/aethis%2Fuk-fsm%2Fchild-eligibility/explain-failure \
  -H "Content-Type: application/json" \
  -d '{
    "field_values": { "child.age": 16, "child.school_type": "state_funded" },
    "expected_outcome": "eligible"
  }'

Ask your coding agent in natural language:

“Use Aethis to explain why a 16-year-old at a state-funded school is not eligible under aethis/uk-fsm/child-eligibility.”

Your agent invokes the aethis_explain_failure tool for you (it accepts either the slug or the concrete ruleset_id — the server resolves the slug directly):

aethis_explain_failure({
  ruleset_id: "aethis/uk-fsm/child-eligibility",
  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.

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

Debug a failing decide — when things don’t go as expected
MCP tools reference — every tool + parameters
Decision envelope — replay and audit contract

Getting started (no key)

AI coding agents

Interfaces

Recipes

Authoring (invite-only)

Reference

Changelog

Evaluate a case

1. Discover the schema

2. Collect field values

3. Decide

4. (Optional) Explain the decision

Composing multiple sections (rulebook)

Next steps

​1. Discover the schema

​2. Collect field values

​3. Decide

​4. (Optional) Explain the decision

​Composing multiple sections (rulebook)

​Next steps

1. Discover the schema

2. Collect field values

3. Decide

4. (Optional) Explain the decision

Composing multiple sections (rulebook)

Next steps