---
title: "Create a tag definition"
method: POST
path: "/tags"
tags: ["TagService"]
---

# Create a tag definition

`POST /tags`

## Request

- Base URL: `https://csp.infoblox.com/api/atlas-tagging/v2`
- URL: `https://csp.infoblox.com/api/atlas-tagging/v2/tags`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/infoblox/apis/atlas-tagging-api/docs/tags/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new tag definition in the authenticated account's default namespace. Returns the created tag definition with a server-assigned UUID. Tag key must be unique within the namespace and account.

## Request body

- ServiceTag
  - `compartment_id` string: The compartment ID for multi-tenancy scoping.
  - `created_at` string, date-time: Read-only. Timestamp created_at, equals to time when particular object was created. Format: RFC 3339 (ISO 8601).
  - `deleted_at` string, date-time: Read-only. Timestamp deleted_at, equals to time when particular object was deleted, by default equals to null. Format: RFC 3339 (ISO 8601).
  - `id` string: The resource identifier.
  - `key` string: The tag key. Must be unique within a namespace and account.
  - `namespace` ServiceNamespace
    - `created_at` string, date-time: Read-only. Timestamp created_at, equals to time when particular object was created. Format: RFC 3339 (ISO 8601).
    - `deleted_at` string, date-time: Read-only. Timestamp deleted_at, equals to time when particular object was deleted, by default equals to null. Format: RFC 3339 (ISO 8601).
    - `id` string: The resource identifier.
    - `name` string: Human-readable name for namespace.
    - `type` string: The namespace type. Valid values: "freeform" (default), "locked", "system".
    - `updated_at` string, date-time: Read-only. Timestamp updated_at, equals to time when particular object was updated, by default equals to created_at. Format: RFC 3339 (ISO 8601).
  - `regexp` string: The tag regexp. POSIX regexp string, used for values validation. By default equals to "*" (allow all). Only applies to freeform tags.
  - `regexp_description` string: The regexp_description, optional human-readable description explaining the regexp validation pattern.
  - `status` string: The tag status. Valid values: "active" (default), "revoked" (soft-deleted).
  - `type` string: The tag type. Valid values: "freeform" (default — any value allowed), "restricted" (only predefined values allowed).
  - `updated_at` string, date-time: Read-only. Timestamp updated_at, equals to time when particular object was updated, by default equals to created_at. Format: RFC 3339 (ISO 8601).
  - `values` ServiceValue[]: The values is a repeated value objects which belongs to particular tag. For restricted tags, defines the set of allowed values.
    - `created_at` string, date-time: Read-only. Timestamp created_at, equals to time when particular object was created. Format: RFC 3339 (ISO 8601).
    - `deleted_at` string, date-time: Read-only. Timestamp deleted_at, equals to time when particular object was deleted, by default equals to null. Format: RFC 3339 (ISO 8601).
    - `id` string: The resource identifier.
    - `value` string: The value string. Trimmed of leading/trailing whitespace on input.
  - `version` integer: The version is used for optimistic concurrency control — prevents multiple users from updating the same tag simultaneously. Must match the current server-side version for updates to succeed.

## Response `201`

A successful response.

- ServiceCreateTagResponse: CreateTagResponse contains the created tag definition with server-assigned ID.
  - `result` ServiceTag
    - `compartment_id` string: The compartment ID for multi-tenancy scoping.
    - `created_at` string, date-time: Read-only. Timestamp created_at, equals to time when particular object was created. Format: RFC 3339 (ISO 8601).
    - `deleted_at` string, date-time: Read-only. Timestamp deleted_at, equals to time when particular object was deleted, by default equals to null. Format: RFC 3339 (ISO 8601).
    - `id` string: The resource identifier.
    - `key` string: The tag key. Must be unique within a namespace and account.
    - `namespace` ServiceNamespace
      - `created_at` string, date-time: Read-only. Timestamp created_at, equals to time when particular object was created. Format: RFC 3339 (ISO 8601).
      - `deleted_at` string, date-time: Read-only. Timestamp deleted_at, equals to time when particular object was deleted, by default equals to null. Format: RFC 3339 (ISO 8601).
      - `id` string: The resource identifier.
      - `name` string: Human-readable name for namespace.
      - `type` string: The namespace type. Valid values: "freeform" (default), "locked", "system".
      - `updated_at` string, date-time: Read-only. Timestamp updated_at, equals to time when particular object was updated, by default equals to created_at. Format: RFC 3339 (ISO 8601).
    - `regexp` string: The tag regexp. POSIX regexp string, used for values validation. By default equals to "*" (allow all). Only applies to freeform tags.
    - `regexp_description` string: The regexp_description, optional human-readable description explaining the regexp validation pattern.
    - `status` string: The tag status. Valid values: "active" (default), "revoked" (soft-deleted).
    - `type` string: The tag type. Valid values: "freeform" (default — any value allowed), "restricted" (only predefined values allowed).
    - `updated_at` string, date-time: Read-only. Timestamp updated_at, equals to time when particular object was updated, by default equals to created_at. Format: RFC 3339 (ISO 8601).
    - `values` ServiceValue[]: The values is a repeated value objects which belongs to particular tag. For restricted tags, defines the set of allowed values.
      - `created_at` string, date-time: Read-only. Timestamp created_at, equals to time when particular object was created. Format: RFC 3339 (ISO 8601).
      - `deleted_at` string, date-time: Read-only. Timestamp deleted_at, equals to time when particular object was deleted, by default equals to null. Format: RFC 3339 (ISO 8601).
      - `id` string: The resource identifier.
      - `value` string: The value string. Trimmed of leading/trailing whitespace on input.
    - `version` integer: The version is used for optimistic concurrency control — prevents multiple users from updating the same tag simultaneously. Must match the current server-side version for updates to succeed.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/infoblox/apis/atlas-tagging-api.md) - [All operations](https://skmtc.dev/infoblox/apis/atlas-tagging-api/llms.txt) - [OpenAPI document](https://skmtc.dev/infoblox/apis/atlas-tagging-api/revisions/4255d62cedc5?raw)