Detach a tag from a conversation

API Versioning

This API uses date-based versioning. Each version is identified by a release date and slug, e.g., 2026-01-01.nova.

Specifying a Version

Include the version in the request header:

Featurebase-Version: 2026-01-01.nova

Or set a default version for your organization in the dashboard settings.

Version Compatibility

Newer versions may add new fields to responses (always backwards-compatible)
Breaking changes (removed/renamed fields, changed behavior) only occur in new versions
Your integration will continue to work as long as you pin to a specific version

Authentication

All API requests require authentication via API key.

Include in headers:

Authorization: Bearer <api-key>

Create and manage your API keys in the Featurebase dashboard.

Error Handling

The API uses conventional HTTP response codes to indicate success or failure:

2xx - Success
4xx - Client errors (bad request, unauthorized, not found, etc.)
5xx - Server errors (internal error)

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Post not found",
    "param": "id",
    "status": 404
  }
}

Error Types

Type	Description
`authentication_error`	Authentication failed (401)
`authorization_error`	Permission denied (403)
`invalid_request_error`	Invalid request parameters or resource not found (400, 404, 410)
`api_error`	Server-side error (500)
`rate_limit_error`	Too many requests (429)

Boards

Boards (post categories) organize feedback into distinct containers with their own settings.

Operations

Posts

User-submitted feedback and feature requests. Posts belong to boards and can be upvoted, commented on, and tracked through statuses.

Operations

Post Statuses

Post statuses define the workflow stages for posts (e.g., In Review, Active, Completed).

Operations

Comments

Threaded discussions on posts and changelogs. Comments support voting, moderation, and privacy controls.

Operations

Custom Fields

Configurable input fields for posts in your Featurebase organization. Custom fields allow you to collect additional structured data when users create posts.

Operations

Changelogs

Release notes and updates published by the organization. Changelogs keep users informed about new features, improvements, and fixes.

Operations

Admins

Team members who manage your Featurebase organization. Admins have roles that define their permissions.

Operations

Teams

Teams are groups within your Featurebase organization. Use this endpoint to list and retrieve team information for conversation assignment and organization management.

Operations

Brands

Brands represent distinct brand identities within your organization. Each brand can have its own help center and email sending address. Use this endpoint to list and retrieve brand information.

Operations

Contacts

Contacts are the customers and leads in your Featurebase organization. Use this endpoint to list and retrieve contact information.

Operations

Companies

Companies represent organizations or businesses that your users belong to. Use this endpoint to list and retrieve company information.

Operations

Surveys

Surveys allow you to collect targeted feedback from your users within your product. Surveys can be targeted to specific user segments or pages and can contain multiple questions with conditional logic.

Operations

Help Centers

Help centers allow organizations to create and manage knowledge bases with articles and collections. Currently, Featurebase supports one help center per organization.

Operations

Conversations

Conversations are messenger/inbox conversations in your Featurebase organization. Use this endpoint to list and retrieve conversation information.

Operations

Attach a tag to a conversation

Request

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

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

Version Availability

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

Security

bearerAuth

Path

idstring[ 1 .. 16 ] characters^[a-zA-Z0-9]+$required

Conversation ID (short ID)

Example: 12345

Headers

Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova

Bodyapplication/jsonrequired

tagIdstringrequired

The Featurebase tag ID to attach to the conversation.

Example: "67ec1234abcd5678ef901234"

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"

curl -i -X POST \
  https://docs.featurebase.app/_mock/rest-api/v2/conversations/12345/tags \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Featurebase-Version: 2026-01-01.nova' \
  -d '{
    "tagId": "67ec1234abcd5678ef901234",
    "actingAdminId": "507f1f77bcf86cd799439011"
  }'

Responses

Success

Bodyapplication/json

typestringrequired

Object type identifier for a tag

Value"tag"

Example: "tag"

idstringrequired

Unique tag identifier

Example: "67ec1234abcd5678ef901234"

namestringrequired

Current tag name

Example: "Churn"

targetPartIdstring or null

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

Example: "67890"

appliedAtstring or null

ISO timestamp when the tag was applied

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

appliedByConversationTagMutationActor (object) or null

Actor that applied the tag

Any of:

Actor that applied the tag

removedAtstring or null

ISO timestamp when the tag was removed, if applicable

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

removedByConversationTagMutationActor (object) or null

Actor that removed the tag, if applicable

Any of:

