REST API

Use the REST API when you’re building your own backend, dashboard, or custom workflow — a lending application that calls /decide on every form submission, a compliance portal that displays current rule explanations, or a custom authoring pipeline. Base URL: https://api.aethis.ai/api/v1/public/ Evaluation and read endpoints on public rulesets accept anonymous requests — no key.
Authoring endpoints require an x-api-key header, are invite-only, and must be called from your server. Only an enumerated set of routes is reachable from a browser on an arbitrary origin — see Browser and mobile access before you call this API from client-side code.

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.

Examples below marked (illustrative) use placeholder digests and identifiers; the field names and shapes are exact.

Authentication

x-api-key: ak_live_...

Get an API key: sign up Omitting the header on decision endpoints works fine. Including it on decision endpoints is also fine — it’s ignored.

Scopes

API keys carry a set of scopes. Each authoring endpoint requires a specific scope; a key without that scope receives 403 Forbidden. For the CLI-side view — what aethis login mints, how to check with aethis whoami, and how to mint a rulebook-capable key — see Authentication & API keys.

Scope	Grants
`decide`	`POST /decide` on private rulesets
`rulesets:read`	`GET /rulesets`, `GET /rulesets/{id}/schema`
`rulesets:explain`	`GET /rulesets/{id}/explain`, `POST /rulesets/{id}/explain-failure`
`rulesets:source`	`GET /rulesets/{id}/source` (DSL export)
`rulesets:write`	`PATCH /rulesets/{id}/visibility`, `POST /rulesets/{id}/archive`
`projects:read`	`GET /projects`, `/status`, `/guidance` list/export, and `GET /projects/{id}/sources/{source_id}/raw` — the authenticated download of a retained source artefact (Provenance)
`projects:write`	All project authoring: sources, tests, guidance, field/section discovery, generate, publish
`rulebooks:read`	`GET /rulebooks` (your tenant’s listing), `/schema`, `/explain`, `/graph`
`rulebooks:write`	Rulebook CRUD, `/activate`, `/archive`, `PATCH /rulebooks/{id}/visibility`

Decision endpoints (/decide, /schema, /explain on public rulesets) require no scope and accept anonymous requests. GET /rulebooks/ also accepts anonymous requests: without a key it returns the cross-tenant public catalogue (rulebooks with visibility=public and status=active); with a key it returns your tenant’s rulebooks as before.

Rulebook lookups and decisions require an API key. Anonymous /decide resolves a ruleset_id or ruleset slug against public rulesets only. The separate rulebook_id field (for composed multi-section rulebooks like aethis/uk-fsm) is always scope-gated — anonymous callers get a 401. Anonymous access to rulebooks is limited to the GET /rulebooks/ catalogue listing; to evaluate one, hit each section by slug instead, or pass an x-api-key header with a key that has the decide scope. See Nomenclature for the full distinction.

Browser and mobile access (CORS)

Cross-origin access is scoped per route and method, not granted to “decision endpoints” as a class. Two regimes: Open surface — any origin, no credentials. Exactly these (method, path) pairs answer a cross-origin request from any website:

Method	Path
`POST`	`/api/v1/public/decide`
`GET`	`/api/v1/public/rulesets`
`GET`	`/api/v1/public/rulesets/{ruleset_id}/schema`
`GET`	`/api/v1/public/rulesets/{ruleset_id}/explain`
`GET`	`/api/v1/public/rulesets/{ruleset_id}/graph`
`POST`	`/api/v1/public/rulesets/{ruleset_id}/explain-failure`
`GET`	`/health`

On this surface the engine allows GET, POST and OPTIONS, accepts the Content-Type and X-API-Key request headers, and never returns Access-Control-Allow-Credentials — cookies and other ambient credentials are not carried, by design. Restricted surface — everything else. Every other route, including all authoring and project routes, grants CORS only to first-party Aethis origins. A browser request from your own origin to an authoring route receives no CORS grant and the browser blocks it. Preflights are classified by the method the browser asks for, so an OPTIONS preflight for a non-open method on an open path is handled by the restricted policy.

Two consequences worth designing around.

GET /rulebooks/ accepts anonymous requests server-side, but it is not on the open browser surface — call it from your backend.
Never ship an authoring key to a browser. Even setting CORS aside, an x-api-key in client-side code is a published credential.

