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

> Consulte o catálogo de etiquetas do negócio para atribuir ou remover etiquetas por nome.

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

<Note>
  Endpoint **somente de consulta**: devolve informação e não modifica nada. Não é enviado dentro do array `actions` — é chamado diretamente.
</Note>

Devolve o catálogo de etiquetas do negócio, em ordem alfabética e paginado por
cursor. Exclui as etiquetas apagadas e as etiquetas de sistema que o dashboard
cria por padrão.

Serve para saber o `name` exato de uma etiqueta antes de usá-la: as ações
`assign_label` e `remove_label` identificam cada etiqueta pelo nome, então
convém ler o catálogo primeiro em vez de adivinhar o texto.

**Parâmetros**

* `slug` — slug do negócio, no path. Case-insensitive, deve coincidir com o negócio do token (**obrigatório**).
* `search` — substring do nome, case-insensitive. Opcional, de 1 a 100 caracteres. O asterisco `*` funciona como curinga e corresponde a qualquer sequência de caracteres: `fact*mx` encontra tanto `Facturas MX` quanto `Facturação MX`. Os caracteres `%` e `_` são buscados literalmente.
* `cursor` — cursor opaco devolvido pela página anterior em `next_cursor`. Opcional; omiti-lo pede a primeira página. Não reutilizar cursores entre endpoints diferentes: mesmo que o formato seja idêntico, cada endpoint o interpreta sobre o seu próprio conjunto de dados.
* `limit` — etiquetas por página. Opcional, inteiro de 1 a 500, padrão 100.

Nenhum parâmetro de query é obrigatório: `GET /tags` sem query params devolve a
primeira página completa.

### Resposta

```json theme={null}
{
  "items": [
    { "name": "Faturamento BR", "color": "#FFB300" },
    { "name": "Prioritário", "color": "#22C55E" },
    { "name": "VIP", "color": "#2563EB" }
  ],
  "next_cursor": "eyJuYW1lIjoiVklQIn0",
  "has_more": true
}
```

* `items` — array de etiquetas, cada uma com `name` e `color`.
* `next_cursor` — cursor da página seguinte, para enviar como `?cursor=`. É `null` quando `has_more` é `false`.
* `has_more` — indica se há mais resultados depois desta página. Repetir a chamada com o `next_cursor` até que seja `false`.

### Exemplo

Uma leitura simples, sem corpo: pede o catálogo e não muda nada no negócio.

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

Buscando com o curinga e pedindo uma página menor:

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

O `name` devolvido por esta consulta é o que depois se envia na ação.

### Erros

| Código                    | Status | Quando                                                                              |
| ------------------------- | ------ | ----------------------------------------------------------------------------------- |
| `INVALID_REQUEST`         | 400    | Algum query param não cumpre o formato (`limit` fora do intervalo, `search` vazio). |
| `INVALID_CURSOR`          | 400    | O `cursor` está corrompido ou não corresponde a este endpoint.                      |
| `INVALID_API_TOKEN`       | 401    | Token ausente, mal formado ou inválido.                                             |
| `TOKEN_BUSINESS_MISMATCH` | 403    | O slug do path não coincide com o negócio do token.                                 |
| `RATE_LIMIT_EXCEEDED`     | 429    | Limite de requisições excedido — veja [Rate limits](/pt/rate-limits).               |

O catálogo completo está em [Erros](/pt/errors).

Com o nome em mãos, a ação que o consome é
[Atribuir etiqueta](/pt/action-groups/assign-label) ou
[Remover etiqueta](/pt/action-groups/remove-label).