> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/tags/tags-api.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.