# Table of Contents
- [Featurebase API Reference](#featurebase-api-reference)
- [Authentication - Featurebase API Reference](#authentication-featurebase-api-reference)
- [Pagination - Featurebase API Reference](#pagination-featurebase-api-reference)
- [Quickstart - Featurebase API Reference](#quickstart-featurebase-api-reference)
- [Errors - Featurebase API Reference](#errors-featurebase-api-reference)
- [Webhooks - Featurebase API Reference](#webhooks-featurebase-api-reference)
- [Posts - Featurebase API Reference](#posts-featurebase-api-reference)
- [Comments - Featurebase API Reference](#comments-featurebase-api-reference)
- [Changelogs - Featurebase API Reference](#changelogs-featurebase-api-reference)
- [Roles - Featurebase API Reference](#roles-featurebase-api-reference)
- [Identify Users - Featurebase API Reference](#identify-users-featurebase-api-reference)
- [Help Centers - Featurebase API Reference](#help-centers-featurebase-api-reference)
- [404: This page could not be found](#404-this-page-could-not-be-found)
---
# Featurebase API Reference
API Documentation
=================
Use the Featurebase API to access posts, changelogs, comments, and more and seamlessly integrate Featurebase into your product.
[Quickstart](/quickstart)
[Guides](/#guides)
-------------------
### Authentication
Learn how to authenticate your API requests.
[Read more](/authentication)
### Pagination
Understand how to work with paginated responses.
[Read more](/pagination)
### Errors
Read about the different types of errors returned by the API.
[Read more](/errors)
[Resources](/#resources)
-------------------------
### [Posts](/posts)
Learn about the posts model and how to create, retrieve, update, delete, and list posts.
### [Changelogs](/changelogs)
Learn about the changelog model and how to create, retrieve, update, delete, and list changelogs.
### [Roles](/roles)
Learn about the roles model and how to create, retrieve, update, delete, and list roles.
### [Comments](/comments)
Learn about the comments model and how to create, retrieve, update, delete, and list comments.
---
# Authentication - Featurebase API Reference
Authentication
==============
In this guide, we’ll look at how authentication works. Featurebase let's you authenticate using a special header containing the API Key.
[API Key authentication](/authentication#api-key-authentication)
-----------------------------------------------------------------
With API Key authentication, you send along an "X-API-Key" header with every request you make.
### Example request with api key
curl https://do.featurebase.app/v2/posts \
-H "X-API-Key: {api_key}"
CopyCopied!
Please don't commit your Featurebase API Key to GitHub!
---
# Pagination - Featurebase API Reference
Pagination
==========
In this guide, we will look at how to work with paginated responses when querying the Featurebase API. By default, all responses limit results to ten. However, you can go as high as 100 by adding a `limit` parameter to your requests.
When an API response returns a list of objects, no matter the amount, pagination is supported. In paginated responses, objects are nested in a `results` attribute. You can use the `page` query parameters to browse pages. You will also get access to `totalPages` and `totalResults`, which you can use to build pagination controls in your application.
[Example using pages](/pagination#example-using-pages)
-------------------------------------------------------
In this example, we request the second page of posts.
* Name
`page`
Type
string
Description
The page to return.
* Name
`limit`
Type
integer
Description
Limit the number of items returned.
### Manual pagination using cURL
curl -G https://do.featurebase.app/v2/posts \
-H "X-API-Key: {token}" \
-d page=2 \
-d limit=10
CopyCopied!
### Paginated response
{
"results": [\
{\
"title": "Weekly email to users.",\
...\
{\
...\
},\
...\
],
"page": 2,
"limit": 10,
"totalPages": 18,
"totalResults": 179
}
CopyCopied!
---
# Quickstart - Featurebase API Reference
Quickstart
==========
This guide will get you all set up and ready to use the Featurebase API. We’ll cover how to find your API key and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.
Before you can make requests to the Featurebase API, you will need to grab your API key from your dashboard. You find it under [Settings » Integrations » API](https://auth.featurebase.app/choose-org?redirect=/settings/integrations)
.
[Making your first API request](/quickstart#making-your-first-api-request)
---------------------------------------------------------------------------
After picking your preferred client, you are ready to make your first call to the Featurebase API. Below, you can see how to send a GET request to the Posts endpoint to get a list of all your posts. In the cURL example, results are limited to ten conversations, the default page length for each client.
cURLNode.jsPython
GET
/v2/posts
curl -G https://do.featurebase.app/v2/posts \
-H "X-API-Key: {token}"
CopyCopied!
[Read the docs for the Posts endpoint](/posts)
[What's next?](/quickstart#whats-next)
---------------------------------------
Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the Featurebase API:
* [Grab your API key from the Featurebase dashboard](/quickstart#)
* [Check out the Posts endpoint](/posts)
* [Learn about the different error messages in Featurebase](/errors)
---
# Errors - Featurebase API Reference
Errors
======
In this guide, we will talk about what happens when something goes wrong while you work with the API. Mistakes happen, and mostly they will be yours, not ours. Let's look at some status codes and error types you might encounter.
You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).
Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting Featurebase support.
* * *
[Status codes](/errors#status-codes)
-------------------------------------
Here is a list of the different categories of status codes returned by the Featurebase API. Use these to understand if a request was successful.
* Name
`2xx`
Type
Description
A 2xx status code indicates a successful response.
* Name
`4xx`
Type
Description
A 4xx status code indicates a client error — this means it's a _you_ problem.
* Name
`5xx`
Type
Description
A 5xx status code indicates a server error — you won't be seeing these.
* * *
### Error response
{
"success": false,
"error": "Something went wrong with X!?",
}
CopyCopied!
---
# Webhooks - Featurebase API Reference
Webhooks
========
When using Featurebase, you might want your applications to react instantly as users interact with your portal. With webhooks, your backend systems can receive and act on real-time updates such as new feedback posts.
Featurebase sends event data to your application's webhook endpoint as a JSON payload, using secure HTTPS. This data contains all the essential event details so you can act on it instantly.
[Registering webhooks](/webhooks#registering-webhooks)
-------------------------------------------------------
To register a new webhook, you need to have a URL in your app that Featurebase can call. You can configure a new webhook from the Featurebase Dashboard -> Settings -> [Webhooks](https://auth.featurebase.app/choose-org?redirect=/settings/webhooks)
. Give your webhook a name, pick the [topics](/webhooks#topic-types)
you want to listen for, and add your URL.
Your webhook endpoint must be a publicly accessible HTTPS URL in this format:
https://{your-website}/{your-webhook-endpoint}
CopyCopied!
For example, if your domain is `https://yourawesomesite.com` and your webhook endpoint route is `/featurebase_webhooks`, you would register:
https://yourawesomesite.com/featurebase_webhooks
CopyCopied!
You can register up to 10 webhook endpoints per organization. All endpoints must use HTTPS for security.
Now, whenever something of interest happens, a webhook is fired off by Featurebase. In the next section, we'll look at how to consume webhooks.
[Consuming webhooks](/webhooks#consuming-webhooks)
---------------------------------------------------
When your app receives a webhook request from Featurebase, check the `topic` attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a post, comment, etc.
### Example webhook payload
{
"id": "notif_0193a6e6-fb6b-78ef-b71f-15008d9f9cde",
"topic": "post.updated",
"data": {
"type": "notification_event_data",
"item": {
"id": "6755c4afb12a37dffa6319b0",
"title": "My new title",
// ...
},
"changes": [\
{\
"field": "title",\
"oldValue": "My old title",\
"newValue": "My new title"\
}\
]
}
// ...
}
CopyCopied!
In the example above, a post was `updated`, and the payload type is a `notification_event_data`. Notice how the `changes` array contains the old and new values for the changed fields.
[See all topic types](/webhooks#topic-types)
* * *
[Topic types](/webhooks#topic-types)
-------------------------------------
* Name
`post.created`
Type
Description
A new post was created.
* Name
`post.updated`
Type
Description
An existing post was updated.
* Name
`post.deleted`
Type
Description
A post was successfully deleted.
* Name
`post.voted`
Type
Description
A post received a vote.
* Name
`changelog.published`
Type
Description
A new changelog entry was published.
* Name
`comment.created`
Type
Description
A new comment was created.
* Name
`comment.updated`
Type
Description
An existing comment was updated.
* Name
`comment.deleted`
Type
Description
A comment was successfully deleted.
### Example payload
{
"type": "notification_event",
"topic": "post.updated",
"organizationId": "6595518396205e06b897ad65",
"data": {
"type": "notification_event_data",
"item": {
"id": "67546dfb6e1363426b90707f",
"type": "post",
"title": "New title",
"content": "
",
"user": {
"id": "5fef50c5e9458a0012f82456",
"email": "admin@example.com",
"name": "Admin",
"profilePicture": "https://example.com/profile.jpg",
"verified": true,
"type": "admin",
"description": ""
},
"isPrivate": false,
"score": 1,
"upvotes": 1,
"downvotes": 0,
"inReview": false,
"pinned": false,
"emailSent": false,
"sendNotification": true,
"createdAt": "2024-12-08T17:28:02.468Z",
"updatedAt": "2024-12-08T17:28:02.468Z",
"organization": "6595518396205e06b897ad65",
"submission": "67530bae0c2341f39d2c5847",
"path": "67530bae0c2341f39d2c5847"
}
},
"id": "notif_0193a750-5fc9-7739-8714-758bff6e62c6",
"webhookId": "675346db13af7340748ce850",
"createdAt": "2024-12-08T17:28:02.761Z",
"deliveryStatus": "pending"
}
CopyCopied!
Each webhook event includes:
* `type`: Always "notification\_event"
* `topic`: The specific event type
* `organizationId`: Your organization's unique identifier
* `data`: Contains the event details
* `type`: Always "notification\_event\_data"
* `item`: The resource that triggered the event
* `changes`: For update events, shows what changed
* `id`: Unique identifier for the webhook event
* `webhookId`: ID of the webhook configuration
* `createdAt`: Timestamp when the event occurred
* `deliveryStatus`: Current delivery status of the webhook
The `item` object structure varies based on the event type, but always includes the resource's essential data and any relevant timestamps.
* * *
[Example webhook handlers](/webhooks#example-webhook-handlers)
---------------------------------------------------------------
Here are examples of webhook handlers for different languages.
### Webhook Handler Examples
PythonJavaScriptPHPRubyJavaGoC#
from fastapi import FastAPI, Request, HTTPException
import logging
app = FastAPI()
logger = logging.getLogger(__name__)
async def process_webhook_event(event_data: dict) -> None:
"""Process the webhook event asynchronously."""
try:
topic = event_data.get('topic')
match topic:
case 'post.created':
await handle_post_created(event_data)
case 'post.updated':
await handle_post_updated(event_data)
case _:
logger.warning(f"Unhandled webhook topic: {topic}")
except Exception as e:
logger.error(f"Error processing webhook: {str(e)}", exc_info=True)
@app.post("/webhooks/featurebase")
async def handle_webhook(request: Request):
try:
# Return 200 immediately to acknowledge receipt
background_tasks = request.background
# Get the raw payload
payload = await request.json()
# Verify webhook signature (implemented in security section)
# verify_webhook_signature(request)
# Process webhook asynchronously
background_tasks.add_task(process_webhook_event, payload)
return {"status": "accepted"}
except Exception as e:
logger.error(f"Webhook handler error: {str(e)}", exc_info=True)
raise HTTPException(status_code=500, detail="Internal server error")
CopyCopied!
When implementing webhook handlers, you'll want to:
1. Validate the webhook signature immediately (see security section below)
2. Return a quick 200 OK response to acknowledge receipt
3. Move the actual processing to a background task/job
4. Handle different event types based on the webhook topic
5. Add error handling and logging for debugging issues
Choose the example that matches your tech stack and adapt it to your needs. Remember to implement the webhook signature verification as shown in the [Security](/webhooks#security)
section.
* * *
[Security](/webhooks#security)
-------------------------------
To verify webhook authenticity, each request includes these security headers:
* `X-Webhook-Signature`: HMAC-SHA256 signature of the request
* `X-Webhook-Timestamp`: Unix timestamp when the request was sent
The signature is generated by combining the timestamp and raw request body with a dot (`.`) separator, then creating an HMAC-SHA256 hash using your webhook secret. Here's how to implement secure verification:
### Verifying webhook signatures
PythonJavaScriptPHPRubyJavaGoC#
import hmac
import hashlib
import time
from fastapi import Request, HTTPException
WEBHOOK_SECRET = "whsec_..." # Load from environment variables
MAX_TIMESTAMP_DIFF = 300 # 5 minutes
async def verify_webhook_signature(request: Request) -> None:
"""Verify the webhook signature or raise HTTPException."""
try:
# Get signature and timestamp
signature = request.headers.get("X-Webhook-Signature")
timestamp = request.headers.get("X-Webhook-Timestamp")
if not signature or not timestamp:
raise HTTPException(401, "Missing signature headers")
# Verify timestamp freshness
timestamp_diff = abs(int(time.time()) - int(timestamp))
if timestamp_diff > MAX_TIMESTAMP_DIFF:
raise HTTPException(401, "Webhook timestamp too old")
# Get raw body
body = await request.body()
# Create signed payload
signed_payload = f"{timestamp}.{body.decode('utf-8')}"
# Calculate expected signature
expected = hmac.new(
WEBHOOK_SECRET.encode('utf-8'),
signed_payload.encode('utf-8'),
hashlib.sha256
).hexdigest()
# Secure comparison
if not hmac.compare_digest(expected, signature):
raise HTTPException(401, "Invalid signature")
except ValueError:
raise HTTPException(401, "Invalid signature format")
# Usage in webhook handler:
@app.post("/webhooks/featurebase")
async def handle_webhook(request: Request):
await verify_webhook_signature(request)
# ... rest of handler code
CopyCopied!
For maximum security:
1. Verify the webhook signature as soon as possible using HMAC-SHA256
2. Ensure the timestamp is within a 5-minute window to prevent replay attacks
3. Use constant-time comparison when checking signatures
4. Return 200 OK immediately after verification
5. Process the webhook payload asynchronously after responding
6. Keep your webhook secret key safe and never commit it to source control
* * *
[Event Delivery Behaviors](/webhooks#event-delivery-behaviors)
---------------------------------------------------------------
This section helps you understand different behaviors to expect regarding how Featurebase sends events to your webhook endpoint.
### Retry behavior
If a webhook delivery fails, Featurebase will automatically retry up to 3 times:
1. 1 minute after the first attempt
2. 1 hour after the second attempt
3. 6 hours after the third attempt
### Event ordering
Featurebase doesn't guarantee that webhook events arrive in the order they were generated. For example, updating a post might generate the following sequence of events:
1. `post.created`
2. `post.updated`
However, these events may not be delivered to your endpoint in that exact order. Your integration should not rely on receiving events sequentially, and it must be able to handle them regardless of arrival sequence.
### Handle duplicate events
Webhook endpoints might occasionally receive the same event more than once. To prevent double-processing, log the unique event IDs that your endpoint has already handled. If a new incoming event's ID matches a previously processed event, skip it.
### Example webhook event with ID
{
"type": "notification_event",
"topic": "post.updated",
"id": "notif_0193a6e6-fb6b-78ef-b71f-15008d9f9cde",
// ... rest of the event data
}
CopyCopied!
### Quick response time
Your endpoint should return a successful (2xx) status code promptly—before performing any lengthy operations that might lead to timeouts. For example:
// Good: Return 200 immediately, then process
app.post('/webhook', async (req, res) => {
// 1. Return 200 OK right away
res.status(200).send('OK');
// 2. Process the webhook asynchronously
processWebhookEvent(req.body).catch(err => {
console.error('Webhook processing error:', err);
});
});
// Bad: Wait for processing before responding
app.post('/webhook', async (req, res) => {
// Don't do this - it could timeout
await processWebhookEvent(req.body);
res.status(200).send('OK');
});
CopyCopied!
This approach prevents timeouts and ensures Featurebase knows your endpoint received the event, even if processing takes longer.
---
# Posts - Featurebase API Reference
Posts
=====
Posts are at the core of Featurebase — they are the basic building blocks of your feedback board. On this page, we'll dive into the different post endpoints you can use to manage them programmatically. We'll look at how to query, create, update, and delete posts.
[The post model](/posts#the-post-model)
----------------------------------------
The Post model contains all the information about the posts and additional metadata created under different boards, including the feedback, reactions, and discussions they generate. This encompasses the title and description of the post, the board it belongs to, any estimated release time for features discussed, and various tags indicating the importance or status of the post. This model allows for a comprehensive overview of user-generated ideas, requests, or issues, and the response they receive from the community.
### Properties
* Name
`id`
Type
string
Description
The id of the post. Example: "6409cde5f3c4e8d9a7977d89"
* Name
`slug`
Type
string
Description
The slug of the post. Example: "my-post-slug".
Can be used to create a URL for the post: `https://{yourorg}.featurebase.app/p/ {slug}`
* Name
`title`
Type
string
Description
The title of the post.
* Name
`content`
Type
string
Description
The content of the post.
* Name
`author`
Type
string
Description
The name of the author of the post.
* Name
`authorId`
Type
string
Description
The id for the author of the post.
* Name
`authorEmail`
Type
string
Description
The email of the author of the post.
* Name
`commentsAllowed`
Type
boolean
Description
Flag indicating whether comments are allowed on the post.
* Name
`organization`
Type
string
Description
The organization that the author of the post belongs to.
* Name
`upvotes`
Type
number
Description
The number of upvotes the post has received.
* Name
`postCategory`
Type
object
Description
The category of the post.
* Name
`authorPicture`
Type
string
Description
The URL to the picture of the author of the post.
* Name
`postStatus`
Type
object
Description
The status of the post.
* Name
`date`
Type
Date
Description
The date when the post was made.
* Name
`comments`
Type
Array
Description
An array of comments ids made on the post.
* Name
`postTags`
Type
Array