Create, Add, Remove Tag

Create, apply, and remove Veza tags

New in 2025.11.24: Bulk tagging operations are now available as part of the private/ API set.

Use these APIs to create, add, and remove Veza tags. These endpoints support bulk onboarding of external tags into Veza Access Graph, environment migrations, and maintaining Veza Tags at scale.

Methods

Create Veza Tag

Post {VezaURL}/api/v1/graph/tags

Define a new tag that can be applied to any discovered entity, as a key:value pair. The tag value is optional.

{
    "tag": {
        "key": "note",
        "value": "tags_can_be_used_as_searchable_properties,_or_add_extended_notes"
    }
}

Parameter	In	Description
tag	body	Contains a single key:value pair
key	body	Max length 255 characters (alphanumeric and _)
value	body	Max length 4096 characters.

A successful response will be empty ({}).

Add Veza Tag

Post {VezaURL}/api/v1/graph/nodes/tags

Apply one or more tags to an entity by providing an entity ID. A new Tag will be created if one doesn't already exist.

{
    "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
    "tags": [
        {
            "key": "PII",
            "value": "GRPC"
        },
        {
            "key": "environment",
            "value": "production"
        }
    ]
}

Parameter	In	Description
node_id	body	Veza entity ID
tags	body	Array of tags to add

To retrieve an entity ID, you can use the Query Builder API, or browse the Identity Data Entities catalog.

Remove Veza Tag

Post {VezaURL}/api/v1/graph/nodes/tags:remove

Remove one or more tags from an entity.

Parameter	In	Description
node_id	body	ID of the entity to modify
tag_keys	body	Array of tag keys to remove (1-100 tags)
tag_key	body	Deprecated: Single tag key to remove

Remove single tag (legacy format):

{
 "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
 "tag_key": "environment"
}

Remove multiple tags (recommended):

{
 "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
 "tag_keys": ["environment", "department", "owner"]
}

A successful response will be empty ({}).

Bulk Tag Operations

Post {VezaURL}/graph/private/tags:bulk

Add or remove tags from multiple entities in a single atomic operation. All operations execute within a single transaction; if any operation encounters a retryable error, the entire transaction rolls back.

Parameter	In	Description
add	body	Array of add tag requests
remove	body	Array of remove tag requests

Operation Limit: Maximum of 10,000 total tag operations per request (combined count of all tags added or removed across all nodes).

Validation rules:

• Each add request: supports 1-100 tags per node

• Each remove request: supports 1-100 tag keys per node

• Total operations (all tags in all add/remove requests): Maximum 10,000

• Tag keys: 1-255 characters (alphanumeric and _)

• Tag values: Maximum 4,096 characters

Add tags to multiple nodes:

{
 "add": [
  {
   "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
   "tags": [
    {
     "key": "environment",
     "value": "production"
    },
    {
     "key": "department",
     "value": "engineering"
    }
   ]
  },
  {
   "node_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
   "tags": [
    {
     "key": "environment",
     "value": "production"
    }
   ]
  }
 ]
}

Remove tags from multiple nodes:

{
 "remove": [
  {
   "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
   "tag_keys": ["temporary", "archived"]
  },
  {
   "node_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
   "tag_keys": ["temporary"]
  }
 ]
}

Combined add and remove operations:

{
 "add": [
  {
   "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
   "tags": [
    {
     "key": "status",
     "value": "active"
    }
   ]
  }
 ],
 "remove": [
  {
   "node_id": "080551dc-aef9-46e4-9654-a6362d7baeee",
   "tag_keys": ["temporary"]
  },
  {
   "node_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
   "tag_keys": ["archived", "deprecated"]
  }
 ]
}

A successful response will be empty ({}).