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

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-POSTing the same (name, version) with a different body returns 409 RULESET_ALREADY_EXISTS. Bump the version to publish changes.

Reference in an evaluate call

{
  "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

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.