# Attach a tag to a conversation

Attaches a workspace tag to a conversation.

This endpoint requires both the tag ID to attach and the actingAdminId of the admin on whose behalf the mutation is recorded.

### Path Parameters

- id - The conversation ID (short ID)

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| tagId | string | Yes | The Featurebase tag ID to attach |
| actingAdminId | string | Yes | The admin performing the mutation. Must be a member of the organization. |

### Behavior

Featurebase resolves the latest taggable reply/message in the conversation and records the tag attachment against that part so audit metadata remains deterministic.

### Response

Returns the affected tag plus attachment metadata such as targetPartId, appliedAt, and appliedBy.

### Example Request

json
{
  "tagId": "67ec1234abcd5678ef901234",
  "actingAdminId": "507f1f77bcf86cd799439011"
}


### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Endpoint: POST /v2/conversations/{id}/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"

## Path parameters:

  - `id` (string, required)
    Conversation ID (short ID)
    Example: "12345"

## Request fields (application/json):

  - `tagId` (string, required)
    The Featurebase tag ID to attach to the conversation.
    Example: "67ec1234abcd5678ef901234"

  - `actingAdminId` (string, required)
    Required admin ID performing this tag attachment. Must be a member of the organization so the mutation can be attributed to a real admin actor.
    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"

  - `targetPartId` (string,null)
    Reply/message ID used as the deterministic attachment target for this conversation tag mutation.
    Example: "67890"

  - `appliedAt` (string,null)
    ISO timestamp when the tag was applied
    Example: "2025-01-15T10:30:00.000Z"

  - `appliedBy` (any)
    Actor that applied the tag

  - `removedAt` (string,null)
    ISO timestamp when the tag was removed, if applicable
    Example: "2025-01-15T11:00:00.000Z"

  - `removedBy` (any)
    Actor that removed the tag, if applicable

## Response 400 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: "invalid_request"

  - `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: 400

## 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: "conversation_not_found", "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