Client-side use is intended for the evaluation surface: decide against a public ruleset, read its schema, explain it, graph it. Anything that writes belongs on your server.

Rate limits

Every authenticated request is metered against one of six operation classes. A class is both the rate-limit bucket and the usage metric, so what you’re throttled on is exactly what you can measure:

Class	Covers
`decide`	Decision evaluations (`POST /decide`)
`generate`	Rule generation (`/generate`, `/generate-and-test`) — the scarce, model-backed operation
`author`	Authoring writes: sources, fields, tests, guidance, publish, review
`read`	All `GET`s, including status polling
`keys`	API-key management
`admin`	Administrative operations

Limits apply per rolling 24-hour window (hourly buckets that slide continuously, not a calendar-day reset). Budgets are generous everywhere except generate, which carries the only meaningful ceiling — so ordinary authoring and decisions no longer compete with generation for a shared quota:

Tier	`decide`	`generate`	`author`	`read`	`keys`
Anonymous (no key)	500 per IP	—	—	500 per IP	—
`free`	500	200	20,000	100,000	50
`starter`	10,000	1,000	20,000	100,000	100
`pro`	100,000	5,000	50,000	200,000	500

generate limits currently run in report-only mode: an over-limit request is recorded but not rejected while the ceilings are tuned against real usage. Every other class is enforced. Tier is set at key creation — contact eng@aethis.ai to upgrade.

Forward-visibility headers

Every metered response carries your current budget, so a 429 is never the first signal:

X-RateLimit-Class: decide
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 498
X-RateLimit-Reset: 1753120800

X-RateLimit-Class — the operation class this request was metered against.
X-RateLimit-Limit — the limit for that class on your tier.
X-RateLimit-Remaining — requests left in the current rolling window.
X-RateLimit-Reset — epoch seconds of the next hourly boundary, when the oldest counted hour ages out and budget is freed.

Check your usage

GET /usage returns your budget and usage across every operation class. It is scoped to the calling key and is never metered — poll it as often as you like without consuming quota:

curl https://api.aethis.ai/api/v1/public/usage \
  -H "x-api-key: ak_live_..."

{
  "tier": "free",
  "classes": [
    { "class": "decide", "limit": 500, "used": 12, "remaining": 488, "reset": 1753120800 },
    { "class": "generate", "limit": 200, "used": 3, "remaining": 197, "reset": 1753120800 }
  ],
  "rolling": {
    "last_7_days": { "decide": 84, "generate": 21 },
    "last_30_days": { "decide": 310, "generate": 96 }
  }
}

classes[] gives each class’s rolling-24h budget and usage; rolling adds 7-day and 30-day per-class totals. See the API reference for the full schema.

Anonymous budgets

Anonymous callers are metered separately, and on more than one axis. Plan for all four when you build on the open surface:

Budget	Limit	What trips it
Per client, `decide`	500 / rolling 24h	Decisions from one client identity
Per client, `read`	500 / rolling 24h	Anonymous `GET`s
Shared across all anonymous callers	25,000 / rolling 24h per class	Total anonymous load on the preview
Concurrent anonymous evaluations	8 in flight per process	Parallel bursts, answered with `429` and `reason_code: anonymous_concurrency_exceeded`

Expensive options are costed. A plain anonymous /decide charges one unit. Each of no_cache, include_trace, include_explanation and include_graph_overlay adds 5 further units, so a call with trace and explanation costs 11. Budget accordingly, or use a key. Client identity comes from the trusted proxy hop, not from a caller-supplied X-Forwarded-For. Rotating that header does not rotate your anonymous quota. Anonymous request bodies are capped at 2 MB on the evaluation routes and rejected with 413 before the body is parsed.

What an anonymous call stores. Anonymous preview decisions persist the input hash and aggregate metadata only — never your raw field_values and never a caller reference. inputs_hash is deliberately unsalted, so you can recompute it yourself from the same inputs and match a stored decision for replay.

Decision envelope

Every /decide response includes audit fields (decision_id, inputs_hash, engine_version) for reproducible replay without the server echoing your inputs. See Decision envelope → for the full contract.

Resolved identity

For a published leaf ruleset the response always resolves what you asked for into immutable identity, whether you passed a slug or an ID and whether the answer came from cache or cold:

