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.

Small page, high-value. If you’re writing a /decide call and unsure whether to pass ruleset_id or rulebook_id, you’re in the right place.

​
The objects

TermWhat it is
ProjectAn authoring workspace for one section of rules. You create it, upload sources, add guidance, add tests, then generate-and-publish rulesets from it.
RulesetA single immutable compiled rule artefact for one section. Identified internally by a versioned ruleset_id (<section>:YYYYMMDD-<hash>) — every regeneration produces a new one — and externally by a stable slug (e.g. aethis/uk-fsm/child-eligibility). Always reference a ruleset by slug; the dated id is for replay/audit only. Has a status (draft / active / deprecated / archived) and a visibility (public / private).
RulebookA composition of multiple rulesets (one per section) into a single eligibility determination. Identified by rulebook_id and optionally a slug. Has an outcome_logic expression like A AND (B OR C) that combines the section decisions.
SectionA logical slice of a rule domain (e.g. “child eligibility”, “household criteria”). Each section has its own project and its own stream of ruleset regenerations.
SlugStable human-readable alias, format <segment>[/<segment>...] (lowercase ASCII + hyphens). Applied to rulesets and rulebooks. Surviving the regeneration of the underlying artefact is the whole point.
A concrete example — UK Free School Meals: 
Project "UK FSM — Child Eligibility"
  └── Ruleset (slug: aethis/uk-fsm/child-eligibility)

Project "UK FSM — Household Qualifying Criteria"
  └── Ruleset (slug: aethis/uk-fsm/household-criteria)

Project "UK FSM — Universal Infant FSM"
  └── Ruleset (slug: aethis/uk-fsm/universal-infant)

Rulebook "UK Free School Meals Eligibility"            (slug: aethis/uk-fsm)
  ruleset_refs:
    - section_id: uk-fsm-child-eligibility    (pin_mode: latest_active)
    - section_id: uk-fsm-household-criteria   (pin_mode: latest_active)
    - section_id: uk-fsm-universal-infant     (pin_mode: latest_active)
  outcome_logic: A AND (B OR C)

​
ruleset_id vs rulebook_id on /decide

The public POST /decide endpoint has two separate fields on the request body, and they go through different resolution paths: 
{
  "ruleset_id": "aethis/uk-fsm/child-eligibility",   // single section, anon OK on public rulesets
  "field_values": { ... }
}

{
  "rulebook_id": "aethis/uk-fsm",                    // composed rulebook, x-api-key REQUIRED
  "field_values": { ... }
}
Sending ruleset_id: "aethis/uk-fsm" — a rulebook slug — returns Ruleset 'aethis/uk-fsm' not found. The resolver only looks in the ruleset collection for that field; it doesn’t fall through to rulebooks. If you want the composed decision, move the value into the rulebook_id field and add an x-api-key header.
See interfaces/rest-api.mdx for the full endpoint contract.

​
Visibility — public vs private

visibilityAnon /decide with ruleset_id works?Shown in GET /rulesets?
publicyesyes
privateno — needs an API key with decideno (unless same tenant)
Every new ruleset defaults to private. The exception: publishing with a slug under the reserved aethis/* namespace on an internal API key auto-flips visibility to public. For everything else, call PATCH /rulesets/<id>/visibility after publish.

​
The aethis/* namespace

Reserved. Only internal API keys (those with internal: true set on the key document) can publish slugs starting with aethis/. External tenants attempting the same get HTTP 403 with reason_code: "reserved_namespace". This is intentional: aethis/* is where the canonical public demo rulesets live (see /getting-started/try-it and /getting-started/examples). The namespace doubles as an allow-list for “safe to reference from docs without fear of the tenant renaming it”.

​
pin_mode on rulebook ruleset_refs

When a rulebook composes sections, each ruleset_ref picks which ruleset version to resolve to at decide time:
pin_modeBehaviour
latest_activeResolve to whatever ruleset currently has status="active" for that section_id
pinnedResolve to the specific ruleset_id stored on the ref, regardless of active state
latest_active is the normal choice — it lets section regenerations flow through the rulebook automatically. Use pinned when you need a frozen composition for audit or rollback.

​
See also

  • Decision envelope — what /decide returns and how to replay it
  • REST API — endpoint contracts + rate limits + auth
  • MCP tools — the agent-callable wrappers around these endpoints