Skip to main content

​
What is a Tag Group?

A tag group is a container for related tags. Instead of having a flat list of all tags, you organize them into logical groups like “Departments”, “Sensitivity Levels”, or “Project Types”. Tag groups also define constraints like how many tags from the group can be applied to a single target.

​
Tag Group Properties

PropertyTypeDescription
idstringUnique identifier
scopeIdstringScope where this group is defined
namestringHuman-readable name
keystringMachine-readable key
descriptionstringWhat this group is for
maxAppliedPerTargetnumber | nullMax tags from this group per target (null = unlimited)
originTagGroupOriginEnumHow this group was created
isLockedbooleanWhether the group can be modified
createdBystringSubject who created it
createdAtDateCreation timestamp

​
Creating Tag Groups

Create a tag group and its tags in a single request: 
curl -X POST 'https://api.example.com/tag-groups' \
  -H 'Content-Type: application/json' \
  -d '{
    "scopeId": "scope_project",
    "name": "Departments",
    "key": "departments",
    "description": "Company departments for access control",
    "tags": [
      {"identifier": "engineering", "label": "Engineering"},
      {"identifier": "sales", "label": "Sales"},
      {"identifier": "finance", "label": "Finance"},
      {"identifier": "hr", "label": "Human Resources"}
    ]
  }'
Inline tags automatically inherit scopeId and tagGroupId from the parent group. You only need to provide identifier and label.

​
Basic (Without Tags)

curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Departments",
    "key": "departments",
    "description": "Company departments for access control"
  }'

​
With Constraints

# Only one sensitivity level allowed per resource
curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_project",
    "name": "Sensitivity Level",
    "key": "sensitivity",
    "description": "Data classification level",
    "maxAppliedPerTarget": 1,
    "tags": [
      {"identifier": "public", "label": "Public"},
      {"identifier": "internal", "label": "Internal Only"},
      {"identifier": "confidential", "label": "Confidential"},
      {"identifier": "restricted", "label": "Restricted"}
    ]
  }'

​
maxAppliedPerTarget

This constraint controls how many tags from the group can be applied to a single target:
ValueMeaningUse Case
nullUnlimitedDepartments (user can be in multiple)
1Exactly oneSensitivity level, status
3Up to threeTop 3 skills, primary categories
# Unlimited: A document can belong to multiple departments
{"name": "Departments", "maxAppliedPerTarget": null}

# Single: A document has exactly one sensitivity level
{"name": "Sensitivity", "maxAppliedPerTarget": 1}

# Limited: A user can have up to 3 skill tags
{"name": "Skills", "maxAppliedPerTarget": 3}

​
Tag Group Origin

The origin field tracks how the group was created:
OriginDescription
systemCreated by Bedrock (built-in groups)
userCreated by a user
integrationCreated by an external integration

​
Locked Tag Groups

Locked groups cannot be modified or deleted: 
# Create a locked group (typically for system-critical tags)
curl -X POST 'https://api.example.com/tag-groups' \
  -d '{
    "scopeId": "scope_org",
    "name": "Compliance Zones",
    "key": "compliance",
    "isLocked": true
  }'
Locked groups require special permissions to unlock. Use this for critical classification schemes.

​
Common Tag Group Patterns

​
Organizational Structure

curl -X POST 'https://api.example.com/tag-groups/batch' \
  -d '[
    {
      "scopeId": "scope_project",
      "name": "Departments",
      "key": "departments",
      "description": "Organization departments",
      "tags": [
        {"identifier": "engineering", "label": "Engineering"},
        {"identifier": "sales", "label": "Sales"},
        {"identifier": "finance", "label": "Finance"}
      ]
    },
    {
      "scopeId": "scope_project",
      "name": "Teams",
      "key": "teams",
      "description": "Cross-functional teams",
      "tags": [
        {"identifier": "backend", "label": "Backend"},
        {"identifier": "frontend", "label": "Frontend"},
        {"identifier": "platform", "label": "Platform"}
      ]
    }
  ]'