Field	Meaning
`ruleset_id`	The immutable ruleset ID that was decided. Never the slug you sent.
`ruleset_version`	The published version label (`v3`). A mutable authoring label — it advances on every publish.
`content_digest`	`sha256:<hex>` over the published rule content. Immutable content identity. A republish always changes it.

Pin replay and audit to content_digest, not to the version label. A republish of byte-identical content can advance the label while reusing the existing content cut; only the digest identifies the rules that produced a given decision. ruleset_version: "unknown" is not a possible value for a published leaf ruleset. Composed rulebook (rulebook_id) responses still report "unknown" for the composition until resolved member identity lands.

Evaluate eligibility

No API key required.

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
  }'

Response (illustrative — digests and IDs are placeholders; field names and shapes are exact):

{
  "decision": "eligible",
  "ruleset_id": "uk-fsm-child-eligibility:20260528-244428c1",
  "slug": "aethis/uk-fsm/child-eligibility",
  "ruleset_version": "v3",
  "content_digest": "sha256:0f0e0d0c0b0a09080706050403020100f0e0d0c0b0a090807060504030201000",
  "engine_version": "aethis-core@0.48.0",
  "decision_id": "dec_GjBMU4o8sNvNRmaR",
  "inputs_hash": "sha256:75c958f1a3d72335ccf67c7d5e32f58b57966e0873786843c353b09f787c5ec2",
  "decision_time": "2026-07-26T01:26:33Z",
  "fields_provided": 2,
  "fields_evaluated": 2,
  "field_errors": null,
  "trace": {
    "status": "eligible",
    "group_statuses": {
      "age_check": "satisfied",
      "school_type_check": "satisfied"
    }
  }
}

Parameters:

ruleset_id — the published ruleset to evaluate against
field_values — map of field names to values (types must match the ruleset schema)
include_trace (optional) — when true, returns a trace object showing how each criterion was evaluated and the source clause it references
include_explanation (optional) — when true, returns a structured explanation object: gate-level checklist (groups[].criteria[].status), the supporting facts that proved each satisfied criterion (supporting_facts), the satisfied requirement name (decision_path), and any provided fields the ruleset never references (unused_facts — useful for catching field-name typos). See Debug a /decide for the full payload shape.

Decisions:

eligible — all criteria satisfied
not_eligible — one or more criteria failed
undetermined — the engine could not reach a decision (missing field, discretionary clause, blocking input error, or a case outside the compiled rules)

Reading the response

Blocking errors versus advisory signals

field_errors is the only blocking channel in a /decide response. Every entry means an input you sent could not be applied to the ruleset: an unknown field key, a value that does not convert to the field’s type, or a conversion failure at evaluation time. A non-empty field_errors always forces decision: "undetermined". The engine never returns eligible or not_eligible next to a blocking input error, because that verdict would have been computed from a partial input set you did not knowingly send. Read field_errors before you treat any decision as terminal.

{
  "decision": "undetermined",
  "field_errors": {
    "child.aeg": "Unknown field for this ruleset",
    "child.school_type": "Expected one of state_funded, independent, home_educated"
  },
  "fields_provided": 2,
  "fields_evaluated": 0
}

Everything else is advisory and never gates the outcome:

missing_fields, next_question, optimal_path — progress guidance while the decision is undetermined;
explanation.unused_facts — answers you sent that no satisfied criterion referenced (usually a field-name typo);
a malformed caller_ref — dropped with a server-side warning, never a rejection.

Per-criterion status is not a second decision. When field_errors forces undetermined, explanation.groups[].status and graph_overlay.nodes[].overlay.status still report what the engine established for each criterion from the valid subset of your inputs — so a criterion can legitimately read "satisfied" in the same response.That is deliberate: those fields answer “what is true of this criterion?”, while decision answers “what may I act on?”. Never recompute an outcome by aggregating group or node statuses. decision is the only field to treat as the result, and you read field_errors first.

The response truth table

You sent	HTTP	`decision`	`field_errors`
All keys known, all values valid, outcome determinable	`200`	`eligible` / `not_eligible`	absent
All inputs valid, not yet enough to determine	`200`	`undetermined`	absent
At least one unknown field key	`200`	`undetermined` (forced)	present, blocking
Known key, value fails the field’s type	`200`	`undetermined` (forced)	present, blocking
Valid inputs plus at least one unknown or bad input	`200`	`undetermined` (forced)	present, blocking
A top-level body key the API does not define	`422`	—	—
A ruleset ID or slug that does not resolve	`404`	—	—
A stored record that fails validation on read	`422`	—	—
An unexpected server-side failure after the request was accepted	`500`	—	—

