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

# Listas personalizadas (data lists)

> Listas por organização para regras e checagens: valores primários, chaves de busca, ciclo de vida REST e UUID da lista em condições.

## Visão geral

As **data lists** (incluindo tipo **`custom`**) armazenam valores usados nas **regras** (`in_custom_list`, `not_in_custom_list`, `contains_any_from_custom_list`, etc.). A API pública fica em:

```
https://api.gu1.ai/data-lists
```

Todas as chamadas exigem **API key Bearer** (veja [Autenticação](/pt/api-reference/authentication)). Os dados são isolados na **organização** da chave.

## Conceitos

* **`name` e `description` (metadados da lista)**: texto para **sua equipe**. Aparecem no **dashboard do gu1** (catálogo de listas, seletores, cabeçalhos de detalhe) e em auditoria/admin para reconhecer listas sem depender só do UUID. **Não** entram no motor de regras nem nos `check`; a lógica usa o **id da lista** e os **`primaryValue` / `searchKeys`** de cada item.
* **`primaryValue`**: valor principal do item.
* **`searchKeys`**: strings extras para busca; se omitidas, a API costuma usar `[primaryValue]`.
* **`itemData` / `metadata`**: JSON opcional.
* **UUID nas regras**: nos operadores de lista custom, o `value` da condição é o **id** (UUID) da lista.

Veja [Condições de regras](/pt/api-reference/rules/conditions).

## Fluxo típico

1. **Criar** lista: `POST /data-lists` (`type: "custom"` ou outro tipo).
2. **Itens**: `POST /data-lists/{listId}/items` ou `POST /data-lists/{listId}/items/bulk`.
3. **Checar valor**: `POST /data-lists/{type}/check` ou `POST /data-lists/bulk-check`.
4. **Listar itens**: `GET /data-lists/{listId}/items` (`search`), ou **buscar por valor** com `POST /data-lists/{listId}/items/find` (exato ou contém em **primary + search\_keys** dessa lista).
5. **Manutenção**: `PATCH /data-lists/{id}`, `PATCH /data-lists/{id}/status`, `DELETE /data-lists/{id}`, e por item `PATCH` / `DELETE` em `/data-lists/{id}/items/{itemId}`.

## Listas globais

Listas **globais** só podem ser alteradas por **administradores do sistema**. Listas exclusivas de **marketplace** retornam `403` nesta API.

## Referência API

Use **Listas de dados → Referência API** na barra lateral.