​
Data Classification

curl -X POST 'https://api.example.com/tag-groups/batch' \
  -d '[
    {
      "scopeId": "scope_project",
      "name": "Sensitivity",
      "key": "sensitivity",
      "maxAppliedPerTarget": 1,
      "tags": [
        {"identifier": "public", "label": "Public"},
        {"identifier": "internal", "label": "Internal"},
        {"identifier": "confidential", "label": "Confidential"},
        {"identifier": "restricted", "label": "Restricted"}
      ]
    },
    {
      "scopeId": "scope_project",
      "name": "Compliance",
      "key": "compliance",
      "description": "Regulatory compliance requirements",
      "tags": [
        {"identifier": "hipaa", "label": "HIPAA"},
        {"identifier": "gdpr", "label": "GDPR"},
        {"identifier": "sox", "label": "SOX"}
      ]
    }
  ]'

​
Project Management

curl -X POST 'https://api.example.com/tag-groups/batch' \
  -d '[
    {
      "scopeId": "scope_project",
      "name": "Priority",
      "key": "priority",
      "maxAppliedPerTarget": 1,
      "tags": [
        {"identifier": "critical", "label": "Critical"},
        {"identifier": "high", "label": "High"},
        {"identifier": "medium", "label": "Medium"},
        {"identifier": "low", "label": "Low"}
      ]
    },
    {
      "scopeId": "scope_project",
      "name": "Status",
      "key": "status",
      "maxAppliedPerTarget": 1,
      "tags": [
        {"identifier": "open", "label": "Open"},
        {"identifier": "in_progress", "label": "In Progress"},
        {"identifier": "review", "label": "In Review"},
        {"identifier": "done", "label": "Done"}
      ]
    }
  ]'

​
Construction / Field Service

curl -X POST 'https://api.example.com/tag-groups/batch' \
  -d '[
    {
      "scopeId": "scope_project",
      "name": "Labor Classes",
      "key": "labor_classes",
      "description": "Worker certifications and specialties",
      "tags": [
        {"identifier": "electrician", "label": "Electrician"},
        {"identifier": "plumber", "label": "Plumber"},
        {"identifier": "carpenter", "label": "Carpenter"},
        {"identifier": "foreman", "label": "Foreman"}
      ]
    },
    {
      "scopeId": "scope_project",
      "name": "Safety Certifications",
      "key": "safety_certs",
      "tags": [
        {"identifier": "osha_10", "label": "OSHA 10"},
        {"identifier": "osha_30", "label": "OSHA 30"},
        {"identifier": "first_aid", "label": "First Aid"}
      ]
    }
  ]'

​
Adding Tags to Existing Groups

If you created a group without inline tags, you can add tags later: 
# Add tags to an existing Departments group
curl -X POST 'https://api.example.com/tags/batch' \
  -d '[
    {"scopeId": "scope_project", "tagGroupId": "tg_departments", "identifier": "engineering", "label": "Engineering"},
    {"scopeId": "scope_project", "tagGroupId": "tg_departments", "identifier": "sales", "label": "Sales"},
    {"scopeId": "scope_project", "tagGroupId": "tg_departments", "identifier": "finance", "label": "Finance"}
  ]'
For new tag groups, prefer using inline tags in the create request. Use separate tag creation only when adding tags to existing groups.

​
Querying Tag Groups

# Get all tag groups in a scope
curl -X GET 'https://api.example.com/tag-groups?scopeId=scope_project'

# Get a specific tag group
curl -X GET 'https://api.example.com/tag-groups/tg_departments'

# Get tags in a group
curl -X GET 'https://api.example.com/tags?tagGroupId=tg_departments'

​
API Reference

Create Tag Group

Create a new tag group

Get Tag Groups

List tag groups

Update Tag Group

Update a tag group

Delete Tag Group

Delete a tag group

​
Next Steps

Tag Bindings

Learn how to control which models can use which tag groups