A 500 returns an opaque envelope: no partial decision, and none of your submitted values echoed back. Unknown top-level request keys are rejected, not ignored: the request body is strict, and an undefined key returns 422 with detail[].type == "extra_forbidden". If you have code that sends a field this API does not document, it has never been doing what you thought.

Trace, explanation, and source references

Three distinct things, often conflated. Ask for the one you need — on the anonymous surface each costs extra quota.

You want	Ask for	You get
How the engine got here	`include_trace: true`	`trace`: per-group status, the answers consumed, and the compiled conditions that failed. Machine-oriented and structural.
A gate-level checklist in English	`include_explanation: true`	`explanation`: `groups[].criteria[].status`, `supporting_facts`, the satisfied `decision_path`, and `unused_facts`.
The authority behind a criterion	`include_explanation: true`, or `GET /rulesets/{id}/explain`	`source_references[]` on each criterion — the verbatim quoted clause, its digest, its licence, and a link that lands on the text.

trace is not a citation. It shows the compiled logic that ran. The citation lives in source_references, which is validated at publish time rather than assembled at read time.

The `SourceReference` contract

GET /rulesets/{id}/explain and POST /decide with include_explanation: true return the identical SourceReference shape — on /explain it sits at criteria[].source_references[], on /decide at explanation.groups[].criteria[].source_references[].

{
  "schema_version": 1,
  "source_id": "SI2049-42#reg3",
  "title": "The Spacecraft Crew Certification Regulations 2049",
  "authority": "UK Space Regulator",
  "url": "https://www.example.com/spacecraft-regulations-2049/regulation/3",
  "locator": "Regulation 3(1)",
  "source_version": "2049-04-01",
  "source_date": "2049-04-01",
  "content_digest": "sha256:1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809",
  "licence": "OGL-UK-3.0",
  "verified_at": "2026-07-25T20:14:50Z",
  "quote": {
    "exact": "No person shall be certified as crew if that person is a Vogon.",
    "prefix": "Certification of crew",
    "suffix": "unless an exemption under regulation 9 applies"
  },
  "media_type": "html",
  "deep_link": "https://www.example.com/spacecraft-regulations-2049/regulation/3#:~:text=No%20person%20shall%20be%20certified"
}

What the contract guarantees, and what it does not:

quote.exact is verbatim, never a summary. Publish validation asserts the quote occurs in the fetched source after whitespace normalisation (HTML is tag-stripped, PDF is checked against extracted page text). No stemming, no case folding, no fuzzy matching.
References are resolved and verified at publish time, not at read time. An unresolvable, private, unlicensed or digest-mismatched reference fails the publish. You are reading a check that already passed, so /explain does not fetch anything while you wait.
content_digest fixes the bytes the quote was verified against, and verified_at says when. If the authority silently rewrites the page, your citation still names what was actually cited.
deep_link locates the quote in the source: a percent-encoded #:~:text= fragment for HTML and text, #page=N for PDF.
licence is mandatory. Reproducing text under no stated licence is not publishable.
schema_version grows additively. Pin schema_version >= 1 and treat new fields as optional.
Newly emitted v1 references carry an optional snapshot. It is the digest keying the engine-retained copy of the bytes it fetched (equal to content_digest), so the citation outlives the page it came from. Absent on references stored before snapshot-on-fetch.

Schema v2: artefact-backed references

A reference with "schema_version": 2 cites a file the author uploaded to their project rather than a public URL. It adds target_kind: "artefact", artefact_project_id and artefact_source_id, and its url is different in kind from a v1 url:

On a v2 reference, url is the relative path of an authenticated download route — /api/v1/public/projects/{project_id}/sources/{source_id}/raw, requiring a key with the projects:read scope. Resolve it against the engine base URL you are calling, and never render it as a public link. v1 url is an absolute, publicly fetchable HTTPS URL; the two are not interchangeable.

Artefact references are private-only. Any operation that would make an artefact-backed ruleset publicly resolvable — publishing it public, flipping ruleset or rulebook visibility, attaching or promoting it into a public rulebook — is rejected with artefact_reference_public_visibility_forbidden. So a publicly readable ruleset’s references are always v1 URL citations, and no anonymous response ever exposes a private project or source identifier. Full authoring semantics, including the failure reason codes, are on Provenance and citations.

