> ## Documentation Index
> Fetch the complete documentation index at: https://docs-attestly.code4source.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruleset catalog

> Save your ruleset once, reference it by name@version.

You can pass a ruleset **inline** on every `/v1/evaluate` call, or
save it once to the catalog and reference it by `name@version`.

## When to use the catalog

* **Shared across applications** — same ruleset called from multiple
  services or environments.
* **Auditable** — saved versions are immutable, so a stored verdict
  can always be reproduced from `(name, version)` plus the input.
* **Cleaner requests** — your client sends a short id instead of the
  full document.

## Create a ruleset

```bash theme={null}
curl -X POST https://api-attestly.code4source.com/v1/rulesets \
  -H "Authorization: Bearer atk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "br-rural-credit",
    "version": 1,
    "sets":   { ... },
    "checks": [ ... ]
  }'
```

`version` is an integer. Omit it to let the API assign the next free
version.

Versions are immutable: re-`POST`ing the same `(name, version)` with
a different body returns `409 RULESET_ALREADY_EXISTS`. Bump the
version to publish changes.

## Reference in an evaluate call

```json theme={null}
{
  "input": { "geometry": { ... } },
  "ruleset_id": "br-rural-credit@1"
}
```

`name@version` resolves to a pinned version. `name` alone resolves to
the latest version.

## List and inspect

```bash theme={null}
GET /v1/rulesets                       # paginated list
GET /v1/rulesets/{name}                # latest version
GET /v1/rulesets/{name}/{version}      # specific version
```

The single-record GET returns the canonical body plus a color palette
for UI rendering.

## Versioning convention

Versions are integers — bump them on every change. We recommend:

* Treat the catalog as append-only.
* Never repurpose a `(name, version)` pair.
* Add `description` to each version to capture the policy intent.