# Create, Add, Remove Tag

> 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](/4yItIzMvkpAvMVFAamTf/features/search/tags.md) 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.

```json
{
    "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.

```json
{
    "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):**

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

**Remove multiple tags (recommended):**

```json
{
 "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 |

{% hint style="info" %}
**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
  {% endhint %}

**Add tags to multiple nodes:**

```json
{
 "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:**

```json
{
 "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:**

```json
{
 "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 (`{}`).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/tags/tags-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.