> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Tag

> Create a new tag within a classification hierarchy with display name, description, parent relationships, and styling for data asset categorization using the Collate REST API.

# Create a Tag

Create a new tag within a classification.

## Body Parameters

**name** `string` *required*

Name of the tag. Must be unique within the parent classification or parent tag.

**classification** `string` *required*

Fully qualified name of the parent classification, for example `Certification`.

**displayName** `string`

Human-readable display name for the tag.

**description** `string`

Description of the tag in Markdown format.

**parent** `string`

Fully qualified name of the parent tag for creating nested tags, for example `PII.Sensitive`.

**style** `object`

Visual styling for the tag.

**properties**

**color** `string`

Hex color code, for example `#C08320`.

**iconURL** `string`

URL to a custom icon for the tag.

**owners** `array`

Array of owner references (users or teams) to assign to the tag.

**properties**

**id** `string`

UUID of the owner entity.

**type** `string`

Type of owner entity, for example `user`, `team`.

**name** `string`

Name of the owner entity.

**provider** `string`

Provider of the tag: `user` (custom) or `system` (built-in).

```python POST /v1/tags theme={null}
from metadata.sdk import configure
from metadata.sdk.entities import Tags
from metadata.generated.schema.api.classification.createTag import CreateTagRequest

configure(
    host="https://your-company.getcollate.io/api",
    jwt_token="your-jwt-token"
)

request = CreateTagRequest(
    name="Bronze",
    classification="Certification",
    description="Bronze certified Data Asset.",
    style={"color": "#C08320"}
)

tag = Tags.create(request)
print(f"Created: {tag.fullyQualifiedName.root}")
```

```java POST /v1/tags theme={null}
import org.openmetadata.schema.api.classification.CreateTag;
import org.openmetadata.schema.entity.type.Style;

// client is an initialized OpenMetadataClient.
var request = new CreateTag()
    .withName("Bronze")
    .withClassification("Certification")
    .withDescription("Bronze certified Data Asset.")
    .withStyle(new Style().withColor("#C08320"));

var tag = client.tags().create(request);
```

```bash POST /v1/tags theme={null}
curl -X POST "{base_url}/api/v1/tags" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bronze",
    "classification": "Certification",
    "description": "Bronze certified Data Asset.",
    "style": {"color": "#C08320"},
    "owners": []
  }'
```

```json Response theme={null}
{
  "id": "68ec158c-5f5e-4277-8a19-5e9e0cd5294f",
  "name": "Bronze",
  "fullyQualifiedName": "Certification.Bronze",
  "description": "Bronze certified Data Asset.",
  "style": {
    "color": "#C08320"
  },
  "version": 0.1,
  "updatedAt": 1769982619666,
  "updatedBy": "admin",
  "classification": {
    "id": "06d90883-6be9-4f7e-9475-753f10a95e94",
    "type": "classification",
    "name": "Certification",
    "fullyQualifiedName": "Certification",
    "deleted": false
  },
  "deleted": false,
  "owners": [],
  "provider": "system",
  "mutuallyExclusive": false
}
```

***

## Returns

Returns the created tag object with all specified properties and system-generated fields.

## Response

**id** `string`

Unique identifier for the tag (UUID format).

**name** `string`

Tag name.

**fullyQualifiedName** `string`

Fully qualified name in format `classification.tagName` or `classification.parent.child`.

**displayName** `string`

Human-readable display name.

**description** `string`

Description of the tag in Markdown format.

**style** `object`

Visual styling for the tag.

**properties**

**color** `string`

Hex color code.

**iconURL** `string`

URL to a custom icon.

**classification** `object`

Reference to the parent classification.

**properties**

**id** `string`

UUID of the classification.

**type** `string`

Type of entity (always `classification`).

**name** `string`

Name of the classification.

**fullyQualifiedName** `string`

Fully qualified name of the classification.

**provider** `string`

Provider: `user` or `system`.

**owners** `array`

List of owners assigned to the tag.

**version** `number`

Version number for the entity (starts at 0.1).

***

## Create or Update (PUT)

Use `PUT /v1/tags` instead of `POST` to perform an upsert. If a tag with the same `fullyQualifiedName` already exists, it will be updated; otherwise, a new tag is created. The request body is the same as `POST`.

```bash theme={null}
curl -X PUT "{base_url}/api/v1/tags" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ ... same body as POST ... }'
```

> [!NOTE]
>
> `PUT` will not return a `409` conflict error if the entity already exists -- it will update the existing entity instead. However, for certain fields (such as description, tags, owners, and custom properties), `PUT` preserves an already-populated value instead of overwriting it with an empty or omitted one -- the exact behavior depends on the field and the calling user or bot's permissions, not a blanket rule. See [Entity Update Behavior](https://docs.getcollate.io/api-reference/entity-updates.md) for the full preserve/merge rules. Use `PATCH` to intentionally replace an existing value.

***

## Error Handling

| Code | Error Type | Description |
| - | - | - |
| `400` | `BAD_REQUEST` | Invalid request body or missing required fields |
| `401` | `UNAUTHORIZED` | Invalid or missing authentication token |
| `403` | `FORBIDDEN` | User lacks permission to create tags |
| `409` | `ENTITY_ALREADY_EXISTS` | Tag with same name already exists in classification (POST only) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.