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

# Catálogo de rulesets

> Salve seu ruleset uma vez, referencie por name@version.

Você pode passar um ruleset **inline** a cada chamada de
`/v1/evaluate`, ou salvá-lo uma vez no catálogo e referenciar por
`name@version`.

## Quando usar o catálogo

* **Compartilhado entre aplicações** — mesmo ruleset chamado por
  múltiplos serviços ou ambientes.
* **Auditável** — versões salvas são imutáveis, então um verdict
  guardado pode sempre ser reproduzido a partir de
  `(name, version)` mais o input.
* **Requests mais limpas** — seu cliente envia um id curto em vez do
  documento inteiro.

## Criar um 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` é um inteiro. Omita-o para a API atribuir o próximo número
livre.

Versões são imutáveis: re-`POST`ar o mesmo `(name, version)` com
body diferente retorna `409 RULESET_ALREADY_EXISTS`. Suba a versão
para publicar mudanças.

## Referenciar em uma chamada de evaluate

```json theme={null}
{
  "input": { "geometry": { "type": "Polygon", "coordinates": [] } },
  "ruleset_id": "br-rural-credit@1"
}
```

`name@version` resolve para uma versão fixada. `name` sozinho
resolve para a versão mais recente.

## Listar e inspecionar

```bash theme={null}
GET /v1/rulesets                       # lista paginada
GET /v1/rulesets/{name}                # versão mais recente
GET /v1/rulesets/{name}/{version}      # versão específica
```

O GET de um único registro retorna o body canônico e uma paleta de
cores para uso na UI.

## Convenção de versionamento

Versões são inteiros — incremente a cada mudança. Recomendamos:

* Trate o catálogo como append-only.
* Nunca reaproveite um par `(name, version)`.
* Adicione `description` em cada versão para registrar a intenção
  da política.