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

# Create a New Contact Tag via the ChatbotX REST API

> Use POST /api/v1/tags to create a new contact tag in your ChatbotX workspace by supplying a unique name and an optional folder assignment.

Tags help you label and segment contacts for use in broadcasts, sequences, and automation flows. Use this endpoint to create a new tag in your workspace. Each tag name must be unique within the workspace. You can optionally place the tag into a folder to keep your tag library organised.

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

## Request Body

<ParamField body="name" type="string" required>
  A unique name for the tag. Must be between 1 and 255 characters.
</ParamField>

<ParamField body="folderId" type="string | null">
  The ID of the folder to place this tag in. Pass `null` or omit to leave the tag unorganised.
</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://app.chatbotx.io/api/v1/tags \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "High Value Lead",
      "folderId": null
    }'
  ```

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

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

  payload = {
      "name": "High Value Lead",
      "folderId": None
  }
  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'High Value Lead',
      folderId: null
    })
  };

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

## Response

Returns `201 Created` with the newly created tag object.

### Response Fields

<ResponseField name="id" type="string" required>
  The unique identifier for the created tag.
</ResponseField>

<ResponseField name="name" type="string" required>
  The name of the newly created tag.
</ResponseField>

### Example Response

```json theme={null}
{
  "id": "203",
  "name": "High Value Lead"
}
```