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

# Labels

> Query the business label catalog to assign or remove labels by name.

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

<Note>
  **Read-only** endpoint: it returns information and changes nothing. It is not sent inside the `actions` array — you call it directly.
</Note>

Returns the business label catalog, in alphabetical order and paginated by
cursor. It excludes deleted labels and the system labels the dashboard creates
by default.

Use it to learn the exact `name` of a label before using it: the `assign_label`
and `remove_label` actions identify each label by name, so it is best to read
the catalog first instead of guessing the text.

**Parameters**

* `slug` — the business slug, in the path. Case-insensitive, must match the business of the token (**required**).
* `search` — name substring, case-insensitive. Optional, 1 to 100 characters. The asterisk `*` works as a wildcard and matches any sequence of characters: `fact*mx` finds both `Facturas MX` and `Facturación MX`. The characters `%` and `_` are matched literally.
* `cursor` — opaque cursor returned by the previous page in `next_cursor`. Optional; omit it to request the first page. Do not reuse cursors across different endpoints: even though the format is identical, each endpoint interprets it over its own data set.
* `limit` — labels per page. Optional, integer from 1 to 500, defaults to 100.

No query parameter is required: `GET /tags` with no query params returns the
full first page.

### Response

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

* `items` — array of labels, each one with `name` and `color`.
* `next_cursor` — cursor for the next page, to be passed as `?cursor=`. It is `null` when `has_more` is `false`.
* `has_more` — whether there are more results after this page. Repeat the call with `next_cursor` until it is `false`.

### Example

A plain read, with no body: it asks for the catalog and changes nothing in the
business.

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

Searching with the wildcard and asking for a smaller page:

```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_your_api_key"
```

The `name` returned by this query is the one you then send in the action.

### Errors

| Code                      | Status | When                                                                                     |
| ------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| `INVALID_REQUEST`         | 400    | A query param does not match the expected format (`limit` out of range, empty `search`). |
| `INVALID_CURSOR`          | 400    | The `cursor` is corrupt or does not belong to this endpoint.                             |
| `INVALID_API_TOKEN`       | 401    | Token missing, malformed or invalid.                                                     |
| `TOKEN_BUSINESS_MISMATCH` | 403    | The slug in the path does not match the business of the token.                           |
| `RATE_LIMIT_EXCEEDED`     | 429    | Request limit exceeded — see [Rate limits](/en/rate-limits).                             |

The full catalog is in [Errors](/en/errors).

With the name in hand, the action that consumes it is
[Assign label](/en/action-groups/assign-label) or
[Remove label](/en/action-groups/remove-label).