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

# Create Tag Group

> Create a new tag group with optional inline tags

## Request Body

<ParamField body="id" type="string">
  Optional client-provided ID. Format: `tag_group_{uuidv7}`
</ParamField>

<ParamField body="scopeId" type="string" required>
  ID of the scope where this tag group is defined
</ParamField>

<ParamField body="name" type="string" required>
  Display name for the tag group
</ParamField>

<ParamField body="key" type="string" required>
  Unique key for the tag group within the scope. Must be lowercase alphanumeric with underscores.
</ParamField>

<ParamField body="description" type="string" required>
  Description of the tag group
</ParamField>

<ParamField body="origin" type="string">
  Origin of the tag group. One of: `system`, `user`. Default: `user`
</ParamField>

<ParamField body="maxAppliedPerTarget" type="number">
  Maximum number of tags from this group that can be applied to a single target
</ParamField>

<ParamField body="isLocked" type="boolean">
  Whether the tag group is locked from modifications. Default: `false`
</ParamField>

<ParamField body="tags" type="array">
  Optional array of inline tags to create with the group. Each tag has:

  * `id` (optional): Client-provided ID
  * `identifier` (required): Unique identifier within the group (lowercase alphanumeric with underscores/hyphens)
  * `label` (required): Display label for the tag
</ParamField>

## Response

Returns the created tag group object.

<Note>
  You can create a tag group with its tags in a single request using the `tags` array. The tags will automatically inherit the `scopeId` and `tagGroupId` from the parent group.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.example.com/tag-groups' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "scopeId": "scope_project",
      "name": "Priority",
      "key": "priority",
      "description": "Task priority levels",
      "maxAppliedPerTarget": 1,
      "tags": [
        {"identifier": "high", "label": "High"},
        {"identifier": "medium", "label": "Medium"},
        {"identifier": "low", "label": "Low"}
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "tag_group_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "scopeId": "scope_project",
    "name": "Priority",
    "key": "priority",
    "description": "Task priority levels",
    "origin": "user",
    "maxAppliedPerTarget": 1,
    "isLocked": false,
    "createdAt": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

## Examples

### Basic Tag Group (No Inline Tags)

```bash theme={null}
curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Status",
    "key": "status",
    "description": "Item status"
  }'
```

### Tag Group with Inline Tags

```bash theme={null}
curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Departments",
    "key": "departments",
    "description": "Organization departments",
    "tags": [
      {"identifier": "engineering", "label": "Engineering"},
      {"identifier": "sales", "label": "Sales"},
      {"identifier": "marketing", "label": "Marketing"},
      {"identifier": "finance", "label": "Finance"}
    ]
  }'
```

### Single-Select Tag Group

```bash theme={null}
curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Environment Type",
    "key": "env_type",
    "description": "Deployment environment classification",
    "maxAppliedPerTarget": 1,
    "tags": [
      {"identifier": "production", "label": "Production"},
      {"identifier": "staging", "label": "Staging"},
      {"identifier": "development", "label": "Development"}
    ]
  }'
```