Skip to main content
POST
/
tag-groups
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"}
    ]
  }'

{
  "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"
}

​
Request Body

​
id
string
Optional client-provided ID. Format: tag_group_{uuidv7}
​
scopeId
string
required
ID of the scope where this tag group is defined
​
name
string
required
Display name for the tag group
​
key
string
required
Unique key for the tag group within the scope. Must be lowercase alphanumeric with underscores.
​
description
string
required
Description of the tag group
​
origin
string
Origin of the tag group. One of: system, user. Default: user
​
maxAppliedPerTarget
number
Maximum number of tags from this group that can be applied to a single target
​
isLocked
boolean
Whether the tag group is locked from modifications. Default: false
​
tags
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

​
Response

Returns the created tag group object.
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.
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"}
    ]
  }'

{
  "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"
}

​
Examples

​
Basic Tag Group (No Inline Tags)

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

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

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"}
    ]
  }'