> ## 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 organización para reglas y chequeos: valores principales, claves de búsqueda, ciclo de vida REST y UUID de lista en condiciones.

## Resumen

Las **data lists** (incluidas las listas **`custom`**) guardan valores que tu organización usa en **reglas** (`in_custom_list`, `not_in_custom_list`, `contains_any_from_custom_list`, etc.). La API pública está en:

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

Requiere **API key Bearer** (igual que [Autenticación](/es/api-reference/authentication)). Los datos quedan acotados a la **organización** de la clave.

## Conceptos

* **`name` y `description` (metadata de la lista)**: texto para **tu equipo**. Se usan en el **dashboard de gu1** (selector de listas, tablas, cabeceras de detalle) y en vistas de auditoría o administración para reconocer listas sin depender solo del UUID. **No** intervienen en el motor de reglas ni en los endpoints de `check`; la lógica sigue usando el **id de lista** y los **`primaryValue` / `searchKeys`** de cada ítem.
* **`primaryValue`**: valor principal del ítem.
* **`searchKeys`**: strings adicionales para búsqueda; si no se envían, el backend suele usar `[primaryValue]`.
* **`itemData` / `metadata`**: JSON opcional con columnas extra o contexto.
* **UUID en reglas**: en operadores de lista custom, el `value` de la condición es el **id** (UUID) de la lista.

Ver [Condiciones de reglas](/es/api-reference/rules/conditions).

## Flujo típico

1. **Crear** lista: `POST /data-lists` (`type: "custom"` u otro tipo soportado).
2. **Ítems**: `POST /data-lists/{listId}/items` o `POST /data-lists/{listId}/items/bulk`.
3. **Consultar pertenencia**: `POST /data-lists/{type}/check` o `POST /data-lists/bulk-check`.
4. **Listar ítems**: `GET /data-lists/{listId}/items` (query `search`), o **buscar por valor** con `POST /data-lists/{listId}/items/find` (coincidencia exacta o contiene sobre **primary + search\_keys** de esa lista).
5. **Mantener**: `PATCH /data-lists/{id}`, `PATCH /data-lists/{id}/status`, `DELETE /data-lists/{id}`, y por ítem `PATCH` / `DELETE` en `/data-lists/{id}/items/{itemId}`.

## Listas globales vs tenant

Tu tenant puede ver **listas globales**. Solo **administradores de sistema** mutan listas globales o sus ítems; las claves normales gestionan listas **de la organización**.

Las listas **solo marketplace** no se exponen por estos endpoints (`403` con código de error).

## Referencia API

Usá el apartado **Listas personalizadas → Referencia API** en el menú lateral.