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

# Etiquetas

> Consulta el catálogo de etiquetas del negocio para asignarlas o quitarlas por nombre.

<Info>
  **Endpoint** · `GET /tags`
</Info>

<Note>
  Endpoint de **solo consulta**: devuelve información y no modifica nada. No se manda dentro del array `actions` — se llama directo.
</Note>

Devuelve el catálogo de etiquetas del negocio, en orden alfabético y paginado
por cursor. Excluye las etiquetas borradas y las etiquetas de sistema que el
dashboard crea por defecto.

Sirve para saber el `name` exacto de una etiqueta antes de usarla: las acciones
`assign_label` y `remove_label` identifican cada etiqueta por nombre, así que
conviene leer el catálogo primero en vez de adivinar el texto.

**Parámetros**

* `slug` — slug del negocio, en el path. Case-insensitive, debe coincidir con el negocio del token (**obligatorio**).
* `search` — substring del nombre, case-insensitive. Opcional, de 1 a 100 caracteres. El asterisco `*` funciona como comodín y coincide con cualquier secuencia de caracteres: `fact*mx` encuentra tanto `Facturas MX` como `Facturación MX`. Los caracteres `%` y `_` se buscan literalmente.
* `cursor` — cursor opaco devuelto por la página anterior en `next_cursor`. Opcional; omitirlo pide la primera página. No reutilizar cursores entre endpoints distintos: aunque el formato sea idéntico, cada endpoint lo interpreta sobre su propio conjunto de datos.
* `limit` — etiquetas por página. Opcional, entero de 1 a 500, por defecto 100.

Ningún parámetro de query es obligatorio: `GET /tags` sin query params devuelve
la primera página completa.

### Respuesta

```json theme={null}
{
  "items": [
    { "name": "Facturación MX", "color": "#FFB300" },
    { "name": "Prioritario", "color": "#22C55E" },
    { "name": "VIP", "color": "#2563EB" }
  ],
  "next_cursor": "eyJuYW1lIjoiVklQIn0",
  "has_more": true
}
```

* `items` — arreglo de etiquetas, cada una con `name` y `color`.
* `next_cursor` — cursor de la página siguiente, para pasarlo como `?cursor=`. Es `null` cuando `has_more` es `false`.
* `has_more` — indica si hay más resultados después de esta página. Repetir la llamada con el `next_cursor` hasta que sea `false`.

### Ejemplo

Una lectura simple, sin cuerpo: pide el catálogo y no cambia nada en el negocio.

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/tags" \
  -H "Authorization: Bearer sk_1to1_tu_api_key"
```

Buscando por comodín y pidiendo una página más chica:

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/tags?search=fact*mx&limit=20" \
  -H "Authorization: Bearer sk_1to1_tu_api_key"
```

El `name` que devuelve esta consulta es el que después se manda en la acción.

### Errores

| Código                    | Status | Cuándo                                                                           |
| ------------------------- | ------ | -------------------------------------------------------------------------------- |
| `INVALID_REQUEST`         | 400    | Algún query param no cumple el formato (`limit` fuera de rango, `search` vacío). |
| `INVALID_CURSOR`          | 400    | El `cursor` está corrupto o no corresponde a este endpoint.                      |
| `INVALID_API_TOKEN`       | 401    | Token ausente, mal formado o no válido.                                          |
| `TOKEN_BUSINESS_MISMATCH` | 403    | El slug del path no coincide con el negocio del token.                           |
| `RATE_LIMIT_EXCEEDED`     | 429    | Se excedió el límite de peticiones — ver [Límites de uso](/es/rate-limits).      |

El catálogo completo está en [Errores](/es/errors).

Con el nombre en la mano, la acción que lo consume es
[Asignar etiqueta](/es/action-groups/assign-label) o
[Quitar etiqueta](/es/action-groups/remove-label).