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

**Decision endpoints** (`/decide`, `/rulesets/{id}/schema`, `/rulesets/{id}/explain`) require **no authentication**. Safe to call client-side from a browser or mobile app.

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

[Get an API key →](https://aethis.ai/developer-access)

***

## Endpoint groups

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

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

  <Card title="Projects" icon="code">
    Author rules from source text using a test-driven workflow. API key required.

    * `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
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714000000

{ "error": "rate_limit_exceeded", "retry_after": 1714000000 }
```

***

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.