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

> Guarda tu ruleset una vez, referencia por name@version.

Puedes pasar un ruleset **inline** en cada llamada a `/v1/evaluate`,
o guardarlo una vez en el catálogo y referenciarlo por
`name@version`.

## Cuándo usar el catálogo

* **Compartido entre aplicaciones** — el mismo ruleset llamado por
  múltiples servicios o entornos.
* **Auditable** — las versiones guardadas son inmutables, así que
  un verdict guardado siempre puede reproducirse a partir de
  `(name, version)` más el input.
* **Requests más limpias** — tu cliente envía un id corto en vez del
  documento completo.

## Crear un 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` es un entero. Omítelo para que la API asigne el siguiente
número libre.

Las versiones son inmutables: re-`POST`ear el mismo
`(name, version)` con un body distinto devuelve
`409 RULESET_ALREADY_EXISTS`. Sube la versión para publicar
cambios.

## Referenciar en una llamada de evaluate

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

`name@version` resuelve a una versión fijada. `name` solo resuelve
a la versión más reciente.

## Listar e inspeccionar

```bash theme={null}
GET /v1/rulesets                       # listado paginado
GET /v1/rulesets/{name}                # versión más reciente
GET /v1/rulesets/{name}/{version}      # versión específica
```

El GET de un único registro devuelve el body canónico y una paleta
de colores para uso en UI.

## Convención de versionamiento

Las versiones son enteros — incrementa en cada cambio.
Recomendamos:

* Trata el catálogo como append-only.
* Nunca reutilices un par `(name, version)`.
* Agrega `description` en cada versión para registrar la intención
  de la política.