> ## 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.

# API Reference

> REST API for evaluating eligibility and authoring rule rulesets.

## Base URL

```
https://api.aethis.ai/api/v1/public/
```

## Authentication

```http theme={null}
x-api-key: ak_live_...
```

**Evaluation and read endpoints** on published public rulesets require **no
authentication**: `POST /decide`, `GET /rulesets`, and
`GET /rulesets/{id}/schema` · `/explain` · `/graph`, plus
`POST /rulesets/{id}/explain-failure`.

**Authoring endpoints** (`/projects/`, `/generate-and-test`, `/publish`,
`/guidance`) require an `x-api-key` header and are **invite-only private
beta**. Call them from your server — never expose an API key to client-side
code.

<Warning>
  **Browser access is scoped per route and method, not granted to "decision
  endpoints" as a class.** Only the enumerated evaluate/read surface answers a
  cross-origin request from an arbitrary origin, without credentials; every
  other route — authoring included — is restricted to first-party origins. See
  the [full route matrix](/interfaces/rest-api#browser-and-mobile-access-cors)
  before calling this API from client-side code.
</Warning>

[Request an API key →](https://aethis.ai/developer-access) · [What each tier includes](/reference/capabilities)

***

## Endpoint groups

<CardGroup cols={2}>
  <Card title="Decision" icon="check-circle">
    Evaluate eligibility against a published ruleset. No auth required. Under 1ms in the engine.

    * `POST /decide`
    * `GET /rulesets/{id}/schema`
    * `GET /rulesets/{id}/explain`
  </Card>

  <Card title="Projects (invite-only)" icon="code">
    Author rules from source text using a test-driven workflow. Requires an API key from the invite-only [authoring beta](https://aethis.ai/developer-access).

    * `POST /projects/`
    * `POST /projects/{id}/generate-and-test`
    * `POST /projects/{id}/publish`
    * `POST /projects/{id}/guidance`
  </Card>

  <Card title="Rulesets" icon="box">
    Inspect, list, and manage published rule rulesets.

    * `GET /rulesets/`
    * `GET /rulesets/{id}/schema`
    * `GET /rulesets/{id}/explain`
    * `PATCH /rulesets/{id}/visibility`
    * `POST /rulesets/{id}/archive`
  </Card>

  <Card title="Rulebooks" icon="sitemap">
    Compose multiple section rulesets into a single rulebook with outcome logic.

    * `POST /rulebooks/`
    * `GET /rulebooks/{id}`
    * `GET /rulebooks/{id}/schema`
    * `POST /rulebooks/{id}/activate`
    * `POST /rulebooks/{id}/archive`
  </Card>
</CardGroup>

***

## Quick example

```bash theme={null}
# Evaluate eligibility — no API key
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
  }'
```

```json theme={null}
{
  "decision": "eligible",
  "fields_provided": 2,
  "fields_evaluated": 2,
  "trace": {
    "age_check": "PASS — age 10 is within 4–15 (Regulation 3)",
    "school_type_check": "PASS — school_type is state_funded (Section 512ZA)"
  }
}
```

***

## Response codes

| Code | Meaning |
| - | - |
| `200` | OK |
| `201` | Created (project or ruleset) |
| `202` | Accepted — generation queued, poll `/status` |
| `404` | Ruleset or project not found |
| `422` | Validation error — wrong field type, missing required field, invalid ruleset ID |
| `429` | Rate limit exceeded |

**422 format:**

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

**429 with rate limit headers:**

```http theme={null}
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
  }
}
```

Requests are metered per [operation class](/interfaces/rest-api#rate-limits) over a rolling 24-hour window. Every metered response carries `X-RateLimit-*` headers, and `GET /usage` returns budget and usage across all classes without consuming quota.

***

For higher-level interfaces — CLI, MCP server, Python SDK — see [Which interface?](/interfaces/which-to-use).

Select an endpoint from the sidebar to view its full parameter schema and example responses.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.