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

# List All Contact Tags via the ChatbotX REST API

> Use GET /api/v1/tags to retrieve a paginated list of all tags in your ChatbotX workspace, with optional keyword filtering to find specific tags quickly.

Tags let you categorise and segment your contacts for targeted messaging and automation. Use this endpoint to retrieve all tags defined in your workspace. You can paginate through results and search by keyword to locate specific tags quickly.

<Info>
  **GET** `/api/v1/tags`
</Info>

## Query Parameters

<ParamField query="page" type="integer">
  The page number to retrieve. Must be `1` or greater. Defaults to `1`.
</ParamField>

<ParamField query="perPage" type="integer">
  Number of tags to return per page. Must be `1` or greater.
</ParamField>

<ParamField query="keyword" type="string">
  Filter tags by name. Returns all tags whose name contains the provided keyword (case-insensitive).
</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://app.chatbotx.io/api/v1/tags?page=1&perPage=20' \
    --header 'Authorization: Bearer <token>'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.chatbotx.io/api/v1/tags"

  params = {"page": 1, "perPage": 20}
  headers = {"Authorization": "Bearer <token>"}

  response = requests.get(url, params=params, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'GET',
    headers: { Authorization: 'Bearer <token>' }
  };

  fetch('https://app.chatbotx.io/api/v1/tags?page=1&perPage=20', options)
    .then(res => res.json())
    .then(res => console.log(res))
    .catch(err => console.error(err));
  ```
</CodeGroup>

## Response

Returns `200 OK` with a `data` array of tag objects.

### Response Fields

<ResponseField name="data" type="array" required>
  Array of tag objects belonging to the workspace.

  <Expandable title="data item fields">
    <ResponseField name="id" type="string" required>
      Unique identifier for the tag.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name of the tag.
    </ResponseField>

    <ResponseField name="workspaceId" type="string">
      The ID of the workspace this tag belongs to.
    </ResponseField>

    <ResponseField name="folderId" type="string | null">
      The folder this tag is organised into, or `null` if it is not in a folder.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "201",
      "name": "VIP Customer",
      "workspaceId": "42",
      "folderId": null
    },
    {
      "id": "202",
      "name": "Newsletter Subscriber",
      "workspaceId": "42",
      "folderId": "3"
    }
  ]
}
```