Actor that applied the tag

Response

application/json

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

Detach a tag from a conversation

Request

Removes a workspace tag from a conversation.

This endpoint requires the actingAdminId of the admin on whose behalf the mutation is recorded.

Path Parameters

id - The conversation ID (short ID)
tagId - The Featurebase tag ID to remove

Request Body

Field	Type	Required	Description
`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 removal against that part so audit metadata remains deterministic.

Response

Returns the affected tag payload with the most relevant attachment metadata available for that relationship.

Example Request

{
  "actingAdminId": "507f1f77bcf86cd799439011"
}

Version Availability

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

Security

bearerAuth

Path

idstring[ 1 .. 16 ] characters^[a-zA-Z0-9]+$required

Conversation ID (short ID)

Example: 12345

tagIdstringrequired

The Featurebase tag ID to remove from the conversation.

Example: 67ec1234abcd5678ef901234

Headers

Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova

Bodyapplication/jsonrequired

actingAdminIdstringrequired

Required admin ID performing this tag removal. Must be a member of the organization so the mutation can be attributed to a real admin actor.

Example: "507f1f77bcf86cd799439011"

curl -i -X DELETE \
  https://docs.featurebase.app/_mock/rest-api/v2/conversations/12345/tags/67ec1234abcd5678ef901234 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Featurebase-Version: 2026-01-01.nova' \
  -d '{
    "actingAdminId": "507f1f77bcf86cd799439011"
  }'

Responses

Success

Bodyapplication/json

typestringrequired

Object type identifier for a tag

Value"tag"

Example: "tag"

idstringrequired

Unique tag identifier

Example: "67ec1234abcd5678ef901234"

namestringrequired

Current tag name

Example: "Churn"

targetPartIdstring or null

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

Example: "67890"

appliedAtstring or null

ISO timestamp when the tag was applied

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

appliedByConversationTagMutationActor (object) or null

Actor that applied the tag

Any of:

Actor that applied the tag

removedAtstring or null

ISO timestamp when the tag was removed, if applicable

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

removedByConversationTagMutationActor (object) or null

Actor that removed the tag, if applicable

Any of:

Actor that applied the tag

Response

application/json

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

Reply to a conversation

Request

Adds a reply to an existing conversation. Supports both contact (customer/lead) and admin replies.

Path Parameters

id - The conversation ID (short ID)

Request Body

The request body varies based on who is sending the reply:

Contact Reply (customer/lead)

Field	Type	Required	Description
`type`	string	Yes	Must be "contact"
`userId`	string	No*	External user ID from your system
`id`	string	No*	Featurebase contact ID (24-character ObjectId)
`bodyMarkdown`	string	Yes	The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored.
`messageType`	string	Yes	Must be "reply"
`skipNotifications`	boolean	No	Skip sending notifications (default: false). Useful for bulk imports.

*At least one of userId or id is required.

Admin Reply

Field	Type	Required	Description
`type`	string	Yes	Must be "admin"
`id`	string	Yes	Featurebase admin ID (24-character ObjectId)
`bodyMarkdown`	string	Yes	The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored.
`messageType`	string	Yes	"reply" for customer-visible reply, "note" for internal note
`skipNotifications`	boolean	No	Skip sending notifications (default: false). Useful for bulk imports.

Response

Returns the created conversation part object with a 201 Created status. The response includes both bodyHtml (with signed image URLs) and bodyMarkdown fields.

Example Contact Reply

{
  "type": "contact",
  "userId": "user_123",
  "bodyMarkdown": "Thank you for your help!",
  "messageType": "reply"
}

Example Admin Reply

{
  "type": "admin",
  "id": "507f1f77bcf86cd799439011",
  "bodyMarkdown": "I'm happy to help! Here's what you need to do...",
  "messageType": "reply"
}

Example Admin Note (Internal)

{
  "type": "admin",
  "id": "507f1f77bcf86cd799439011",
  "bodyMarkdown": "Customer seems frustrated, escalating to tier 2.",
  "messageType": "note"
}

Example Response

{
  "object": "conversation_part",
  "id": "3",
  "partType": "user_msg",
  "bodyHtml": "<p>Thank you for your help!</p>",
  "bodyMarkdown": "Thank you for your help!",
  "author": {
    "type": "customer",
    "id": "676f0f6765bdaa7d7d760f88",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "channel": "desktop",
  "createdAt": "2025-01-15T10:40:00.000Z",
  "updatedAt": "2025-01-15T10:40:00.000Z"
}

Version Availability

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

Security

bearerAuth

Path

idstring[ 1 .. 16 ] characters^[a-zA-Z0-9]+$required

Conversation ID (short ID)

Example: 12345

Headers

Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova

Bodyapplication/jsonrequired

typestringrequired

The type of author. Use "contact" for customer/lead replies.

Value"contact"

Example: "contact"

Discriminator

userIdstring<= 255 characters

The external user ID from your system

Example: "user_123"

idstring

The Featurebase contact ID

Example: "676f0f6765bdaa7d7d760f88"

bodyMarkdownstringnon-emptyrequired

The content of the reply message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored.

Example: "Thank you for your help!"

messageTypestringrequired

The type of message. Always "reply" for contact replies.

Value"reply"

Example: "reply"

skipNotificationsboolean

Skip sending notifications (default: false). Useful for bulk imports.

Default false

Example: false

curl -i -X POST \
  https://docs.featurebase.app/_mock/rest-api/v2/conversations/12345/reply \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Featurebase-Version: 2026-01-01.nova' \
  -d '{
    "type": "contact",
    "userId": "user_123",
    "id": "676f0f6765bdaa7d7d760f88",
    "bodyMarkdown": "Thank you for your help!",
    "messageType": "reply",
    "skipNotifications": false
  }'

Responses

Created

Bodyapplication/json

objectstringrequired

Object type identifier

Value"conversation_part"

Example: "conversation_part"

idstringrequired

Unique part identifier

Example: "1"

createdAtstringrequired

ISO timestamp when the part was created

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

updatedAtstringrequired

ISO timestamp when the part was last updated

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

authorobject or null(ConversationPartAuthor)

redactedboolean

Whether this message has been redacted

Example: false

tagApplicationsArray of objects(ConversationTagApplication)

Reply-level tag applications and provenance for this conversation part

partTypestringrequired

User message type

Value"user_msg"

Example: "user_msg"

Discriminator

bodyHtmlstring or nullrequired

Message body content as HTML with signed image URLs

Example: "<p>Hello, I have a question about your product.</p>"

bodyMarkdownstring or nullrequired

Message body content as markdown

Example: "Hello, I have a question about your product."

channelstringrequired

Channel through which the message was sent

Enum"unknown""desktop""android""ios""email"

Example: "desktop"

Response

application/json

{
  "object": "conversation_part",
  "id": "1",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "author": {
    "type": "customer",
    "id": "676f0f6765bdaa7d7d760f88",
    "name": "John Doe",
    "email": "john@example.com",
    "profilePicture": "https://cdn.example.com/avatars/user.png"
  },
  "redacted": false,
  "tagApplications": [
    { … }
  ],
  "partType": "user_msg",
  "bodyHtml": "<p>Hello, I have a question about your product.</p>",
  "bodyMarkdown": "Hello, I have a question about your product.",
  "channel": "desktop"
}

Conversation Tags

Conversation tags let you organize, filter, and automate around inbox conversations. Use these endpoints to list, look up, create, rename, and delete workspace conversation tags.

Operations

Tickets

Tickets represent support requests in your Featurebase organization. Create, update, reply to, and manage tickets via these endpoints.

Operations

Webhooks

Webhooks allow you to receive real-time HTTP callbacks when events occur in your Featurebase organization. Configure webhook endpoints to subscribe to specific event types.

Operations

Featurebase API (2026-01-01.nova)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

API Versioning

Authentication

Error Handling

Boards

Posts

Post Statuses

Comments

Custom Fields

Changelogs

Admins

Teams

Brands

Contacts

Companies

Surveys

Help Centers

Conversations

Attach a tag to a conversation

Request

Path Parameters

Request Body

Behavior

Response

Example Request

Version Availability

Responses

Was this helpful?

Detach a tag from a conversation

Request

Path Parameters

Request Body

Behavior

Response

Example Request

Version Availability

Responses

Was this helpful?

Reply to a conversation

Request

Path Parameters

Request Body

Contact Reply (customer/lead)

Admin Reply

Response

Example Contact Reply

Example Admin Reply

Example Admin Note (Internal)

Example Response

Version Availability

Responses

Was this helpful?

Conversation Tags

Tickets

Webhooks

Featurebase API (2026-01-01.nova)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code