# Featurebase API

Welcome to the Featurebase API. This API allows you to programmatically interact with your Featurebase organization.

This documentation reflects API version **2026-01-01.nova**.

Version: 2026-01-01.nova
License: Proprietary

## Servers

Production
```
https://do.featurebase.app
```

## Security

### bearerAuth

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

Type: http
Scheme: bearer

## Download OpenAPI description

[Featurebase API](https://docs.featurebase.app/_bundle/REST%20API/@2026-01-01.nova/index.yaml)

## Boards

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

### List all boards

 - [GET /v2/boards](https://docs.featurebase.app/rest-api/boards/listboards.md): Returns all boards (post categories) for the authenticated organization.

Boards are containers for posts/feedback. Each board can have different:
- Access controls (public, private, segment-restricted)
- Feature toggles (comments, posting enabled)
- Custom fields

This endpoint returns all boards without pagination. Organizations typically have a small number of boards.

### Get a board by ID

 - [GET /v2/boards/{id}](https://docs.featurebase.app/rest-api/boards/getboard.md): Retrieves a single board by its unique identifier.

Returns the full board object including all access controls,
feature toggles, and localization settings.

## Posts

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

### List all posts

 - [GET /v2/posts](https://docs.featurebase.app/rest-api/posts/listposts.md): Returns all posts (feedback submissions) for the authenticated organization.

Posts are user-submitted feedback items. Each post belongs to a board and can have:
- Status (in progress, complete, etc.)
- Tags for categorization
- Upvotes from users
- Comments (if enabled)
- Custom field values

### Pagination

This endpoint uses cursor-based pagination:

- limit - Number of posts to return (1-100, default 10)
- cursor - Opaque cursor from a previous response's nextCursor field

Example: To paginate through results:
1. First request: GET /v2/posts?limit=10
2. If nextCursor is not null, use it for the next page
3. Next request: GET /v2/posts?limit=10&cursor={nextCursor}

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of post objects
- nextCursor - Cursor for the next page (null if no more results)

### Filtering

Filter posts using query parameters:
- boardId - Filter by board (category) ID
- statusId - Filter by status ID
- tags - Filter by tag names (can be comma-separated or repeated)
- q - Search query for title/content
- inReview - Include posts pending moderation

### Sorting

Use sortBy to sort results:
- createdAt - Sort by creation date (default)
- upvotes - Sort by vote count
- trending - Sort by trending score
- recent - Sort by most recently updated

### Create a new post

 - [POST /v2/posts](https://docs.featurebase.app/rest-api/posts/createpost.md): Creates a new post (feedback submission) in the specified board.

### Required Fields

- title - Post title (minimum 2 characters)
- boardId - Board ID to create the post in

### Optional Fields

- content - Post content in HTML format
- tags - Array of tag names to attach
- statusId - Status ID to set (defaults to board's default status)
- commentsEnabled - Whether comments are allowed (default: true)
- inReview - Whether post is pending moderation (default: false)
- customFields - Custom field values as key-value pairs
- eta - Estimated completion date (Unix timestamp or ISO date)
- assigneeId - Admin ID to assign this post to
- visibility - Post-level visibility restriction: 'public' (no additional restrictions), 'authorOnly' (only author and admins), or 'companyOnly' (only users in author's company). Note: even 'public' posts are still subject to board-level and organization-level access controls.

### Author Attribution

For posts created on behalf of users, use the author object:
- id - Featurebase user ID
- userId - External SSO user ID
- email - User's email address
- name - Display name
- profilePicture - Profile picture URL

Resolution priority: id > userId > email > authenticated user

### Backdating (Imports)

- createdAt - Override creation date for importing historical data

### Response

Returns the created post object with all fields populated.

### Get a post by ID

 - [GET /v2/posts/{id}](https://docs.featurebase.app/rest-api/posts/getpost.md): Retrieves a single post by its unique identifier.

Returns the full post object including:
- Author information
- Current status
- Tags
- Voting stats
- Engagement metrics
- Custom field values

### Update a post

 - [PATCH /v2/posts/{id}](https://docs.featurebase.app/rest-api/posts/updatepost.md): Updates an existing post. Only provided fields will be modified.

### Updatable Fields

- title - Post title (minimum 2 characters)
- content - Post content in HTML format
- boardId - Move post to a different board
- statusId - Update post status
- tags - Replace existing tags with new set
- commentsEnabled - Enable/disable comments
- inReview - Put post in/out of moderation queue
- customFields - Update custom field values
- eta - Set estimated completion date (null to clear)
- createdAt - Update creation date (for backdating)
- assigneeId - Admin ID to assign this post to (null to unassign)
- visibility - Post-level visibility restriction: 'public' (no additional restrictions), 'authorOnly' (only author and admins), or 'companyOnly' (only users in author's company). Note: even 'public' posts are still subject to board-level and organization-level access controls.
- author - Change post attribution (id, userId, email, name, profilePicture)

### Status Update Notifications

- sendStatusUpdateEmail - When changing status, optionally send email notification to voters (default: false)

### Response

Returns the updated post object with all fields populated.

### Delete a post

 - [DELETE /v2/posts/{id}](https://docs.featurebase.app/rest-api/posts/deletepost.md): Permanently deletes a post. This action cannot be undone.

### What Gets Deleted

When you delete a post:
- The post itself is permanently removed
- All comments on the post are deleted
- Vote records are removed
- Any associated notifications are cleared

### Response

Returns a deletion confirmation object with:
- id - The ID of the deleted post
- object - Always "post"
- deleted - Always true

### Permissions

Requires member-level access or higher to delete posts.

### List voters on a post

 - [GET /v2/posts/{id}/voters](https://docs.featurebase.app/rest-api/posts/listvoters.md): Returns all voters (upvoters) for a specific post.

Voters are users who have upvoted the post. Each voter is returned in the standard user format with:
- Basic info: id, name, email, profilePicture
- User type (admin, customer, guest, etc.)
- Companies the user belongs to
- Activity stats: commentsCreated, postsCreated, lastActivity
- Preferences: subscribedToChangelog, locale, verified

### Pagination

This endpoint uses cursor-based pagination:

- limit - Number of voters to return (1-100, default 10)
- cursor - Opaque cursor from a previous response's nextCursor field

Example: To paginate through results:
1. First request: GET /v2/posts/{id}/voters?limit=10
2. If nextCursor is not null, use it for the next page
3. Next request: GET /v2/posts/{id}/voters?limit=10&cursor={nextCursor}

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of user objects
- nextCursor - Cursor for the next page (null if no more results)

### Permissions

Requires member-level access or higher.

### Add a voter to a post

 - [POST /v2/posts/{id}/voters](https://docs.featurebase.app/rest-api/posts/addvoter.md): Adds a voter (upvote) to a post.

### Voter Identification

To add a vote on behalf of a user, provide one or more identification fields:
- id - Featurebase user ID
- userId - External SSO user ID from your system
- email - User's email address
- name - Display name (used when creating a new user)
- profilePicture - Profile picture URL (used when creating a new user)

Resolution priority: id > userId > email > authenticated user

If no fields are provided, the authenticated user's vote is added.

If the user doesn't exist, a new customer will be created with the provided information.

### Idempotency

If the user has already voted on this post, the request succeeds but no duplicate vote is added.

### Response

Returns a confirmation object with:
- object - Always "voter"
- added - Always true
- id - The voter's user ID
- postId - The post ID the vote was added to

### Permissions

Requires member-level access or higher.

### Remove a voter from a post

 - [DELETE /v2/posts/{id}/voters](https://docs.featurebase.app/rest-api/posts/removevoter.md): Removes a voter (upvote) from a post.

### Voter Identification

To remove a vote on behalf of a user, provide one or more identification fields:
- id - Featurebase user ID
- userId - External SSO user ID from your system
- email - User's email address

Resolution priority: id > userId > email > authenticated user

If no fields are provided, the authenticated user's vote will be removed.

### Response

Returns a confirmation object with:
- object - Always "voter"
- removed - Always true
- id - The voter's user ID
- postId - The post ID the vote was removed from

### Permissions

Requires member-level access or higher.

## Post Statuses

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

### List all post statuses

 - [GET /v2/post_statuses](https://docs.featurebase.app/rest-api/post-statuses/listpoststatuses.md): Returns all post statuses for the authenticated organization.

Post statuses define workflow stages for posts. Each status has:
- A display name and color
- A type indicating the workflow stage (reviewing, unstarted, active, completed, canceled)
- A flag indicating if it's the default status for new posts

This endpoint returns all post statuses without pagination. Organizations typically have a small number of statuses.

### Get a post status by ID

 - [GET /v2/post_statuses/{id}](https://docs.featurebase.app/rest-api/post-statuses/getpoststatus.md): Retrieves a single post status by its unique identifier.

Returns the full post status object including name, color, type, and default flag.

## Comments

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

### List comments

 - [GET /v2/comments](https://docs.featurebase.app/rest-api/comments/listcomments.md): Returns comments for your organization.

Comments are threaded discussions. Each comment can have:
- Author information
- Voting (upvotes/downvotes)
- Privacy settings (public/private)
- Moderation status
- Parent comment reference for threading

### Filtering

Optionally filter by:
- postId - Get comments for a specific post
- changelogId - Get comments for a specific changelog

If no filter is provided, returns all comments across the organization.

### Pagination

This endpoint uses cursor-based pagination:

- limit - Number of comments to return (1-100, default 10)
- cursor - Opaque cursor from a previous response's nextCursor field

Example: To paginate through results:
1. First request: GET /v2/comments?postId={id}&limit=10
2. If nextCursor is not null, use it for the next page
3. Next request: GET /v2/comments?postId={id}&limit=10&cursor={nextCursor}

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of comment objects (flat structure with parentCommentId for threading)
- nextCursor - Cursor for the next page (null if no more results)

### Comment Structure

Each comment includes:
- id - Unique comment identifier
- postId / changelogId - Reference to the parent content
- parentCommentId - Reference to parent comment (null for root comments)
- content - Comment content in HTML format
- author - Author information (id, name, profilePicture, type)
- upvotes / downvotes / score - Voting metrics
- isPrivate - Whether comment is only visible to admins
- inReview - Whether comment is pending moderation
- created / updated - Unix timestamps

### Additional Filters

- privacy - Filter by privacy: "public", "private", or "all"
- inReview - Filter by moderation status (true/false)

### Sorting

Use sortBy to sort results:
- best - Sort by confidence score (default, like Reddit)
- top - Sort by net score (upvotes - downvotes)
- new - Sort by creation date, newest first
- old - Sort by creation date, oldest first

### Create a new comment

 - [POST /v2/comments](https://docs.featurebase.app/rest-api/comments/createcomment.md): Creates a new comment or reply to an existing comment.

You can create a comment for a post or changelog. Comments support:
- HTML content (images are automatically uploaded to our storage)
- Threading (replies via parentCommentId)
- Privacy controls (private comments visible only to admins)
- Author attribution (post on behalf of users)

### Required Fields

- content - Comment content in HTML format
- postId OR changelogId - One is required to specify the target

### Optional Fields

- parentCommentId - Create a reply to an existing comment
- isPrivate - Make comment visible only to admins (default: false)
- sendNotification - Notify voters about the comment (default: true)
- author - Post comment under a specific user (uses authenticated user if not provided)
- createdAt - Backdate creation (useful for imports)

### Author Object

The author field supports multiple identification methods:
- id - Featurebase user ID (direct reference)
- userId - External user ID from your system (via SSO)
- email - Email address (finds existing or creates new user)
- name - Display name (used with email for new users)
- profilePicture - Profile picture URL

If no author is provided, the comment is posted under the authenticated user.

### Content Format

Content should be formatted as HTML. For images:
- External URLs in img src attributes are automatically pulled into our storage
- Base64 encoded data URIs (data:image/...) are also supported and processed

### Response

Returns the created comment object with all fields populated, including:
- id - Unique comment identifier
- author - Author information
- Voting stats and timestamps

### Errors

- 400 - Invalid input (missing required fields, invalid IDs)
- 403 - Commenting disabled or not authorized
- 404 - Post/changelog not found or parent comment not found

### Get a comment by ID

 - [GET /v2/comments/{id}](https://docs.featurebase.app/rest-api/comments/getcomment.md): Retrieves a single comment by its unique identifier.

Returns the full comment object including:
- Author information
- Voting stats (upvotes, downvotes, score)
- Privacy and moderation status
- Threading information (parentCommentId)
- Timestamps

### Response

Returns a comment object with all fields populated.

### Errors

- 400 - Invalid comment ID format
- 404 - Comment not found or doesn't belong to your organization

### Update a comment

 - [PATCH /v2/comments/{id}](https://docs.featurebase.app/rest-api/comments/updatecomment.md): Updates an existing comment by its unique identifier.

You can update:
- content - Comment text (HTML format)
- isPrivate - Privacy status (admin-only visibility)
- isPinned - Pinned status (displayed at top)
- inReview - Moderation status

### Content Format

Content should be formatted as HTML. For images:
- External URLs in img src attributes are automatically pulled into our storage
- Base64 encoded data URIs (data:image/...) are also supported and processed

### Permissions

- Comment authors can update their own comment content
- Admin permissions required for:
  - isPrivate - Requires manage_comments_private permission
  - isPinned - Requires set_comment_pinned permission
  - inReview - Requires moderate_comments permission
  - Updating other users' comments - Requires moderate_comments permission

### Response

Returns the updated comment object with all fields populated.

### Errors

- 400 - Invalid comment ID format or input
- 403 - Not authorized to update this comment
- 404 - Comment not found

### Delete a comment

 - [DELETE /v2/comments/{id}](https://docs.featurebase.app/rest-api/comments/deletecomment.md): Deletes a comment by its unique identifier.

### Deletion Behavior

- Comments with replies: Soft delete
  - Content is replaced with "[deleted]"
  - Author information is anonymized
  - Comment remains visible to maintain conversation context
  - Votes and scores are reset to 0

- Comments without replies: Hard delete
  - Comment is permanently removed from the database
  - All associated data is deleted

### Permissions

- Comment authors can delete their own comments
- Admins can delete any comment (subject to permissions)
- Lite seat admins can only delete their own comments
- Non-authors require manage_comments or manage_comments_private permission

### Response

Returns a deletion confirmation:

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "comment",
  "deleted": true
}


### Errors

- 400 - Invalid comment ID format
- 403 - Not authorized to delete this comment
- 404 - Comment not found or doesn't belong to your organization

### Delete a comment

 - [DELETE /v2/comment](https://docs.featurebase.app/rest-api/comments/deletecommentclover.md): Deletes a comment using the legacy Clover API format.

This endpoint accepts the comment ID in the request body instead of the route parameter.

### Request Body

json
{
  "id": "507f1f77bcf86cd799439011"
}


### Deletion Behavior

- Comments with replies: Soft delete
  - Content is replaced with "[deleted]"
  - Author information is anonymized
  - Comment remains visible to maintain conversation context
  - Votes and scores are reset to 0

- Comments without replies: Hard delete
  - Comment is permanently removed from the database
  - All associated data is deleted

### Permissions

- Comment authors can delete their own comments
- Admins can delete any comment (subject to permissions)
- Lite seat admins can only delete their own comments
- Non-authors require manage_comments or manage_comments_private permission

### Response

Returns a success confirmation (Clover format):

json
{
  "success": true
}


Note: Nova API returns { id, object: "comment", deleted: true }, but Clover transformer converts it to { success: true } for backwards compatibility.

### Errors

- 400 - Invalid comment ID format or missing ID in body
- 403 - Not authorized to delete this comment
- 404 - Comment not found or doesn't belong to your organization

## Custom Fields

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

### List custom fields

 - [GET /v2/custom_fields](https://docs.featurebase.app/rest-api/custom-fields/listcustomfields.md): Returns all custom fields configured in your organization.

This endpoint returns all custom fields at once (typically a small list). No pagination is supported.

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of custom field objects
- nextCursor - Always null

### Custom Field Object

Each custom field includes:
- id - Unique field identifier
- label - Field label displayed to users
- type - Field type (text, number, select, multi-select, checkbox, date)
- required - Whether the field is required
- placeholder - Placeholder text (for text/number fields)
- public - Whether the field value is publicly visible
- internal - Whether the field is for internal use only
- options - Array of options (for select/multi-select fields)

### Field Types

- text - Single line text input
- number - Numeric input
- select - Single-choice dropdown
- multi-select - Multiple-choice dropdown
- checkbox - Boolean checkbox
- date - Date picker

### Get a custom field by ID

 - [GET /v2/custom_fields/{id}](https://docs.featurebase.app/rest-api/custom-fields/getcustomfield.md): Retrieves a single custom field by its unique identifier.

Returns the custom field object if found in your organization.

### Response

Returns a custom field object with:
- id - Unique field identifier
- label - Field label displayed to users
- type - Field type (text, number, select, multi-select, checkbox, date)
- required - Whether the field is required
- placeholder - Placeholder text (for text/number fields)
- public - Whether the field value is publicly visible
- internal - Whether the field is for internal use only
- options - Array of options (for select/multi-select fields)

### Errors

- 404 - Custom field not found in your organization

## Changelogs

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

### List all changelogs

 - [GET /v2/changelogs](https://docs.featurebase.app/rest-api/changelogs/listchangelogs.md): Returns all changelogs for the authenticated organization.

Changelogs are release notes and updates that keep users informed about new features, improvements, and bug fixes. Each changelog can have:
- Multiple translations (locales)
- Categories for organization
- Featured images
- Scheduled publishing

### Pagination

This endpoint uses cursor-based pagination:

- limit - Number of changelogs to return (1-100, default 10)
- cursor - Opaque cursor from a previous response's nextCursor field

Example: To paginate through results:
1. First request: GET /v2/changelogs?limit=10
2. If nextCursor is not null, use it for the next page
3. Next request: GET /v2/changelogs?limit=10&cursor={nextCursor}

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of changelog objects
- nextCursor - Cursor for the next page (null if no more results)

### Filtering

Filter changelogs using query parameters:
- id - Find a specific changelog by ID or slug
- q - Search query for title/content
- categories - Filter by category names
- locale - Get changelogs in a specific locale (defaults to org default)
- state - Filter by state: live, draft, or all
- startDate - Include changelogs dated on or after this date
- endDate - Include changelogs dated on or before this date

### Sorting

Results are sorted by date (descending by default):
- sortBy - Field to sort by (currently only date)
- sortOrder - Sort direction: asc or desc (default: desc)

### Create a new changelog

 - [POST /v2/changelogs](https://docs.featurebase.app/rest-api/changelogs/createchangelog.md): Creates a new changelog for the authenticated organization.

### Required Fields

- title - The title of the changelog

### Content

Provide content in one of two formats (at least one is required):
- htmlContent - HTML content of the changelog
- markdownContent - Markdown content of the changelog

Note: For images in content, you can use:
- External URLs in img src attributes (automatically uploaded to our storage)
- Base64 encoded data URIs (data:image/...) which are processed and stored

### Optional Fields

- categories - Array of category names (e.g., ["New", "Fixed", "Improved"])
- featuredImage - URL of the featured image (external URLs are uploaded to our storage)
- allowedSegmentIds - Array of segment IDs that are allowed to view the changelog
- locale - The locale of the changelog (defaults to organization default)
- date - The date of the changelog
- state - The state of the changelog: draft (default) or live

### Response

Returns the created changelog object.

### Get a changelog by ID

 - [GET /v2/changelogs/{id}](https://docs.featurebase.app/rest-api/changelogs/getchangelog.md): Retrieves a single changelog by its unique identifier or slug.

Returns the full changelog object including:
- Title and content (in HTML and markdown formats)
- Featured image
- Publication date
- Categories
- Comment count
- Email notification status

### Localization

The changelog content is returned in the organization's default locale.
If the changelog doesn't exist in the default locale, the first available locale is used.

### State

Both published (live) and draft changelogs can be retrieved.
The state field indicates the current publication status.

### Update a changelog

 - [PATCH /v2/changelogs/{id}](https://docs.featurebase.app/rest-api/changelogs/updatechangelog.md): Updates an existing changelog by its unique identifier.

You can update:
- title - The changelog title
- htmlContent - HTML content (one of htmlContent or markdownContent)
- markdownContent - Markdown content (one of htmlContent or markdownContent)
- categories - Array of category names
- featuredImage - Featured image URL
- allowedSegmentIds - Segment IDs for access control
- date - The date of the changelog

### Content Format

Provide content in one of two formats:
- htmlContent - HTML content of the changelog
- markdownContent - Markdown content of the changelog

Note: For images in content, you can use:
- External URLs in img src attributes (automatically uploaded to our storage)
- Base64 encoded data URIs (data:image/...) which are processed and stored

### Categories

Provide category names as an array. The categories must already exist in your organization.

Example: ["New", "Fixed", "Improved"]

### Response

Returns the updated changelog object with all fields populated.

### Errors

- 400 - Invalid changelog ID format or invalid input
- 404 - Changelog not found or doesn't belong to your organization

### Delete a changelog

 - [DELETE /v2/changelogs/{id}](https://docs.featurebase.app/rest-api/changelogs/deletechangelog.md): Deletes a changelog by its unique identifier.

### Deletion Behavior

The changelog and all associated comments are permanently deleted. This action cannot be undone.

### Permissions

Only organization admins can delete changelogs.

### Response

Returns a deletion confirmation:

json
{
  "id": "6457e3ff70afca5d8c27dccc",
  "object": "changelog",
  "deleted": true
}


### Errors

- 400 - Invalid changelog ID format
- 404 - Changelog not found or doesn't belong to your organization

### Publish a changelog

 - [POST /v2/changelogs/{id}/publish](https://docs.featurebase.app/rest-api/changelogs/publishchangelog.md): Publishes a changelog and optionally sends an email notification to subscribers.

### Optional Fields

- sendEmail - Whether to send an email notification to subscribers (default: false)
- locales - Array of locales to publish. An empty array publishes to all available locales
- scheduledDate - A future date/time when the changelog should be published

### Scheduling

If scheduledDate is provided:
- Must be a future date
- The changelog will be scheduled for publishing at that time
- Any existing scheduled publish for the same locales will be cancelled and replaced

### Email Notifications

If sendEmail is true:
- Email notifications are sent to all subscribers in the published locales
- Emails are only sent once per locale (won't resend on republish)

### Response

Returns a success confirmation:

json
{
  "success": true,
  "state": "published"
}


Or for scheduled publishes:

json
{
  "success": true,
  "state": "scheduled"
}


### Errors

- 400 - Invalid changelog ID or scheduled date is not in the future
- 404 - Changelog not found or doesn't belong to your organization

### Unpublish a changelog

 - [POST /v2/changelogs/{id}/unpublish](https://docs.featurebase.app/rest-api/changelogs/unpublishchangelog.md): Unpublishes a changelog, removing it from public view.

### Optional Fields

- locales - Array of locales to unpublish from. An empty array unpublishes from all locales

### Behavior

- The changelog content is preserved (reverts to draft state)
- Any scheduled publishes for the specified locales are cancelled
- The changelog can be re-published later

### Response

Returns a success confirmation:

json
{
  "success": true,
  "state": "unpublished"
}


### Errors

- 400 - Invalid changelog ID format
- 404 - Changelog not found or doesn't belong to your organization

### Add changelog subscribers

 - [POST /v2/changelogs/subscribers](https://docs.featurebase.app/rest-api/changelogs/addchangelogsubscribers.md): Adds email addresses as changelog subscribers in bulk.

Subscribers will receive email notifications when new changelogs are published (if email notifications are enabled during publishing).

### Request Body

- emails - Array of email addresses to add (required, 1-1000 emails)
- locale - Locale for the subscribers (optional, defaults to organization default)

### Email Validation

- Invalid email addresses are automatically filtered out
- Emails are normalized (trimmed, lowercased)
- Duplicate emails are deduplicated

### Rate Limiting

This endpoint is rate limited to prevent abuse. If you need to import more subscribers, please contact support.

### Response

Returns a confirmation with the count of processed emails:

json
{
  "object": "changelog_subscribers_import",
  "count": 150
}


### Errors

- 400 - Invalid request (empty emails array, too many emails)
- 429 - Rate limit exceeded

### Remove changelog subscribers

 - [DELETE /v2/changelogs/subscribers](https://docs.featurebase.app/rest-api/changelogs/removechangelogsubscribers.md): Removes email addresses from changelog subscribers in bulk.

Removed subscribers will no longer receive email notifications when new changelogs are published.

### Request Body

- emails - Array of email addresses to remove (required, 1-1000 emails)

### Email Handling

- Emails that don't exist as subscribers are silently ignored
- Emails are normalized (trimmed, lowercased) before matching

### Response

Returns a confirmation with the count of processed emails:

json
{
  "object": "changelog_subscribers_removal",
  "count": 150
}


### Errors

- 400 - Invalid request (empty emails array, too many emails)

## Admins

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

### List admins

 - [GET /v2/admins](https://docs.featurebase.app/rest-api/admins/listadmins.md): Returns all admins for your organization.

This endpoint returns all admins at once (typically a small list). No pagination is supported.

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of admin objects
- nextCursor - Always null

### Admin Object

Each admin includes:
- id - Unique admin identifier
- name - Admin's display name
- email - Admin's email address
- picture - Profile picture URL
- roleId - ID of the role assigned to this admin

### Get an admin by ID

 - [GET /v2/admins/{id}](https://docs.featurebase.app/rest-api/admins/getadmin.md): Retrieves a single admin by their unique identifier.

Returns the admin object if found and they belong to your organization.

### Response

Returns an admin object with:
- id - Unique admin identifier
- name - Admin's display name
- email - Admin's email address
- picture - Profile picture URL
- roleId - ID of the role assigned to this admin

### Errors

- 404 - Admin not found or doesn't belong to your organization

### List admin roles

 - [GET /v2/admins/roles](https://docs.featurebase.app/rest-api/admins/listadminroles.md): Returns all available admin roles and their permissions.

This endpoint returns all roles at once (typically a small list). No pagination is supported.

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of admin role objects
- nextCursor - Always null

### Admin Role Object

Each role includes:
- id - Unique role identifier
- name - Role name (e.g., "Admin", "Viewer")
- permissions - Object containing permission flags

### Permissions

The permissions object contains boolean flags for each permission:
- view_comments_private - Can view private comments
- manage_comments - Can manage comments
- manage_comments_private - Can manage private comments
- set_comment_pinned - Can pin comments
- moderate_comments - Can moderate comments
- set_post_category - Can change post categories
- set_post_pinned - Can pin posts
- set_post_eta - Can set post ETA
- set_post_tags - Can manage post tags
- set_post_author - Can change post author
- set_post_status - Can change post status
- set_post_assignee - Can assign posts
- set_post_custom_fields - Can edit custom fields
- post_vote_on_behalf - Can vote on behalf of users
- post_merge - Can merge posts
- post_import - Can import posts
- post_export - Can export posts
- moderate_posts - Can moderate posts
- view_users - Can view users
- manage_users - Can manage users
- view_posts_private - Can view private posts
- view_private_post_tags - Can view private tags
- manage_changelogs - Can manage changelogs
- manage_surveys - Can manage surveys
- manage_branding - Can manage branding
- manage_billing - Can manage billing
- manage_team_members - Can manage team members
- manage_sso - Can manage SSO settings
- manage_api - Can manage API settings
- manage_statuses - Can manage statuses
- manage_boards - Can manage boards
- manage_post_tags - Can manage post tags
- manage_custom_fields - Can manage custom fields
- manage_moderation_settings - Can manage moderation
- manage_roadmap - Can manage roadmap
- manage_user_roles - Can manage user roles
- manage_prioritization - Can manage prioritization
- manage_notifications - Can manage notifications
- manage_custom_domain - Can manage custom domain
- manage_integrations - Can manage integrations
- use_integrations - Can use integrations
- manage_help_center - Can manage help center
- auto_approve_posts - Posts auto-approved

## Teams

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

### List all teams

 - [GET /v2/teams](https://docs.featurebase.app/rest-api/teams/listteams.md): Returns all teams in your organization.

### Response Structure

The response includes:
- object - Always "list"
- data - Array of team objects

### Team Object

Each team includes:
- id - Unique team identifier
- name - Team display name
- color - Team color in hex format
- icon - Team icon (emoji, predefined, or external URL)
- members - Array of admin IDs who are members of this team

### Example Response

json
{
  "object": "list",
  "data": [
    {
      "object": "team",
      "id": "507f1f77bcf86cd799439011",
      "name": "Support Team",
      "color": "#3B82F6",
      "icon": {
        "value": "👥",
        "type": "emoji"
      },
      "members": ["5fef50c5e9458a0012f82456", "5fef50c5e9458a0012f82457"]
    }
  ]
}


### Version Availability

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

### Get team by ID

 - [GET /v2/teams/{id}](https://docs.featurebase.app/rest-api/teams/getteambyid.md): Retrieves a single team by its Featurebase ID.

### Path Parameters

- id - The Featurebase internal ID of the team (MongoDB ObjectId)

### Response

Returns a team object with:
- id - Unique team identifier
- name - Team display name
- color - Team color in hex format
- icon - Team icon (emoji, predefined, or external URL)
- members - Array of admin IDs who are members of this team

### Example Response

json
{
  "object": "team",
  "id": "507f1f77bcf86cd799439011",
  "name": "Support Team",
  "color": "#3B82F6",
  "icon": {
    "value": "👥",
    "type": "emoji"
  },
  "members": ["5fef50c5e9458a0012f82456", "5fef50c5e9458a0012f82457"]
}


### Error Responses

- 404 Not Found - Team with the specified ID does not exist

### Version Availability

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

## Contacts

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

### List contacts

 - [GET /v2/contacts](https://docs.featurebase.app/rest-api/contacts/listcontacts.md): Returns a list of contacts (customers and leads) in your organization using cursor-based pagination.

### Query Parameters

- limit - Number of contacts to return (1-100, default 10)
- cursor - Cursor from previous response for pagination
- contactType - Filter by contact type: "customer" (default), "lead", or "all"

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of contact objects
- nextCursor - Cursor for the next page, or null if no more results

### Contact Object

Each contact includes:
- id - Unique contact identifier
- userId - External user ID from SSO (if set)
- email - Contact email address
- name - Contact display name
- profilePicture - Profile picture URL
- type - Contact type ("customer" or "lead")
- companies - Array of companies the contact belongs to
- customFields - Custom field values
- postsCreated - Number of posts created
- commentsCreated - Number of comments created
- lastActivity - Last activity timestamp

### Example

json
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "676f0f6765bdaa7d7d760f88",
      "email": "john@example.com",
      "name": "John Doe",
      "type": "customer",
      ...
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}


### Version Availability

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

### Create or update a contact

 - [POST /v2/contacts](https://docs.featurebase.app/rest-api/contacts/upsertcontact.md): Creates a new contact or updates an existing one.

If a contact with the given email or userId already exists, it will be updated.
Otherwise, a new contact will be created.

At least one of email or userId must be provided for identification.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | One of email/userId | Contact email address |
| userId | string | One of email/userId | External user ID from your system |
| name | string | No | Contact display name |
| profilePicture | string | No | Profile picture URL |
| companies | array | No | Companies the contact belongs to |
| customFields | object | No | Custom field values |
| subscribedToChangelog | boolean | No | Whether subscribed to changelog |
| locale | string | No | Contact locale/language |
| phone | string | No | Contact phone number |
| roles | array | No | Role IDs to assign |
| userHash | string | No | HMAC hash for identity verification |
| createdAt | string | No | When the contact was created (ISO 8601) |

### Company Object

Each company in the companies array can have:
- id (required) - External company ID from your system
- name (required) - Company name
- monthlySpend - Monthly spend/revenue
- customFields - Custom field values
- industry - Industry
- website - Company website URL
- plan - Current plan/subscription
- companySize - Number of employees
- createdAt - When the company was created

### Response

Returns the created or updated contact object.

- 201 Created - A new contact was created
- 200 OK - An existing contact was updated

### Example Request

json
{
  "email": "john@example.com",
  "name": "John Doe",
  "userId": "usr_12345",
  "companies": [
    {
      "id": "company_123",
      "name": "Acme Inc",
      "monthlySpend": 500,
      "plan": "enterprise"
    }
  ],
  "customFields": {
    "plan": "pro",
    "signupSource": "website"
  },
  "subscribedToChangelog": true
}


### Example Response

json
{
  "object": "contact",
  "id": "676f0f6765bdaa7d7d760f88",
  "email": "john@example.com",
  "name": "John Doe",
  "userId": "usr_12345",
  "type": "customer",
  "companies": [...],
  "customFields": {...},
  ...
}


### Version Availability

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

### Get contact by ID

 - [GET /v2/contacts/{id}](https://docs.featurebase.app/rest-api/contacts/getcontactbyid.md): Retrieves a single contact by their Featurebase ID.

Returns both customers and leads.

### Path Parameters

- id - The Featurebase contact ID (24-character ObjectId)

### Response Format

Returns a single contact object with:
- object - Always "contact"
- id - Unique contact identifier
- userId - External user ID from SSO (if set)
- email - Contact email address
- name - Contact display name
- profilePicture - Profile picture URL
- type - Contact type ("customer" or "lead")
- companies - Array of companies the contact belongs to
- customFields - Custom field values
- postsCreated - Number of posts created
- commentsCreated - Number of comments created
- lastActivity - Last activity timestamp

### Example

json
{
  "object": "contact",
  "id": "676f0f6765bdaa7d7d760f88",
  "email": "john@example.com",
  "name": "John Doe",
  "type": "customer",
  ...
}


### Version Availability

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

### Delete contact by ID

 - [DELETE /v2/contacts/{id}](https://docs.featurebase.app/rest-api/contacts/deletecontactbyid.md): Permanently deletes a contact by their Featurebase ID.

Supports deleting both customers and leads.

### Path Parameters

- id - The Featurebase contact ID (24-character ObjectId)

### Deletion Behavior

When a contact is deleted:
- The contact record is permanently removed
- Associated data cleanup is triggered asynchronously
- Comments and posts created by the contact are handled according to retention policies

### Response

Returns a deletion confirmation object:
- id - The ID of the deleted contact
- object - Always "contact"
- deleted - Always true

### Example Response

json
{
  "id": "676f0f6765bdaa7d7d760f88",
  "object": "contact",
  "deleted": true
}


### Version Availability

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

### Get contact by external user ID

 - [GET /v2/contacts/by-user-id/{userId}](https://docs.featurebase.app/rest-api/contacts/getcontactbyuserid.md): Retrieves a single contact by their external user ID (from your system via SSO).

Important: This endpoint only returns customers (type: "customer"). Leads are not returned.

### Path Parameters

- userId - The external user ID from your system (matched via SSO integration)

### Response Format

Returns a single contact object with:
- object - Always "contact"
- id - Unique contact identifier
- userId - External user ID from SSO
- email - Contact email address
- name - Contact display name
- profilePicture - Profile picture URL
- type - Always "customer" for this endpoint
- companies - Array of companies the contact belongs to
- customFields - Custom field values
- postsCreated - Number of posts created
- commentsCreated - Number of comments created
- lastActivity - Last activity timestamp

### Example

json
{
  "object": "contact",
  "id": "676f0f6765bdaa7d7d760f88",
  "userId": "usr_12345",
  "email": "john@example.com",
  "name": "John Doe",
  "type": "customer",
  ...
}


### Use Case

This endpoint is useful when you need to look up a contact using your own system's user identifier, 
such as when displaying Featurebase data alongside your user's information in your own application.

### Version Availability

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

### Delete contact by external user ID

 - [DELETE /v2/contacts/by-user-id/{userId}](https://docs.featurebase.app/rest-api/contacts/deletecontactbyuserid.md): Permanently deletes a contact by their external user ID.

Important: This endpoint only deletes customers (type: "customer"). Leads cannot be deleted using this endpoint.

### Path Parameters

- userId - The external user ID from your system

### Deletion Behavior

When a contact is deleted:
- The contact record is permanently removed
- Associated data cleanup is triggered asynchronously
- Comments and posts created by the contact are handled according to retention policies

### Response

Returns a deletion confirmation object:
- id - The ID of the deleted contact
- object - Always "contact"
- deleted - Always true

### Example Response

json
{
  "id": "676f0f6765bdaa7d7d760f88",
  "object": "contact",
  "deleted": true
}


### Use Case

Use this endpoint when you need to delete a contact using your own system's user identifier,
such as when a user deletes their account in your application.

### Version Availability

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

### Block a contact

 - [POST /v2/contacts/{id}/block](https://docs.featurebase.app/rest-api/contacts/blockcontactbyid.md): Blocks a contact by their Featurebase ID from the messenger/inbox.

### Path Parameters

- id - The Featurebase internal ID of the contact (MongoDB ObjectId)

### Supported Contact Types

This endpoint blocks both:
- Customers - Users with registered accounts
- Leads - Anonymous or unregistered visitors

### Blocking Behavior

When a contact is blocked:
- The contact cannot send new messages via messenger
- Existing conversations are not deleted but no new messages can be added by the blocked user
- The block can be removed by unblocking the contact

### Response

Returns a block confirmation object:
- id - The ID of the blocked contact
- object - Always "contact"
- blocked - Always true

### Example Response

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "contact",
  "blocked": true
}


### Version Availability

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

### Unblock a contact

 - [POST /v2/contacts/{id}/unblock](https://docs.featurebase.app/rest-api/contacts/unblockcontactbyid.md): Unblocks a contact by their Featurebase ID from the messenger/inbox.

### Path Parameters

- id - The Featurebase internal ID of the contact (MongoDB ObjectId)

### Supported Contact Types

This endpoint unblocks both:
- Customers - Users with registered accounts
- Leads - Anonymous or unregistered visitors

### Unblocking Behavior

When a contact is unblocked:
- The contact can resume sending messages via messenger
- Previously blocked conversations remain intact
- The contact regains full messenger functionality

### Response

Returns an unblock confirmation object:
- id - The ID of the unblocked contact
- object - Always "contact"
- unblocked - Always true

### Example Response

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "contact",
  "unblocked": true
}


### Version Availability

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

## Companies

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

### List all companies

 - [GET /v2/companies](https://docs.featurebase.app/rest-api/companies/listcompanies.md): Returns all companies in your organization with cursor-based pagination.

### Query Parameters

- limit - Number of companies to return (1-100, default: 10)
- cursor - Opaque cursor from a previous response for pagination

### Response Structure

The response includes:
- object - Always "list"
- data - Array of company objects
- nextCursor - Cursor for the next page (null if no more results)

### Company Object

Each company includes:
- id - Featurebase internal ID (MongoDB ObjectId)
- companyId - External company ID from your system
- name - Company name
- monthlySpend - Monthly spend/revenue
- industry - Industry
- website - Company website URL
- plan - Plan/tier name
- linkedUsers - Number of users linked to this company
- companySize - Employee headcount
- lastActivity - Last activity timestamp
- customFields - Custom field values
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Example Response

json
{
  "object": "list",
  "data": [
    {
      "object": "company",
      "id": "507f1f77bcf86cd799439011",
      "companyId": "comp_12345",
      "name": "Acme Inc",
      "monthlySpend": 5000,
      "industry": "Technology",
      "website": "https://acme.com",
      "plan": "enterprise",
      "linkedUsers": 15,
      "companySize": 250,
      "lastActivity": "2025-01-15T00:00:00.000Z",
      "customFields": { "location": "Europe" },
      "createdAt": "2025-01-01T12:00:00.000Z",
      "updatedAt": "2025-01-10T15:30:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}


### Version Availability

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

### Create or update a company

 - [POST /v2/companies](https://docs.featurebase.app/rest-api/companies/upsertcompany.md): Creates a new company or updates an existing one.

Uses the external companyId as the unique identifier for upsert matching.
If a company with the given companyId already exists, it will be updated.
Otherwise, a new company will be created.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| companyId | string | Yes | External company ID from your system (unique identifier) |
| name | string | Yes | Company name |
| monthlySpend | number | No | Monthly spend/revenue from this company |
| industry | string | No | Industry the company operates in |
| website | string | No | Company website URL |
| plan | string | No | Current plan/subscription name |
| companySize | number | No | Number of employees |
| createdAt | string | No | When the company was created (ISO 8601) |
| customFields | object | No | Custom field values |

### Example Request

json
{
  "companyId": "comp_12345",
  "name": "Acme Inc",
  "monthlySpend": 5000,
  "industry": "Technology",
  "website": "https://acme.com",
  "plan": "enterprise",
  "companySize": 250,
  "customFields": {
    "region": "EMEA",
    "tier": "gold"
  }
}


### Example Response

json
{
  "object": "company",
  "id": "507f1f77bcf86cd799439011",
  "companyId": "comp_12345",
  "name": "Acme Inc",
  "monthlySpend": 5000,
  "industry": "Technology",
  "website": "https://acme.com",
  "plan": "enterprise",
  "linkedUsers": 1,
  "companySize": 250,
  "lastActivity": "2025-01-15T00:00:00.000Z",
  "customFields": { "region": "EMEA", "tier": "gold" },
  "createdAt": "2025-01-01T12:00:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}


### Error Responses

- 400 Bad Request - Invalid company data

### Version Availability

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

### Get company by ID

 - [GET /v2/companies/{id}](https://docs.featurebase.app/rest-api/companies/getcompanybyid.md): Retrieves a single company by its Featurebase ID.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)

### Response

Returns a company object with:
- id - Featurebase internal ID
- companyId - External company ID from your system
- name - Company name
- monthlySpend - Monthly spend/revenue
- industry - Industry
- website - Company website URL
- plan - Plan/tier name
- linkedUsers - Number of users linked to this company
- companySize - Employee headcount
- lastActivity - Last activity timestamp
- customFields - Custom field values
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Example Response

json
{
  "object": "company",
  "id": "507f1f77bcf86cd799439011",
  "companyId": "comp_12345",
  "name": "Acme Inc",
  "monthlySpend": 5000,
  "industry": "Technology",
  "website": "https://acme.com",
  "plan": "enterprise",
  "linkedUsers": 15,
  "companySize": 250,
  "lastActivity": "2025-01-15T00:00:00.000Z",
  "customFields": { "location": "Europe" },
  "createdAt": "2025-01-01T12:00:00.000Z",
  "updatedAt": "2025-01-10T15:30:00.000Z"
}


### Error Responses

- 404 Not Found - Company with the specified ID does not exist

### Version Availability

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

### Delete a company

 - [DELETE /v2/companies/{id}](https://docs.featurebase.app/rest-api/companies/deletecompanybyid.md): Deletes a company by its Featurebase ID.

This will also remove the company from all linked users' associations.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)

### Response

Returns a deletion confirmation object:

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "company",
  "deleted": true
}


### Error Responses

- 404 Not Found - Company with the specified ID does not exist

### Version Availability

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

### List contacts attached to a company

 - [GET /v2/companies/{id}/contacts](https://docs.featurebase.app/rest-api/companies/listcompanycontacts.md): Returns all contacts (customers) attached to a specific company.

Only returns contacts with type "customer" that have the company in their companyIds array.
Uses cursor-based pagination.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)

### Query Parameters

- limit - Number of contacts to return (1-100, default: 10)
- cursor - Opaque cursor from a previous response for pagination

### Response Structure

The response includes:
- object - Always "list"
- data - Array of contact objects
- nextCursor - Cursor for the next page (null if no more results)

### Example Response

json
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "507f1f77bcf86cd799439011",
      "userId": "usr_12345",
      "email": "john@acme.com",
      "name": "John Doe",
      "type": "customer",
      "companies": [...],
      "createdAt": "2025-01-01T12:00:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}


### Error Responses

- 404 Not Found - Company with the specified ID does not exist

### Version Availability

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

### Attach a contact to a company

 - [POST /v2/companies/{id}/contacts](https://docs.featurebase.app/rest-api/companies/attachcontacttocompany.md): Attaches a contact (customer) to a company.

Adds the company to the contact's companyIds array and embedded companies array.
This operation is additive - existing company associations are preserved.
Also increments the linkedUsers count on the company.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| contactId | string | Yes | The Featurebase internal ID of the contact to attach (MongoDB ObjectId) |

### Example Request

json
{
  "contactId": "507f1f77bcf86cd799439012"
}


### Response

Returns the updated contact object with the new company association.

### Example Response

json
{
  "object": "contact",
  "id": "507f1f77bcf86cd799439012",
  "userId": "usr_12345",
  "email": "john@acme.com",
  "name": "John Doe",
  "type": "customer",
  "companies": [
    {
      "object": "company",
      "id": "507f1f77bcf86cd799439011",
      "companyId": "comp_12345",
      "name": "Acme Inc"
    }
  ]
}


### Error Responses

- 404 Not Found - Company or contact does not exist

### Version Availability

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

### Remove a contact from a company

 - [DELETE /v2/companies/{id}/contacts/{contactId}](https://docs.featurebase.app/rest-api/companies/removecontactfromcompany.md): Removes a contact (customer) from a company.

Removes the company from the contact's companyIds array and embedded companies array.
Also decrements the linkedUsers count on the company.

### Path Parameters

- id - The Featurebase internal ID of the company (MongoDB ObjectId)
- contactId - The Featurebase internal ID of the contact to remove (MongoDB ObjectId)

### Response

Returns the updated contact object with the company removed.

### Example Response

json
{
  "object": "contact",
  "id": "507f1f77bcf86cd799439012",
  "userId": "usr_12345",
  "email": "john@acme.com",
  "name": "John Doe",
  "type": "customer",
  "companies": []
}


### Error Responses

- 400 Bad Request - Contact is not attached to this company
- 404 Not Found - Company or contact does not exist

### Version Availability

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

## 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.

### List surveys

 - [GET /v2/surveys](https://docs.featurebase.app/rest-api/surveys/listsurveys.md): Returns all surveys configured in your Featurebase organization.

### Query Parameters

- limit - Number of items to return (1-100, default 10)
- cursor - Cursor for pagination
- type - Filter by survey page type (text, link, rating, multiple-choice)
- isActive - Filter by active status

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of survey objects
- nextCursor - Cursor for next page (null if no more results)

### Survey Object

Each survey includes:
- id - Unique identifier
- title - Survey title
- description - Survey description
- isActive - Whether the survey is active
- responseCount - Number of responses received
- targeting - Targeting configuration (segments, URLs, CSS selectors)
- pages - Array of survey pages/questions
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Get a survey by ID

 - [GET /v2/surveys/{id}](https://docs.featurebase.app/rest-api/surveys/getsurvey.md): Retrieves a single survey by its unique identifier.

Returns the survey object if found in your organization.

### Response

Returns a survey object with:
- id - Unique identifier
- title - Survey title
- description - Survey description
- isActive - Whether the survey is active
- responseCount - Number of responses received
- targeting - Targeting configuration
- pages - Array of survey pages/questions
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Survey Pages

Each page represents a question or screen in the survey:
- type - Page type (text, link, rating, multiple-choice)
- title - Question title
- description - Optional description
- logic - Conditional logic rules
- defaultAction - Default action when no logic matches

### Errors

- 404 - Survey not found in your organization

### Get survey responses

 - [GET /v2/surveys/{id}/responses](https://docs.featurebase.app/rest-api/surveys/getsurveyresponses.md): Retrieves all user responses for a specific survey.

### Query Parameters

- pageId - Filter responses to a specific survey page
- limit - Number of items to return (1-100, default 10)
- cursor - Cursor for pagination

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of survey response objects
- nextCursor - Cursor for next page (null if no more results)

### Survey Response Object

Each response includes:
- id - Unique response identifier
- user - User who submitted the response (may be null for anonymous)
- responses - Array of individual answers
- createdAt - ISO 8601 timestamp when submitted

### Individual Response

Each item in the responses array:
- pageId - The survey page this response is for
- type - Response type (text, rating, multiple-choice)
- value - The response value

### Errors

- 404 - Survey not found in your organization

## Help Centers

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

### List help centers

 - [GET /v2/help_center/help_centers](https://docs.featurebase.app/rest-api/help-centers/listhelpcenters.md): Returns all help centers configured in your Featurebase organization.

Currently, Featurebase only supports one help center per organization, but we plan on supporting multiple help centers in the future.

### Query Parameters

- limit - Number of items to return (1-100, default 10)
- cursor - Cursor for pagination

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of help center objects
- nextCursor - Cursor for next page (null if no more results)

### Help Center Object

Each help center includes:
- id - Unique identifier
- displayName - Help center display name
- title - Help center title
- description - Help center description
- isPublic - Whether the help center is publicly accessible
- defaultLocale - Default locale for content
- availableLocales - Array of available locales
- navItems - Navigation items configuration
- urls - URL configuration (subpath, custom domain)
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Get a help center by ID

 - [GET /v2/help_center/help_centers/{id}](https://docs.featurebase.app/rest-api/help-centers/gethelpcenter.md): Retrieves a single help center by its unique identifier.

Returns the help center object if found in your organization.

### Response

Returns a help center object with:
- id - Unique identifier
- displayName - Help center display name
- title - Help center title
- description - Help center description
- searchPlaceholder - Search input placeholder text
- isPublic - Whether the help center is publicly accessible
- defaultLocale - Default locale for content
- locale - Current locale
- availableLocales - Array of available locales
- navItems - Navigation items configuration
- urls - URL configuration (subpath, custom domain)
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Errors

- 404 - Help center not found in your organization

### List collections

 - [GET /v2/help_center/collections](https://docs.featurebase.app/rest-api/help-centers/listcollections.md): Returns a paginated list of collections within your organization's help center.

Collections are used to organize articles into logical groups.

### Query Parameters

- limit - Number of items to return (1-100, default 10)
- cursor - Cursor for pagination

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of collection objects
- nextCursor - Cursor for next page (null if no more results)

### Collection Object

Each collection includes:
- id - Unique identifier
- name - Collection name
- description - Collection description
- slug - URL slug
- icon - Collection icon (emoji or custom)
- parentId - Parent collection ID (null for root collections)
- helpCenterId - ID of the help center this collection belongs to
- organization - Organization ID
- defaultLocale - Default locale for content
- locale - Current locale
- availableLocales - Array of available locales
- featurebaseUrl - Featurebase URL for the collection
- externalUrl - External URL if custom domain is configured
- articleCount - Number of articles in this collection
- authorCount - Number of authors who contributed
- order - Display order
- translations - Translations for different locales
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Create a collection

 - [POST /v2/help_center/collections](https://docs.featurebase.app/rest-api/help-centers/createcollection.md): Creates a new collection in your organization's help center.

### Request Body

Required attributes:
- name - The name of the collection

Optional attributes:
- description - A description of the collection
- icon - An icon object representing the collection icon (with type and value)
- parentId - The ID of the parent collection, if any
- translations - A dictionary of translations keyed by locale

### Response

Returns the created collection object with:
- id - Unique identifier
- name - Collection name
- description - Collection description
- slug - URL slug
- icon - Collection icon (emoji or custom)
- parentId - Parent collection ID (null for root collections)
- helpCenterId - ID of the help center this collection belongs to
- organization - Organization ID
- defaultLocale - Default locale for content
- locale - Current locale
- availableLocales - Array of available locales
- featurebaseUrl - Featurebase URL for the collection
- externalUrl - External URL if custom domain is configured
- articleCount - Number of articles in this collection
- authorCount - Number of authors who contributed
- order - Display order
- translations - Translations for different locales
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Get a collection by ID

 - [GET /v2/help_center/collections/{id}](https://docs.featurebase.app/rest-api/help-centers/getcollection.md): Retrieves a specific collection by its unique identifier.

Returns the collection object if found in your organization's help center.

### Response

Returns a collection object with:
- id - Unique identifier
- name - Collection name
- description - Collection description
- slug - URL slug
- icon - Collection icon (emoji or custom)
- parentId - Parent collection ID (null for root collections)
- helpCenterId - ID of the help center this collection belongs to
- organization - Organization ID
- defaultLocale - Default locale for content
- locale - Current locale
- availableLocales - Array of available locales
- featurebaseUrl - Featurebase URL for the collection
- externalUrl - External URL if custom domain is configured
- articleCount - Number of articles in this collection
- authorCount - Number of authors who contributed
- order - Display order
- translations - Translations for different locales
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Errors

- 404 - Collection not found in your organization's help center

### Update a collection

 - [PATCH /v2/help_center/collections/{id}](https://docs.featurebase.app/rest-api/help-centers/updatecollection.md): Updates an existing collection. Only include the fields you wish to update.

### Path Parameters

- id - The unique identifier of the collection to update

### Request Body

All fields are optional. Only provided fields will be updated:
- name - The new name of the collection
- description - The new description of the collection
- icon - An updated icon object for the collection (with type and value)
- parentId - The new parent collection ID, if applicable (null for root level)
- translations - A dictionary of updated translations keyed by locale code

### Response

Returns the updated collection object with:
- id - Unique identifier
- name - Collection name
- description - Collection description
- slug - URL slug
- icon - Collection icon (emoji or custom)
- parentId - Parent collection ID (null for root collections)
- helpCenterId - ID of the help center this collection belongs to
- organization - Organization ID
- defaultLocale - Default locale for content
- locale - Current locale
- availableLocales - Array of available locales
- featurebaseUrl - Featurebase URL for the collection
- externalUrl - External URL if custom domain is configured
- articleCount - Number of articles in this collection
- authorCount - Number of authors who contributed
- order - Display order
- translations - Translations for different locales
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Errors

- 404 - Collection not found in your organization's help center

### Delete a collection

 - [DELETE /v2/help_center/collections/{id}](https://docs.featurebase.app/rest-api/help-centers/deletecollection.md): Deletes an existing collection.

### Path Parameters

- id - The unique identifier of the collection to delete

### Response

Returns a deletion confirmation object:
- id - The ID of the deleted collection
- object - Always "collection"
- deleted - Always true

### Errors

- 404 - Collection not found in your organization's help center

### List articles

 - [GET /v2/help_center/articles](https://docs.featurebase.app/rest-api/help-centers/listarticles.md): Returns a paginated list of articles within your organization's help center.

Articles are the main content pieces that contain documentation, guides, and FAQs.

### Query Parameters

- limit - Number of items to return (1-100, default 10)
- cursor - Cursor for pagination
- state - Filter by article state: "live", "draft", or "all" (default "live")
- parentId - Filter by parent collection ID

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of article objects
- nextCursor - Cursor for next page (null if no more results)

### Article Object

Each article includes:
- id - Unique identifier
- title - Article title
- description - Article description
- body - Article content (HTML)
- slug - URL slug
- icon - Article icon (emoji or custom)
- parentId - Parent collection ID
- helpCenterId - ID of the help center this article belongs to
- organization - Organization ID
- state - Article state (live or draft)
- defaultLocale - Default locale for content
- locale - Current locale
- availableLocales - Array of available locales
- publishedLocales - Array of locales where article is published
- featurebaseUrl - Featurebase URL for the article
- externalUrl - External URL if custom domain is configured
- author - Author information (name, authorId, avatarUrl)
- order - Display order
- isPublished - Whether the article is published
- isDraftDiffersFromLive - Whether draft differs from live version
- translations - Translations for different locales
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated
- liveUpdatedAt - ISO 8601 timestamp when live version was last updated

### Create an article

 - [POST /v2/help_center/articles](https://docs.featurebase.app/rest-api/help-centers/createarticle.md): Creates a new article in your organization's help center.

### Request Body

Required attributes:
- title - The title of the article

Optional attributes:
- description - A brief description of the article
- body - The HTML content of the article (supports external image URLs and base64 data URIs)
- formatter - Content formatter: "default" or "ai" (AI converts markdown/html to Featurebase format)
- parentId - The ID of the parent collection
- icon - Icon object with type and value
- state - "live" or "draft" (defaults to "draft")
- translations - Dictionary of translations keyed by locale

### Response

Returns the created article object with:
- id - Unique identifier
- title - Article title
- description - Article description
- body - Article content (HTML)
- slug - URL slug
- icon - Article icon (emoji or custom)
- parentId - Parent collection ID
- helpCenterId - ID of the help center this article belongs to
- organization - Organization ID
- state - Article state (live or draft)
- author - Author information (name, authorId, avatarUrl)
- translations - Translations for different locales
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Get an article by ID

 - [GET /v2/help_center/articles/{id}](https://docs.featurebase.app/rest-api/help-centers/getarticle.md): Retrieves a specific article by its unique identifier.

Returns the article object if found in your organization's help center.

### Query Parameters

- state - Article state to retrieve: "live" or "draft" (default "live")

### Response

Returns an article object with:
- id - Unique identifier
- title - Article title
- description - Article description
- body - Article content (HTML)
- slug - URL slug
- icon - Article icon (emoji or custom)
- parentId - Parent collection ID
- helpCenterId - ID of the help center this article belongs to
- organization - Organization ID
- state - Article state (live or draft)
- defaultLocale - Default locale for content
- locale - Current locale
- availableLocales - Array of available locales
- publishedLocales - Array of locales where article is published
- featurebaseUrl - Featurebase URL for the article
- externalUrl - External URL if custom domain is configured
- author - Author information (name, authorId, avatarUrl)
- order - Display order
- isPublished - Whether the article is published
- isDraftDiffersFromLive - Whether draft differs from live version
- translations - Translations for different locales
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated
- liveUpdatedAt - ISO 8601 timestamp when live version was last updated

### Errors

- 404 - Article not found in your organization's help center

### Update an article

 - [PATCH /v2/help_center/articles/{id}](https://docs.featurebase.app/rest-api/help-centers/updatearticle.md): Updates an existing article. Only include the fields you wish to update.

### Path Parameters

- id - The unique identifier of the article to update

### Request Body

All fields are optional. Only provided fields will be updated:
- title - The new title of the article
- description - The new description of the article
- body - The new HTML content of the article
- formatter - Content formatter: "default" or "ai"
- icon - Updated icon object for the article
- parentId - New parent collection ID
- authorId - ID of the new author (must be a member of the organization)
- state - "live" or "draft" - if "live", publishes immediately
- translations - Dictionary of updated translations keyed by locale

### Response

Returns the updated article object with:
- id - Unique identifier
- title - Article title
- description - Article description
- body - Article content (HTML)
- slug - URL slug
- icon - Article icon (emoji or custom)
- parentId - Parent collection ID
- helpCenterId - ID of the help center this article belongs to
- organization - Organization ID
- state - Article state (live or draft)
- author - Author information (name, authorId, avatarUrl)
- translations - Translations for different locales
- createdAt - ISO 8601 timestamp when created
- updatedAt - ISO 8601 timestamp when last updated

### Errors

- 404 - Article not found in your organization's help center

### Delete an article

 - [DELETE /v2/help_center/articles/{id}](https://docs.featurebase.app/rest-api/help-centers/deletearticle.md): Deletes an existing article.

### Path Parameters

- id - The unique identifier of the article to delete

### Response

Returns a deletion confirmation object:
- id - The ID of the deleted article
- object - Always "article"
- deleted - Always true

### Errors

- 404 - Article not found in your organization's help center

## Conversations

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

### List conversations

 - [GET /v2/conversations](https://docs.featurebase.app/rest-api/conversations/listconversations.md): Returns a list of conversations in your organization using cursor-based pagination.

### Query Parameters

- limit - Number of conversations to return (1-100, default 10)
- cursor - Cursor from previous response for pagination

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of conversation objects
- nextCursor - Cursor for the next page, or null if no more results

### Conversation Object

Each conversation includes:
- id - Unique conversation identifier (short ID)
- title - Conversation title
- state - Current state ("open", "closed", or "snoozed")
- priority - Whether the conversation is marked as priority
- adminAssigneeId - ID of assigned admin (if any)
- teamAssigneeId - ID of assigned team (if any)
- participants - Array of participants
- source - Information about the first message
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Example

json
{
  "object": "list",
  "data": [
    {
      "object": "conversation",
      "id": "12345",
      "title": "Question about pricing",
      "state": "open",
      "priority": false,
      "adminAssigneeId": null,
      "participants": [
        { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
      ],
      ...
    }
  ],
  "nextCursor": "eyJpZCI6IjEyMzQ1In0="
}


### Version Availability

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

### Create a conversation

 - [POST /v2/conversations](https://docs.featurebase.app/rest-api/conversations/createconversation.md): Creates a new conversation. Supports both contact-initiated (customer/lead) and admin-initiated (outreach) conversations.

## Contact-Initiated Conversation

For conversations started by a customer or lead:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| from.type | string | Yes | Must be "contact" |
| from.id | string | Yes | The Featurebase contact ID (24-character ObjectId) |
| bodyMarkdown | string | Yes | The initial message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |
| channel | string | No | The channel: "desktop" (default) or "email" |
| createdAt | string | No | ISO timestamp for migrations |

### Example Contact-Initiated Request

json
{
  "from": {
    "type": "contact",
    "id": "676f0f6765bdaa7d7d760f88"
  },
  "bodyMarkdown": "Hello, I have a question about your product.",
  "channel": "desktop"
}


## Admin-Initiated Outreach

For outreach conversations started by an admin:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| from.type | string | Yes | Must be "admin" |
| from.id | string | Yes | The Featurebase admin ID (24-character ObjectId) |
| bodyMarkdown | string | Yes | The initial message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |
| channel | string | No | The channel: "desktop" (default) or "email" |
| recipients | object | Yes | Recipients for the outreach |
| recipients.to | object | Yes | Primary recipients |
| recipients.to.emails | string[] | No* | Email addresses |
| recipients.to.ids | string[] | No* | Featurebase contact IDs |
| recipients.cc | object | No | CC recipients (same structure as "to") |
| recipients.bcc | object | No | BCC recipients (same structure as "to") |
| subject | string | No | Email subject line |
| createdAt | string | No | ISO timestamp for migrations |

*At least one email or ID is required in recipients.to
Required when channel is "email"

### Example Admin Outreach (In-App)

json
{
  "from": {
    "type": "admin",
    "id": "507f1f77bcf86cd799439011"
  },
  "bodyMarkdown": "Hi! Just following up on your inquiry.",
  "channel": "desktop",
  "recipients": {
    "to": {
      "ids": ["676f0f6765bdaa7d7d760f88"]
    }
  }
}


### Example Admin Outreach (Email)

json
{
  "from": {
    "type": "admin",
    "id": "507f1f77bcf86cd799439011"
  },
  "bodyMarkdown": "Hi! Just following up on your inquiry.",
  "channel": "email",
  "subject": "Following up on your inquiry",
  "recipients": {
    "to": {
      "emails": ["john@example.com"]
    },
    "cc": {
      "emails": ["manager@example.com"]
    }
  }
}


### Response

Returns the created conversation object with a 201 Created status.

### Example Response

json
{
  "object": "conversation",
  "id": "12345",
  "state": "open",
  "priority": false,
  "adminAssigneeId": null,
  "participants": [
    { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
  ],
  "source": {
    "channel": "desktop",
    "deliveredAs": "customer_initiated",
    "bodyHtml": "Hello, I have a question about your product.",
    "bodyMarkdown": "Hello, I have a question about your product.",
    "author": { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}


### Version Availability

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

### Get conversation by ID

 - [GET /v2/conversations/{id}](https://docs.featurebase.app/rest-api/conversations/getconversationbyid.md): Retrieves a single conversation by its ID, including conversation parts (messages).

### Path Parameters

- id - The conversation ID (short ID)

### Hard Limit of 500 Parts

The maximum number of conversation parts that can be returned via the API is 500.
If a conversation has more than 500 parts, only the 500 most recent conversation parts will be returned.

### Response Format

Returns a single conversation object with:
- object - Always "conversation"
- id - Unique conversation identifier (short ID)
- title - Conversation title
- state - Current state ("open", "closed", or "snoozed")
- priority - Whether the conversation is marked as priority
- adminAssigneeId - ID of assigned admin (if any)
- teamAssigneeId - ID of assigned team (if any)
- participants - Array of participants
- source - Information about the first message
- conversationParts - Array of conversation parts (messages, max 500)
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Conversation Parts

Each conversation part includes:
- object - Always "conversation_part"
- id - Unique part identifier
- partType - Type of part (e.g., "user_msg", "admin_msg", "bot_msg")
- body - Message body (HTML content)
- author - Author information with name, email, and profile picture
- channel - Channel through which the message was sent
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Example

json
{
  "object": "conversation",
  "id": "12345",
  "title": "Question about pricing",
  "state": "open",
  "priority": false,
  "adminAssigneeId": "507f1f77bcf86cd799439011",
  "participants": [
    { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
  ],
  "conversationParts": [
    {
      "object": "conversation_part",
      "id": "1",
      "partType": "user_msg",
      "bodyHtml": "Hello, I have a question about your pricing plans.",
      "bodyMarkdown": "Hello, I have a question about your pricing plans.",
      "author": {
        "type": "customer",
        "id": "676f0f6765bdaa7d7d760f88",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "channel": "desktop",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "object": "conversation_part",
      "id": "2",
      "partType": "admin_msg",
      "bodyHtml": "Hi John! I'd be happy to help you with pricing information.",
      "bodyMarkdown": "Hi John! I'd be happy to help you with pricing information.",
      "author": {
        "type": "admin",
        "id": "507f1f77bcf86cd799439011",
        "name": "Support Agent"
      },
      "channel": "desktop",
      "createdAt": "2025-01-15T10:35:00.000Z",
      "updatedAt": "2025-01-15T10:35:00.000Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:35:00.000Z"
}


### Version Availability

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

### Delete a conversation

 - [DELETE /v2/conversations/{id}](https://docs.featurebase.app/rest-api/conversations/deleteconversation.md): Permanently deletes a conversation by its short ID.

### Path Parameters

- id - The conversation short ID (numeric)

### Response

Returns a deletion confirmation object:

json
{
  "id": "12345",
  "object": "conversation",
  "deleted": true
}


### Caution

This operation is irreversible. The conversation and all its messages will be permanently deleted.

### Version Availability

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

### Update a conversation

 - [PATCH /v2/conversations/{id}](https://docs.featurebase.app/rest-api/conversations/updateconversation.md): Updates a conversation's properties. Supports partial updates - only provided fields will be updated.

### Path Parameters

- id - The conversation ID (short ID)

### Request Body

All fields are optional. Only provided fields will be updated.

| Field | Type | Description |
|-------|------|-------------|
| actingAdminId | string | Admin ID performing the action (for attribution). If not provided, uses bot service user. Must be a member of the organization. |
| state | string | Conversation state: "open", "closed", or "snoozed" |
| snoozedUntil | string | ISO datetime when to unsnooze (required when state is "snoozed") |
| adminAssigneeId | string/null | Admin ID to assign, or null to unassign |
| teamAssigneeId | string/null | Team ID to assign, or null to unassign |
| title | string | Conversation title |
| customAttributes | object | Custom attributes to set on the conversation |
| markAsRead | object | Mark conversation as read for specific users |

### markAsRead Object

| Field | Type | Description |
|-------|------|-------------|
| allAdmins | boolean | If true, marks all admins with existing readReceipts as read |
| adminIds | string[] | Array of specific admin IDs to mark as read |
| allContacts | boolean | If true, marks all contacts with existing readReceipts as read |
| contactIds | string[] | Array of specific contact IDs to mark as read |

Note: Only users with existing read receipts will be updated. Use allAdmins/allContacts OR adminIds/contactIds - the "all" flags take precedence.

### Response

Returns the updated conversation object.

### Example: Close a Conversation (with attribution)

json
{
  "actingAdminId": "507f1f77bcf86cd799439011",
  "state": "closed"
}


### Example: Close a Conversation (bot user)

json
{
  "state": "closed"
}


### Example: Snooze a Conversation

json
{
  "state": "snoozed",
  "snoozedUntil": "2025-01-20T10:00:00.000Z"
}


### Example: Assign to an Admin

json
{
  "adminAssigneeId": "507f1f77bcf86cd799439011"
}


### Example: Update Title and Custom Attributes

json
{
  "title": "Billing Issue - Priority",
  "customAttributes": {
    "priority_level": "high",
    "category": "billing"
  }
}


### Example: Mark as Read (All Admins)

json
{
  "markAsRead": {
    "allAdmins": true
  }
}


### Example: Mark as Read (All Contacts)

json
{
  "markAsRead": {
    "allContacts": true
  }
}


### Example: Mark as Read (Specific IDs)

json
{
  "markAsRead": {
    "adminIds": ["507f1f77bcf86cd799439011"],
    "contactIds": ["676f0f6765bdaa7d7d760f88"]
  }
}


### Version Availability

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

### Reply to a conversation

 - [POST /v2/conversations/{id}/reply](https://docs.featurebase.app/rest-api/conversations/replytoconversation.md): 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" |

*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 |

### 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

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


### Example Admin Reply

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


### Example Admin Note (Internal)

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


### Example Response

json
{
  "object": "conversation_part",
  "id": "3",
  "partType": "user_msg",
  "bodyHtml": "Thank you for your help!",
  "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.

### Add a contact to a conversation

 - [POST /v2/conversations/{id}/participants](https://docs.featurebase.app/rest-api/conversations/addparticipanttoconversation.md): Adds a contact (customer or lead) as a participant to an existing conversation.

### Path Parameters

- id - The conversation ID (short ID)

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| participant | object | Yes | The contact to add (see below) |
| participant.id | string | No* | The Featurebase ID (24-character ObjectId) - matches customer or lead |
| participant.userId | string | No* | External user ID from your system - matches customer only |
| participant.email | string | No* | Email address - matches customer only |
| actingAdminId | string | No | Admin ID performing the action (for attribution) |

*At least one of id, userId, or email is required in the participant object.

### Lookup Priority

1. If id is provided, looks up by Featurebase ID (matches both customer and lead types)
2. If userId is provided, looks up by external user ID (matches customer type only)
3. If email is provided, looks up by email address (matches customer type only)

### Response

Returns the updated conversation object.

### Example Request (by Featurebase ID)

json
{
  "participant": {
    "id": "676f0f6765bdaa7d7d760f88"
  },
  "actingAdminId": "507f1f77bcf86cd799439011"
}


### Example Request (by external userId)

json
{
  "participant": {
    "userId": "user_123"
  }
}


### Example Request (by email)

json
{
  "participant": {
    "email": "john@example.com"
  }
}


### Example Response

json
{
  "object": "conversation",
  "id": "12345",
  "participants": [
    { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" },
    { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" }
  ],
  ...
}


### Version Availability

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

### Remove a contact from a conversation

 - [DELETE /v2/conversations/{id}/participants](https://docs.featurebase.app/rest-api/conversations/removeparticipantfromconversation.md): Removes a contact (customer or lead) from an existing conversation.

Note: You cannot remove the last participant from a conversation.

### Path Parameters

- id - The conversation ID (short ID)

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | The Featurebase ID of the contact to remove (24-character ObjectId) |
| actingAdminId | string | No | Admin ID performing the action (for attribution) |

### Response

Returns the updated conversation object.

### Example Request

json
{
  "id": "676f0f6765bdaa7d7d760f88",
  "actingAdminId": "507f1f77bcf86cd799439011"
}


### Example Response

json
{
  "object": "conversation",
  "id": "12345",
  "participants": [
    { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" }
  ],
  ...
}


### Error Cases

- 400 Bad Request - Cannot remove the last participant from a conversation
- 404 Not Found - Conversation or contact not found in participants

### Version Availability

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

### Redact a conversation part

 - [POST /v2/conversations/redact](https://docs.featurebase.app/rest-api/conversations/redactconversationpart.md): Redacts a conversation part (message) from a conversation. Redaction permanently removes the message content while preserving the conversation structure.

Only human message types can be redacted:
- user_msg - Messages from customers/leads
- admin_msg - Messages from admins
- email_msg - Email messages
- bot_msg - Bot messages

System-generated conversation parts (assignments, status changes, etc.) cannot be redacted.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| type | string | Yes | The type of item to redact. Currently only "conversation_part" is supported. |
| conversationId | string | Yes | The conversation short ID containing the part to redact |
| conversationPartId | string | Yes | The conversation part short ID to redact |
| actingAdminId | string | No | Admin ID performing the action (for attribution) |

### Response

Returns the updated conversation object.

### Example Request

json
{
  "type": "conversation_part",
  "conversationId": "12345",
  "conversationPartId": "67890",
  "actingAdminId": "507f1f77bcf86cd799439011"
}


### Example Response

json
{
  "object": "conversation",
  "id": "12345",
  "conversationParts": [
    {
      "object": "conversation_part",
      "id": "67890",
      "partType": "user_msg",
      "bodyHtml": "",
      "bodyMarkdown": "",
      "redacted": true,
      ...
    }
  ],
  ...
}


### Error Cases

- 400 Bad Request - Only human messages can be redacted
- 404 Not Found - Conversation or conversation part not found

### Version Availability

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

## 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.

### List webhooks

 - [GET /v2/webhooks](https://docs.featurebase.app/rest-api/webhooks/listwebhooks.md): Returns a list of webhooks in your organization using cursor-based pagination.

### Query Parameters

- limit - Number of webhooks to return (1-100, default 10)
- cursor - Cursor from previous response for pagination
- status - Filter by status: "active", "paused", or "suspended"

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of webhook objects
- nextCursor - Cursor for the next page, or null if no more results

### Webhook Object

Each webhook includes:
- id - Unique webhook identifier
- name - Human-readable webhook name
- url - Webhook endpoint URL
- topics - Array of subscribed event topics
- status - Current status ("active", "paused", "suspended")
- health - Health metrics (response times, error counts)
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Example

json
{
  "object": "list",
  "data": [
    {
      "object": "webhook",
      "id": "507f1f77bcf86cd799439011",
      "name": "Production Webhook",
      "url": "https://example.com/webhooks",
      "topics": ["post.created", "post.updated"],
      "status": "active",
      ...
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}


### Version Availability

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

### Create a webhook

 - [POST /v2/webhooks](https://docs.featurebase.app/rest-api/webhooks/createwebhook.md): Creates a new webhook to receive event notifications.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | Human-readable name (max 100 chars) |
| url | string | Yes | Webhook endpoint URL (must be HTTPS) |
| description | string | No | Optional description (max 500 chars) |
| topics | string[] | Yes | Event topics to subscribe to |
| requestConfig | object | No | Request configuration |
| requestConfig.headers | object | No | Custom headers to send (max 10) |

### Available Topics

- post.created - When a new post is created
- post.updated - When a post is updated
- post.deleted - When a post is deleted
- post.voted - When a post receives a vote
- changelog.published - When a changelog is published
- comment.created - When a comment is created
- comment.updated - When a comment is updated
- comment.deleted - When a comment is deleted

### Response

Returns the created webhook object including the signing secret.

### Example Request

json
{
  "name": "Production Webhook",
  "url": "https://example.com/webhooks",
  "description": "Handles all production events",
  "topics": ["post.created", "post.updated", "comment.created"],
  "requestConfig": {
    "timeoutMs": 10000,
    "headers": {
      "X-Custom-Header": "value"
    }
  }
}


### Example Response

json
{
  "object": "webhook",
  "id": "507f1f77bcf86cd799439011",
  "name": "Production Webhook",
  "url": "https://example.com/webhooks",
  "secret": "whsec_abc123def456ghi789",
  "topics": ["post.created", "post.updated", "comment.created"],
  "status": "active",
  ...
}


### Limits

Each organization has a maximum number of webhooks (default: 10). Creating a webhook when the limit is reached will return a 400 error.

### Version Availability

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

### Get webhook by ID

 - [GET /v2/webhooks/{id}](https://docs.featurebase.app/rest-api/webhooks/getwebhookbyid.md): Retrieves a single webhook by its unique identifier.

### Path Parameters

- id - The webhook ID (24-character ObjectId)

### Response Format

Returns a webhook object with:
- object - Always "webhook"
- id - Unique webhook identifier
- name - Human-readable webhook name
- url - Webhook endpoint URL
- description - Optional description
- topics - Array of subscribed event topics
- status - Current status ("active", "paused", "suspended")
- requestConfig - Request configuration (timeout, headers)
- lastStatus - Last delivery attempt status
- health - Health metrics
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

The response includes the webhook signing secret for payload verification.

### Example

json
{
  "object": "webhook",
  "id": "507f1f77bcf86cd799439011",
  "name": "Production Webhook",
  "url": "https://example.com/webhooks",
  "description": "Handles all production events",
  "topics": ["post.created", "post.updated"],
  "status": "active",
  "requestConfig": {
    "timeoutMs": 5000,
    "headers": {}
  },
  "lastStatus": {
    "code": 200,
    "message": "Success",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "health": {
    "lastResponseTime": 150,
    "avgResponseTime": 200,
    "lastSuccessAt": "2025-01-15T10:30:00.000Z",
    "errorsSinceLastSuccess": 0,
    "consecutiveFailures": 0
  },
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}


### Version Availability

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

### Update a webhook

 - [PATCH /v2/webhooks/{id}](https://docs.featurebase.app/rest-api/webhooks/updatewebhook.md): Updates a webhook's properties. Supports partial updates - only provided fields will be updated.

### Path Parameters

- id - The webhook ID (24-character ObjectId)

### Request Body

All fields are optional. Only provided fields will be updated.

| Field | Type | Description |
|-------|------|-------------|
| name | string | Human-readable name (max 100 chars) |
| url | string | Webhook endpoint URL (must be HTTPS) |
| description | string/null | Description (null to clear) |
| topics | string[] | Event topics to subscribe to |
| status | string | "active" to reactivate, "paused" to pause delivery |
| requestConfig | object | Request configuration |
| requestConfig.headers | object | Custom headers to send (max 10) |

### Pausing and Reactivating Webhooks

You can pause a webhook to temporarily stop receiving events:

json
{
  "status": "paused"
}


Webhooks may also be automatically paused or suspended due to delivery failures. To reactivate:

json
{
  "status": "active"
}


Reactivating a webhook resets the health metrics and allows it to receive events again.

### Example: Update Topics

json
{
  "topics": ["post.created", "post.updated", "post.deleted"]
}


### Example: Update Request Config

json
{
  "requestConfig": {
    "headers": {
      "X-Custom-Header": "new-value"
    }
  }
}


### Version Availability

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

### Delete a webhook

 - [DELETE /v2/webhooks/{id}](https://docs.featurebase.app/rest-api/webhooks/deletewebhook.md): Permanently deletes a webhook.

### Path Parameters

- id - The webhook ID (24-character ObjectId)

### Response

Returns a deletion confirmation object:

json
{
  "id": "507f1f77bcf86cd799439011",
  "object": "webhook",
  "deleted": true
}


### Caution

This operation is irreversible. The webhook and its configuration will be permanently deleted.
After deletion, no events will be sent to the webhook endpoint.

### Version Availability

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