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

# Create Tag

> Add a tag to a group

A tag always belongs to a group, and the group decides which records it can go
on. Create the group first with
[Create Tag Group](/api-reference/create-tag-group), or read an existing one
from [List Tag Groups](/api-reference/list-tag-groups).

## Body

<ParamField body="group_id" type="string" required>
  The group's id. A group id from another workspace reads as absent, so the tag
  cannot be created into it.
</ParamField>

<ParamField body="name" type="string" required>
  1-50 characters.
</ParamField>

<ParamField body="color" type="string" required>
  A hex colour, e.g. `#3B82F6`. It is rendered through a normaliser that caps
  saturation and clamps lightness, so a neon value displays calmer than you sent
  it.
</ParamField>

<ParamField body="closes" type="boolean" default="false">
  Opportunity (`path`) tags only: this tag closes the opportunity it is on.
  Rows carrying it sort last and draw with a neutral pill; they stay visible and
  filterable, because a tag never hides a row.
</ParamField>

<Note>
  **Position is not yours to set.** A new tag goes to the end of its group. A
  group holds at most 50 tags.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.clustr-ai.com/api/public/tags" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
      "name": "Meeting booked",
      "color": "#22C55E"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "tag": {
        "id": "cbfd0074-57bd-4fa7-a5fc-8bb5392b16c9",
        "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
        "name": "Meeting booked",
        "color": "#22C55E",
        "position": 3,
        "closes": false
      }
    }
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": { "message": "tag group not found", "code": "NOT_FOUND" }
  }
  ```

  ```json 422 theme={null}
  {
    "success": false,
    "error": { "message": "a tag group can hold at most 50 tags", "code": "UNPROCESSABLE_ENTITY" }
  }
  ```
</ResponseExample>