source_references is present only on rulesets published under this contract. Older published rulesets may carry the legacy source_refs array of opaque authoring keys instead. Read source_references when it is present and fall back rather than assuming either.

Inspect a ruleset

# Get the field schema — what fields does this ruleset expect?
curl https://api.aethis.ai/api/v1/public/rulesets/aethis/uk-fsm/child-eligibility/schema

{
  "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 start of academic year",
      "question": "How old will the child be on 1 September of the relevant academic year?",
      "weight": 1,
      "enum_values": null,
      "notes": [
        {
          "note_text": "WHY: Compulsory-school-age status — and therefore FSM eligibility — is determined by age on 1 September.",
          "source": "DfE Free School Meals: guidance for local authorities",
          "metadata": { "type": "why", "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"],
      "notes": []
    }
  ]
}

notes (each FieldNoteOut: { note_text, source, metadata }) is the structured guidance the ruleset author attached during /fields/discover. Conversational front-ends (e.g. a paralegal bot) typically render metadata.type='why' notes when the user asks “why are you asking this?” and draw on metadata.type='legal_background' notes for edge-case follow-ups. Older bundles return "notes": [] — treat the array as optional. weight is the question-ordering hint used by the constraint solver (higher = less preferred to ask). Used by /decide’s optimal_path to surface cheap questions before expensive ones when multiple ways to satisfy the ruleset exist.

# Get human-readable rule descriptions
curl https://api.aethis.ai/api/v1/public/rulesets/aethis/uk-fsm/child-eligibility/explain

Honest catalogue counts

GET /rulesets returns a bare JSON array. A stored record that fails validation on read is skipped rather than 500-ing the whole catalogue, which means a page can be shorter than the records the query matched. Every response carries a header saying how many were dropped:

X-Aethis-Records-Omitted: 0

Read it on every page. 0 is the normal case; a non-zero value tells you a short page is short because something was skipped, not because you reached the end of the catalogue. Never infer exhaustion from len(page) < limit. A direct read of a corrupt record is never silently skipped: it returns a structured 422 with reason_code: "ruleset_record_corrupt", so the failure is attributable to one record rather than surfacing as a page-wide 500. Same anonymous-public access applies to GET /rulesets/{id}/graph — the compiled ruleset as a node/edge graph plus a ready-to-render Mermaid string, for visualizing structure instead of reading a flat field list. See Ruleset & rulebook graphs.

Author rules

Authoring is invite-only private beta (request access). API key required; do all authoring server-side. Pass an X-Anthropic-Key header on generation requests — used for that request only, never stored.

Step 1 — Create a project

curl -X POST https://api.aethis.ai/api/v1/public/projects/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_live_..." \
  -d '{
    "name": "Income eligibility check",
    "section_id": "income_eligibility",
    "source_text": "Section 3: An applicant qualifies if annual net income is below £30,000...",
    "test_cases": [
      { "name": "Below threshold", "field_values": { "applicant.annual_income": 25000 }, "expected_outcome": "eligible" },
      { "name": "Above threshold", "field_values": { "applicant.annual_income": 35000 }, "expected_outcome": "not_eligible" }
    ]
  }'

{ "project_id": "proj_abc123" }

Step 2 — Generate and test

curl -X POST https://api.aethis.ai/api/v1/public/projects/proj_abc123/generate-and-test \
  -H "x-api-key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "anthropic_key": "sk-ant-..." }'

{
  "ruleset_id": "income_eligibility:20260416-a1b2c3d4",
  "tests_passing": 2,
  "tests_total": 2,
  "failures": []
}

If tests are failing:

{
  "ruleset_id": "income_eligibility:20260416-a1b2c3d4",
  "tests_passing": 1,
  "tests_total": 2,
  "failures": [
    {
      "name": "At exact threshold",
      "expected": "eligible",
      "got": "not_eligible",
      "hint": "The threshold condition may be using strict < rather than ≤"
    }
  ]
}

Add guidance and regenerate:

curl -X POST https://api.aethis.ai/api/v1/public/projects/proj_abc123/guidance \
  -H "x-api-key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "guidance_text": "The £30,000 threshold is inclusive — use ≤ not <.",
    "process_type": "rule_generation"
  }'

