# Create or rename a tag

Creates a new workspace conversation tag when only name is provided. If id is also provided, the existing tag is renamed instead.

Endpoint: POST /v2/tags
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Request fields (application/json):

  - `id` (string)
    Optional existing tag ID. Provide this to rename an existing tag instead of creating a new one.
    Example: "67ec1234abcd5678ef901234"

  - `name` (string, required)
    Tag name
    Example: "Churn"

  - `actingAdminId` (string)
    Optional admin ID for actor attribution and permission checks.
    Example: "507f1f77bcf86cd799439011"

## Response 200 fields (application/json):

  - `type` (string, required)
    Object type identifier for a tag
    Enum: "tag"

  - `id` (string, required)
    Unique tag identifier
    Example: "67ec1234abcd5678ef901234"

  - `name` (string, required)
    Current tag name
    Example: "Churn"

## Response 401 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "authentication_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "organization_required"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 401

## Response 403 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "authorization_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "forbidden"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 403

## Response 404 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "resource_not_found"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 404