Skip to content
/Surveys

Featurebase API (2026-01-01.nova)

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.

Download OpenAPI description
index.json
index.yaml
Overview
URL
https://featurebase.app
License
Proprietary
Languages
Servers
Mock server
https://docs.featurebase.app/_mock/rest-api/
Production
https://do.featurebase.app/

API Versioning

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

Specifying a Version

Include the version in the request header:

Featurebase-Version: 2026-01-01.nova

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

Version Compatibility

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

Authentication

All API requests require authentication via API key.

Include in headers:

Authorization: Bearer <api-key>

Create and manage your API keys in the Featurebase dashboard.

Error Handling

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

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

Error Response Format

All errors follow a consistent format:

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

Error Types

TypeDescription
authentication_errorAuthentication failed (401)
authorization_errorPermission denied (403)
invalid_request_errorInvalid request parameters or resource not found (400, 404, 410)
api_errorServer-side error (500)
rate_limit_errorToo many requests (429)

Boards

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

Operations

Posts

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

Operations

Post Statuses

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

Operations

Comments

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

Operations

Custom Fields

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

Operations

Changelogs

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

Operations

Admins

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

Operations

Teams

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

Operations

Contacts

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

Operations

Companies

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

Operations

Surveys

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

Operations

List surveys

Request

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
Security
bearerAuth
Query
limitinteger[ 1 .. 100 ]

A limit on the number of objects to be returned, between 1 and 100.

Default 10
Example: limit=10
cursorstring<= 512 characters

An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page.

Example: cursor=eyJpZCI6IjY3NDM3NTJjYTgxYWU1OWQyNWNmODM0YiJ9
typestring

Filter by survey page type

Enum"text""link""rating""multiple-choice"
Example: type=rating
isActiveboolean or null

Filter by active status

Example: isActive=true
Headers
Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova
curl -i -X GET \
  'https://docs.featurebase.app/_mock/rest-api/v2/surveys?limit=10&cursor=eyJpZCI6IjY3NDM3NTJjYTgxYWU1OWQyNWNmODM0YiJ9&type=rating&isActive=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Featurebase-Version: 2026-01-01.nova'

Responses

Success

Bodyapplication/json
objectstringrequired

Object type identifier

Value"list"
Example: "list"
dataArray of objects(Survey)required

Array of surveys

Example: []
data[].​objectstringrequired

Object type identifier

Value"survey"
Example: "survey"
data[].​idstringrequired

Unique identifier

Example: "6743752ca81ae59d25cf834b"
data[].​titlestringrequired

Survey title

Example: "Get feedback for Feedback module"
data[].​descriptionstring

Survey description

Example: "Measure what we can improve"
data[].​isActivebooleanrequired

Whether the survey is active

Example: true
data[].​organizationstringrequired

Organization ID

Example: "5febde12dc56d60012d47db6"
data[].​responseCountnumberrequired

Number of responses

Example: 85
data[].​targetingobject(SurveyTargeting)

Targeting configuration

data[].​pagesArray of objects(SurveyPage)required

Survey pages

Example: []
data[].​pages[].​idstringrequired

Page ID

Example: "6743752ca81ae59d25cf834c"
data[].​pages[].​typestringrequired

Page type

Enum"text""link""rating""multiple-choice"
Example: "rating"
data[].​pages[].​titlestringrequired

Page title

Example: "How happy are you with our product?"
data[].​pages[].​descriptionstring

Page description

Example: "We really want to hear from you."
data[].​pages[].​placeholderstring

Placeholder for text input

Example: "Type your answer here"
data[].​pages[].​linkButtonTextstring

Button text for link

Example: "Visit our website"
data[].​pages[].​linkRedirectUrlstring

URL to redirect to

Example: "https://example.com"
data[].​pages[].​linkTargetstring

Link target

Enum"_blank""_self""_parent""_top"
Example: "_blank"
data[].​pages[].​subTypestring

Sub-type for rating/multiple-choice

Enum"number""emoji""generic""featurebase-posts""nps"
Example: "emoji"
data[].​pages[].​scalenumber

Rating scale

Example: 5
data[].​pages[].​lowLabelstring

Label for low rating

Example: "Could be improved"
data[].​pages[].​highLabelstring

Label for high rating

