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

> Salvar, listar e inspecionar rulesets.

O catálogo guarda rulesets para que você possa referenciá-los por
`name@version` no `/v1/evaluate` em vez de enviar o body inline a
cada chamada.

## Endpoints

| Método | Path                            | Propósito                       |
| ------ | ------------------------------- | ------------------------------- |
| POST   | `/v1/rulesets`                  | Cria um novo `(name, version)`. |
| GET    | `/v1/rulesets`                  | Lista rulesets (paginado).      |
| GET    | `/v1/rulesets/{name}`           | Pega a versão mais recente.     |
| GET    | `/v1/rulesets/{name}/{version}` | Pega uma versão específica.     |

## Criar

```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. Pares `(name, version)` são imutáveis — re-`POST`ar o mesmo
par retorna `409 RULESET_ALREADY_EXISTS`.

### Response

```json theme={null}
{
  "data": {
    "ruleset": "br-rural-credit",
    "version": 1,
    "body": { },
    "body_hash": "8a3c...",
    "created_at": "2026-05-05T12:00:00Z",
    "created_by": "org_01HX...",
    "display_name": null,
    "description": null,
    "tags": [],
    "resolved_colors": {
      "ruleset": "#3b82f6",
      "checks": { "no_indigenous_overlap": "#dc2626" },
      "outcomes": {
        "compliant": "#16a34a",
        "warning": "#f59e0b",
        "non_compliant": "#dc2626",
        "degraded": "#6b7280"
      }
    }
  }
}
```

## Listar

```bash theme={null}
GET /v1/rulesets?page=1&page_size=25
GET /v1/rulesets?tag=preset
GET /v1/rulesets?tag=preset&tag=brazil
```

| Query param | Notas                                                                                   |
| ----------- | --------------------------------------------------------------------------------------- |
| `page`      | 1-indexado. Padrão `1`.                                                                 |
| `page_size` | Itens por página. Padrão `25`, máximo `200`.                                            |
| `tag`       | Repita para exigir múltiplas tags (AND). Use `tag=preset` para listar presets oficiais. |

Retorna uma listagem de metadados paginada:

```json theme={null}
{
  "data": {
    "items": [
      {
        "ruleset": "br-rural-credit",
        "version": 1,
        "body_hash": "8a3c...",
        "created_at": "2026-05-05T12:00:00Z",
        "created_by": "org_01HX...",
        "display_name": null,
        "description": null,
        "tags": [],
        "color": "#3b82f6"
      }
    ],
    "pagination": { "page": 1, "page_size": 25, "total_count": 42, "total_pages": 2 }
  }
}
```

## Pegar

```bash theme={null}
GET /v1/rulesets/br-rural-credit          # versão mais recente
GET /v1/rulesets/br-rural-credit/1        # versão fixada
```

Ambos retornam o mesmo shape da resposta de `POST` acima.