Conversations

Attach a tag to a conversation

Attaches a workspace tag to a conversation.

POST

/v2/conversations/{id}/tags

curl --request POST \
  --url https://do.featurebase.app/v2/conversations/{id}/tags \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actingAdminId": "507f1f77bcf86cd799439011",
  "tagId": "67ec1234abcd5678ef901234"
}
'

{
  "appliedAt": "2025-01-15T10:30:00.000Z",
  "appliedBy": {
    "id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "type": "admin"
  },
  "id": "67ec1234abcd5678ef901234",
  "name": "Churn",
  "removedAt": "2025-01-15T11:00:00.000Z",
  "removedBy": {
    "id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "type": "admin"
  },
  "targetPartId": "67890",
  "type": "tag"
}

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

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

Version Availability

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

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

idstringrequired

Conversation ID (short ID)

Required string length: 1 - 16

Pattern: ^[a-zA-Z0-9]+$

Example: 12345

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

actingAdminIdstringrequired

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

tagIdstringrequired

The Featurebase tag ID to attach to the conversation.

Example: 67ec1234abcd5678ef901234

Response

Success

appliedAtstring | null

ISO timestamp when the tag was applied

Example: 2025-01-15T10:30:00.000Z

appliedByobject | null

Actor that applied the tag

Show child attributes

idstringrequired

Unique tag identifier

Example: 67ec1234abcd5678ef901234

namestringrequired

Current tag name

Example: Churn

removedAtstring | null

ISO timestamp when the tag was removed, if applicable

Example: 2025-01-15T11:00:00.000Z

removedByobject | null

Actor that removed the tag, if applicable

Show child attributes

targetPartIdstring | null

Reply/message ID used as the deterministic attachment target for this conversation tag mutation.

Example: 67890

typeenum<string>required

Object type identifier for a tag

Available options: tag

Example: tag

Still need help? Ask the team