Example: "It's awesome!"
data[].​pages[].​allowSelectMultipleboolean

Allow multiple selections

Example: false
data[].​pages[].​choicesArray of objects(SurveyChoice)

Available choices

data[].​pages[].​logicArray of objects(SurveyPageLogic)

Conditional logic rules

data[].​pages[].​defaultActionobject

Action to take if condition matches

data[].​createdAtstringrequired

ISO 8601 timestamp when created

Example: "2024-11-24T18:49:16.755Z"
data[].​updatedAtstringrequired

ISO 8601 timestamp when last updated

Example: "2025-04-10T08:58:51.148Z"
nextCursorstring or nullrequired

Cursor for fetching the next page (cursor-based pagination)

Example: null
Response
application/json
{
  "object": "list",
  "data": [],
  "nextCursor": null
}

Get a survey by ID

Request

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
Security
bearerAuth
Path
idstringrequired

Survey unique identifier

Example: 6743752ca81ae59d25cf834b
Headers
Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova
curl -i -X GET \
  https://docs.featurebase.app/_mock/rest-api/v2/surveys/6743752ca81ae59d25cf834b \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Featurebase-Version: 2026-01-01.nova'

Responses

Success

Bodyapplication/json
objectstringrequired

Object type identifier

Value"survey"
Example: "survey"
idstringrequired

Unique identifier

Example: "6743752ca81ae59d25cf834b"
titlestringrequired

Survey title

Example: "Get feedback for Feedback module"
descriptionstring

Survey description

Example: "Measure what we can improve"
isActivebooleanrequired

Whether the survey is active

Example: true
organizationstringrequired

Organization ID

Example: "5febde12dc56d60012d47db6"
responseCountnumberrequired

Number of responses

Example: 85
targetingobject(SurveyTargeting)

Targeting configuration

pagesArray of objects(SurveyPage)required

Survey pages

Example: []
pages[].​idstringrequired

Page ID

Example: "6743752ca81ae59d25cf834c"
pages[].​typestringrequired

Page type

Enum"text""link""rating""multiple-choice"
Example: "rating"
pages[].​titlestringrequired

Page title

Example: "How happy are you with our product?"
pages[].​descriptionstring

Page description

Example: "We really want to hear from you."
pages[].​placeholderstring

Placeholder for text input

Example: "Type your answer here"
pages[].​linkButtonTextstring

Button text for link

Example: "Visit our website"
pages[].​linkRedirectUrlstring

URL to redirect to

Example: "https://example.com"
pages[].​linkTargetstring

Link target

Enum"_blank""_self""_parent""_top"
Example: "_blank"
pages[].​subTypestring

Sub-type for rating/multiple-choice

Enum"number""emoji""generic""featurebase-posts""nps"
Example: "emoji"
pages[].​scalenumber

Rating scale

Example: 5
pages[].​lowLabelstring

Label for low rating

Example: "Could be improved"
pages[].​highLabelstring

Label for high rating

Example: "It's awesome!"
pages[].​allowSelectMultipleboolean

Allow multiple selections

Example: false
pages[].​choicesArray of objects(SurveyChoice)

Available choices

pages[].​logicArray of objects(SurveyPageLogic)

Conditional logic rules

pages[].​defaultActionobject

Action to take if condition matches

createdAtstringrequired

ISO 8601 timestamp when created

Example: "2024-11-24T18:49:16.755Z"
updatedAtstringrequired

ISO 8601 timestamp when last updated

Example: "2025-04-10T08:58:51.148Z"
Response
application/json
{
  "object": "survey",
  "id": "6743752ca81ae59d25cf834b",
  "title": "Get feedback for Feedback module",
  "description": "Measure what we can improve",
  "isActive": true,
  "organization": "5febde12dc56d60012d47db6",
  "responseCount": 85,
  "targeting": {
    "segmentIds": [ … ],
    "url": [ … ],
    "css": [ … ],
    "loginRequired": false
  },
  "pages": [],
  "createdAt": "2024-11-24T18:49:16.755Z",
  "updatedAt": "2025-04-10T08:58:51.148Z"
}

Get survey responses

Request

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
Security
bearerAuth
Path
idstringrequired

Survey unique identifier

Example: 6743752ca81ae59d25cf834b
Query
pageIdstring

Filter by survey page ID