Then repeat generate-and-test.

Incremental refine (minimal edit)

Both generate and generate-and-test accept an optional mode body. mode: "refine" seeds generation from the section’s active ruleset and makes the minimal edit to fix failing tests, instead of re-authoring the section from scratch. Omitting the body (or mode: "fresh") is the default from-scratch behaviour.

curl -X POST https://api.aethis.ai/api/v1/public/projects/proj_abc123/generate-and-test \
  -H "x-api-key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "anthropic_key": "sk-ant-...", "mode": "refine" }'

seed_ruleset_id may be supplied to refine from a specific ruleset; when omitted, the section’s active ruleset is used.

Step 3 — Publish

curl -X POST https://api.aethis.ai/api/v1/public/projects/proj_abc123/publish \
  -H "x-api-key: ak_live_..."

{
  "ruleset_id": "income_eligibility:20260416-b2c3d4e5",
  "version": "v2",
  "tests_passing": 2,
  "tests_total": 2
}

Now evaluate with /decide using the returned ruleset_id.

Review a project (Authoring Coach)

Run the versioned authoring rubric over a project and get an objective quality report — a reproducible score, per-check evidence across grounding / process / lifecycle, strengths, and the single highest-leverage next improvement. Requires an API key with projects:read + rulesets:read. Advisory only — it never blocks generation, publishing, or a decision. The deterministic report needs no LLM key. Add coach: true (with your own X-Anthropic-Key) to get an LLM-synthesised coaching narrative on top; the deterministic layer ignores the key entirely.

curl -X POST https://api.aethis.ai/api/v1/public/projects/proj_abc123/review \
  -H "x-api-key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "coach": false }'

{
  "project_id": "proj_abc123",
  "rubric_version": "v1",
  "score": 56,
  "data_completeness": "ok",
  "checks": [
    {
      "id": "G1",
      "group": "grounding",
      "audience": "author",
      "actionable_via": "source docs + guidance",
      "status": "fail",
      "evidence": "0/2 fields carry a source-cited 'why' note (0%).",
      "weight": 20,
      "scored": true,
      "why": "Fields whose 'why' rationale cites a source stay auditable — the applicant-facing explanation traces back to your uploaded documents.",
      "docs_url": "https://docs.aethis.ai/authoring/review-checks#g1"
    }
  ],
  "strengths": [
    "Testing: golden test coverage meets the bar — 6 test case(s); threshold for this ruleset is 5."
  ],
  "next_skill": {
    "check_id": "G1",
    "message": "Add source-cited 'why' rationales — upload the governing document and re-generate so each field's rationale cites it.",
    "actionable_via": "source docs + guidance",
    "docs_url": "https://docs.aethis.ai/authoring/review-checks#g1"
  },
  "coaching": null
}

Response fields:

score (int | null) — the weighted rubric score (0–100). null on a project too thin to score.
data_completeness — "ok", or "thin" when the project is missing a ruleset, tests, or sources (the report degrades gracefully, never a 500).
checks[] — one entry per rubric check: status (pass / warn / fail / na / info), the evidence that produced it, its weight, whether it’s scored, the why it matters, the actionable_via lever that changes it, and a docs_url linking to Review checks.
strengths[] — what the project already does well.
next_skill (object | null) — the single highest-leverage, author-actionable improvement to make next.
coaching (string | null) — the LLM narrative, present only when coach: true.

The full rubric — every check, its weight, and its pass/warn/fail thresholds — is documented on the Review checks page.

Ambient review hints. The generate, generate-and-test, and publish responses now carry an optional review_hint — the top author-actionable warning from the same rubric, so you get a nudge in-flow without an explicit review call. It’s the same shape as next_skill (check_id, message, actionable_via, docs_url) and is null when nothing needs attention.

Error responses

