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

> Add a named set of tags for one kind of record

Creates an empty group. Add tags to it with
[Create Tag](/api-reference/create-tag).

## Body

<ParamField body="subject_type" type="string" required>
  `account`, `person` or `path`. What the group's tags label. Fixed once
  created: a tag cannot move between groups, and a group cannot change subject.
</ParamField>

<ParamField body="name" type="string" required>
  1-80 characters, unique for that subject type. A name already used by a group
  of the same subject type answers `409 CONFLICT`.
</ParamField>

<ParamField body="selection" type="string" default="multi">
  `single` holds at most one of the group's tags per record, which is how a
  status behaves. `multi` holds any number.
</ParamField>

<Note>
  **A record type holds at most 20 groups, and a group at most 50 tags.** Both
  return `422` rather than growing without limit: past a couple of dozen a flat
  picker stops being scannable, and what you want is another dimension rather
  than a hundredth tag.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.clustr-ai.com/api/public/tag-groups" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"subject_type": "account", "name": "Segment", "selection": "single"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "group": {
        "id": "5a1c3f88-92d4-4b0e-8e7a-1f2b3c4d5e60",
        "subject_type": "account",
        "name": "Segment",
        "selection": "single",
        "position": 2,
        "is_system": false
      }
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": { "message": "subject_type must be account, person or path", "code": "BAD_REQUEST" }
  }
  ```

  ```json 409 theme={null}
  {
    "success": false,
    "error": { "message": "a tag group with that name already exists for this record type", "code": "CONFLICT" }
  }
  ```

  ```json 422 theme={null}
  {
    "success": false,
    "error": { "message": "a record type can hold at most 20 tag groups", "code": "UNPROCESSABLE_ENTITY" }
  }
  ```
</ResponseExample>