Example: pageId=6743752ca81ae59d25cf834c
limitinteger[ 1 .. 100 ]

A limit on the number of objects to be returned, between 1 and 100.

Default 10
Example: limit=10
cursorstring<= 512 characters

An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page.

Example: cursor=eyJpZCI6IjY3MTJlMmQxNzU5MDRjZTI0YjJmOTYzNyJ9
Headers
Featurebase-Versionstring(FeaturebaseVersion)

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

Example: 2026-01-01.nova
curl -i -X GET \
  'https://docs.featurebase.app/_mock/rest-api/v2/surveys/6743752ca81ae59d25cf834b/responses?pageId=6743752ca81ae59d25cf834c&limit=10&cursor=eyJpZCI6IjY3MTJlMmQxNzU5MDRjZTI0YjJmOTYzNyJ9' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Featurebase-Version: 2026-01-01.nova'

Responses

Success

Bodyapplication/json
objectstringrequired

Object type identifier

Value"list"
Example: "list"
dataArray of objects(SurveyResponse)required

Array of survey responses

Example: []
data[].​objectstringrequired

Object type identifier

Value"survey_response"
Example: "survey_response"
data[].​idstringrequired

Unique identifier

Example: "6712e2d175904ce24b2f9637"
data[].​userobject or null(Contact)required

User who submitted the response

data[].​user.​objectstringrequired

Object type identifier

Value"contact"
Example: "contact"
data[].​user.​idstringrequired

Unique identifier

Example: "676f0f6765bdaa7d7d760f88"
data[].​user.​userIdstring

External user ID from SSO

Example: "676f0f673dbb299c8a4f3057"
data[].​user.​organizationIdstring

Organization ID the contact belongs to

Example: "5febde12dc56d60012d47db6"
data[].​user.​companiesArray of objects(Company)

Companies the contact belongs to

Example: []
data[].​user.​emailstring or null

Contact email

Example: "john@example.com"
data[].​user.​namestringrequired

Contact display name

Example: "John Steezy"
data[].​user.​profilePicturestring or null

Profile picture URL

Example: "https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png"
data[].​user.​commentsCreatednumber

Number of comments created

Example: 0
data[].​user.​postsCreatednumber

Number of posts created

Example: 0
data[].​user.​lastActivitystring

Last activity ISO timestamp

Example: "2025-01-03T21:42:30.181Z"
data[].​user.​subscribedToChangelogboolean

Whether subscribed to changelog

Example: true
data[].​user.​manuallyOptedOutFromChangelogboolean

Whether manually opted out from changelog

Example: false
data[].​user.​rolesArray of strings

Contact roles

Example: []
data[].​user.​localestring

Contact locale

Example: "en"
data[].​user.​verifiedboolean

Whether email is verified

Example: true
data[].​user.​typestringrequired

Type of contact

Enum"customer""lead"
Example: "customer"
data[].​user.​descriptionstring

Contact description/bio

Example: ""
data[].​user.​customFieldsobject

Custom field values on the contact

data[].​responsesArray of objects(SurveySingleResponse)required

Individual responses to questions

Example: []
data[].​responses[].​pageIdstringrequired

Page ID this response is for

Example: "66dc53c5a64824f0e84a4c1e"
data[].​responses[].​typestringrequired

Response type

Enum"text""link""rating""multiple-choice"
Example: "multiple-choice"
data[].​responses[].​valuestring or number or boolean or Array of stringsrequired

Response value

Example: ["66dc54128b989696d050008b"]
Any of:

Response value

string
data[].​responses[].​idstring

Response ID

Example: "6712e2d175904ce24b2f9638"
data[].​responses[].​createdAtstring

ISO 8601 timestamp when created

Example: "2024-10-18T22:36:01.270Z"
data[].​responses[].​updatedAtstring

ISO 8601 timestamp when updated

Example: "2024-10-18T22:36:01.270Z"
data[].​createdAtstringrequired

ISO 8601 timestamp when created

Example: "2024-10-18T22:36:01.269Z"
nextCursorstring or nullrequired

Cursor for fetching the next page (cursor-based pagination)

Example: null
Response
application/json
{
  "object": "list",
  "data": [],
  "nextCursor": null
}

Help Centers

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

Operations

Conversations

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

Operations

Webhooks

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

Operations