Code	Meaning	What to do
`200`	OK. On `/decide`, still read `field_errors` before treating the decision as terminal.	—
`201`	Created (project or ruleset)	—
`202`	Accepted — generation queued, poll `/status`	—
`401`	No key, or a key the engine could not verify, on a route that requires one. Composed rulebook decisions are always in this class.	Evaluating a public ruleset? Use `ruleset_id` with a leaf slug — no key needed. Authoring is invite-only: request access. See Capabilities and access.
`403`	Valid key, missing scope.	Check `aethis whoami`, then Authentication.
`404`	Ruleset or project not found. Identical response for “does not exist” and “exists but is not visible to you”.	—
`413`	Request body over the cap (2 MB on the anonymous evaluation routes). Rejected before parsing.	Send fewer fields, or split the call.
`422`	Validation error — wrong field type, an undefined top-level request key, or a stored record that fails validation on read.	See the two shapes below.
`429`	Rate limit, anonymous budget, or the anonymous concurrency cap.	Read `reason_code` and `Retry-After`; poll `/usage`.
`500`	Unexpected server failure. Opaque envelope; never a partial decision and never your inputs echoed back.	Retry, then report it.

422 — a value that failed validation:

{
  "detail": [
    {
      "loc": ["body", "field_values", "child.age"],
      "msg": "Expected an integer, got str",
      "type": "type_error.integer"
    }
  ]
}

422 — a top-level request key the API does not define:

{
  "detail": [
    {
      "loc": ["body", "batch"],
      "msg": "Extra inputs are not permitted",
      "type": "extra_forbidden"
    }
  ]
}

The request body is strict. An undefined key is rejected rather than ignored, so a client sending an unimplemented field finds out immediately instead of believing a feature exists.

A bad field value does not produce a 422 on /decide — it comes back as a 200 with the offending key in field_errors and decision: "undetermined". 422 is reserved for a malformed request. See the truth table.

429 with rate limit headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
X-RateLimit-Class: generate
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1753120800

{
  "detail": {
    "error": "rate_limit_exceeded",
    "reason_code": "daily_quota_exceeded",
    "message": "Quota exceeded for 'generate' (limit: 200 per rolling 24h). Upgrade your tier or wait for the window to slide.",
    "category": "generate",
    "tier": "free",
    "limit": 200
  }
}

The forward-visibility headers ride ordinary metered responses too — check X-RateLimit-Remaining or poll /usage to stay ahead of a 429.

Date fields take an ISO "YYYY-MM-DD" string or an integer ordinal on ruleset evaluations (ISO accepted since engine 0.31.0). Rulebook evaluations (rulebook_id) still require ordinals. See Date field values.

Full endpoint reference

All endpoints with schemas, parameter details, and example responses: API Reference →

Help improve this pageIf something here is unclear or missing an example, use the feedback button at the bottom of the page.Found a bug? Open a GitHub issue. Evaluating Aethis for a regulated workflow? Contact us directly.

Getting started (no key)

AI coding agents

Interfaces

Recipes

Authoring (invite-only)

Reference

Changelog

Authentication

Scopes

Browser and mobile access (CORS)

Rate limits

Forward-visibility headers

Check your usage

Anonymous budgets

Decision envelope

Resolved identity

Evaluate eligibility

Reading the response

Blocking errors versus advisory signals

The response truth table

Trace, explanation, and source references

The `SourceReference` contract

Schema v2: artefact-backed references

Inspect a ruleset

Honest catalogue counts

Author rules

Step 1 — Create a project

Step 2 — Generate and test

Incremental refine (minimal edit)

Step 3 — Publish

Review a project (Authoring Coach)

Error responses

Full endpoint reference

​Authentication

​Scopes

​Browser and mobile access (CORS)

​Rate limits

​Forward-visibility headers

​Check your usage

​Anonymous budgets

​Decision envelope

​Resolved identity

​Evaluate eligibility

​Reading the response

​Blocking errors versus advisory signals

​The response truth table

​Trace, explanation, and source references

​The SourceReference contract

Schema v2: artefact-backed references

​Inspect a ruleset

​Honest catalogue counts

​Author rules

​Step 1 — Create a project

​Step 2 — Generate and test

​Incremental refine (minimal edit)

​Step 3 — Publish

​Review a project (Authoring Coach)

​Error responses

​Full endpoint reference

Authentication

Scopes

Browser and mobile access (CORS)

Rate limits

Forward-visibility headers

Check your usage

Anonymous budgets

Decision envelope

Resolved identity

Evaluate eligibility

Reading the response

Blocking errors versus advisory signals

The response truth table

Trace, explanation, and source references

The `SourceReference` contract

Inspect a ruleset

Honest catalogue counts

Author rules

Step 1 — Create a project

Step 2 — Generate and test

Incremental refine (minimal edit)

Step 3 — Publish

Review a project (Authoring Coach)

Error responses

Full endpoint reference