Public REST API

Feature Upvote has a public REST API that allows you to use core functionality:

• View suggestions
• Create and update suggestions
• View comments
• Vote and “unvote” for a suggestion
• Get notifications via a webhook of new suggestions and comments

Endpoints

• Verify your key is valid
• List your account’s boards
• Show one specific board
• List a board’s suggestions
• Show one specific suggestion
• Search for suggestions
• List a board’s statuses
• Create a new suggestion
• Update an existing suggestion
• List a suggestion’s comments
• Show one specific comment
• Create a new comment
• Update an existing comment
• List a suggestion’s votes
• Vote for a suggestion
• Remove a vote
• Subscribe to a webhook for new or changed suggestions and comments
• Unsubscribe from a webhook
• List webhooks

Response bodies are in JSON

All results are in JSON. If you don’t get a  valid JSON response body, it’s probably one of these problems:

1. The URL is wrong
2. Cloudflare, who protects our website from attacks, has incorrectly identified your usage as malicious. Let us know and we’ll investigate

API key

To use this API, you’ll need an API key. You create and manage API keys in your Feature Upvote dashboard:

1. Click on the user icon in the top-right hand corner
2. From the drop-down menu, select Account
3. Go to the Developer tab

Or, if you are currently signed in to your Feature Upvote account, click here.

Creating an API key

Under Create a new API key, enter a name for the key and click Create API key. Choose a name that tells you where the key is used, such as “Zapier” or “Internal reporting script”. Your new key appears in the list, with a Copy to clipboard button.

You can have up to 20 API keys. We recommend creating a separate key for each application or integration. That way, if you stop using one, or a key is exposed, you can delete that key without affecting your other integrations.

Deleting an API key

To delete a key, click its Delete button and confirm. Any application using that key immediately loses access to your Feature Upvote account. This can’t be undone.

To replace a key, for example after a team member with access to it has left, first create a new key and update your application to use it. Then delete the old key.

Who can manage API keys?

Only admin users can create, view and delete API keys.

Caution

Keep your API keys private. An API key gives access to all of your Feature Upvote data. Don’t share keys in emails, chat messages or public code repositories.

REST API URL

All endpoints start with https://api.featureupvote.com/api/v1/                    

Authentication

All requests must be authenticated using the HTTP Bearer header:

curl -X GET "https://api.featureupvote.com/api/v1/verify" -H "Authorization: Bearer <api_key>"                    

Pagination

Three response headers show you information about pagination:

• Pagination-Count - the full number of results available.
• Pagination-Limit - the maximum number of results returned per request. Defaults to 10.
• Pagination-Offset - how many results were skipped in this response. Defaults to 0.

If you are familiar with SQL, you can think of the Pagination-Limit and Pagination-Offset parameters as analagous to SQL’s LIMIT and OFFSET keywords.

Set limit and offset

You can override these using query parameters:

• limit                    query parameter, defaults to 10
• offset                    query parameter, defaults to 0

eg

https://api.featureupvote.com/api/v1/boards?limit=20&offset=40                   

Rate limits

Our public REST API has generous rate limits, but they do exist as part of our protections from external attack. If you find your API usage is impacted by our rate limits, get in touch and tell us your use case. We might be able to make an exception.

Endpoints

Verify your key is valid

A great starting point:

URL: https://api.featureupvote.com/api/v1/verify                    

Method: GET

Example success response:

{
  "result": "success",
  "message": "This API key is valid and active.",
  "accountId": 1
}

Example error responses:

{
  "error": {
    "message": "Invalid API Key provided: ****efer",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "message": "You did not provide an API key. You need to provide your API key in the Authorization header using a Bearer token (e.g. Authorization: Bearer [YOUR_API_KEY])",
    "type": "invalid_request_error"
  }
}

List your account’s boards

URL: https://api.featureupvote.com/api/v1/boards                    

Method: GET

Show one specific board

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}                    

Method: GET

List a board’s suggestions

URL:https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions                   

Method: GET

Show one specific suggestion

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions/{suggestionId}        

Method: GET

Search for suggestions

URL:https://api.featureupvote.com/api/v1/boards/{boardRef}/search?q={search+terms}                 

Method: GET

Separate multiple search terms with the +      sign.

By default, you’ll receive at most 20 results. Use the limit     query parameter to change this. The maximum allowed value for limit      is 250.

eg

https://api.featureupvote.com/api/v1/boards/{boardRef}/search?q=potion+upgrade&limit=50                 

List a board’s statuses

URL:https://api.featureupvote.com/api/v1/boards/{boardRef}/statuses                 

Method: GET

Returns a list of valid statuses for your board, including the short codes (aka statusRef    ) needed to create or update a suggestion if you don’t want to accept the default “Awaiting approval” status.

The result is an array of JSON objects, each representing one status.

eg

{
  "id": 1360,
  "statusRef": "awaitingapproval",
  "description": "Awaiting approval"
}

In this case, the short code is awaitingapproval                .

Create a new suggestion

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions                 

Method: POST

Returns the newly created suggestion in the response body.

The request body must be a JSON object, with the following properties:

Property	Required	Type	Default
title	Required	String, max 100 characters
description	Optional	String, max 2,000 characters. Any HTML tags and entities in the description will be escaped.
status	Optional	String, must be the short code (aka statusRef    ) for one of your board’s statuses. See “List a board’s statuses” section	awaitingapproval
remote_user_id	Optional	String, max 200 characters. Use this to match the user to someone in your own systems.
name	Required	String, max 50 characters
email	Required	String, max 200 characters, must be a well-formed email address

Update an existing suggestion

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions/{suggestionId}                 

Method: POST

Returns the updated suggestion in the response body.

A field will only be updated if it is present in the request.

The request body must be a JSON object, with the following properties:

Property	Required	Type
title	Optional	String, max 100 characters
description	Optional	String, max 2,000 characters. Any HTML tags and entities in the description will be escaped.
status	Optional	String, must be the short code (aka statusRef    ) for one of your board’s statuses. See “List a board’s statuses” section

List a suggestion’s comments

URL:https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions/{suggestionId}/comments                   

Method: GET

Show one specific comment

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions/{suggestionId}/comments/{commentId}       

Method: GET

Create a new comment

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions/{suggestionId}/comments              

Method: POST

Returns the newly created comment in the response body.

The request body must be a JSON object, with the following properties:

Property	Required	Type	Default
text	Required	String, max 1,000 characters
status	Optional	String, one of “unmoderated”, “approved”, “spam”, “deleted”	“unmoderated”
remote_user_id	Optional	String, max 200 characters. Use this to match the user to someone in your own systems.
name	Required	String, max 50 characters
email	Required	String, max 200 characters, must be a well-formed email address

Update an existing comment

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions/{suggestionId}/comments/{commentId}                 

Method: POST

Returns the updated comment in the response body.

A field will only be updated if it is present in the request.

The request body must be a JSON object, with the following properties:

Property	Required	Type
text	Optional	String, max 1,000 characters
status	Optional	String, one of “unmoderated”, “approved”, “spam”, “deleted”

List a suggestion’s votes

URL:https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions/{suggestionId}/votes          

Method: GET

Vote for a suggestion

URL:https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions/{suggestionId}/votes          

Method: POST

Returns the newly created vote in the response body.

An attempt is made to find an existing contributor with either the remoteUserId, or with the combination of name and email. If found, the vote is assigned to the existing contributor. Otherwise a new contributor is created.

The request body must be a JSON object, with the following properties:

Property	Required	Type	Default
name	Required	String, max 50 characters
email	Required	String, max 200 characters, must be a well-formed email address
remoteUserId	Optional	String, max 200 characters. Use this to match the user to someone in your own systems.
proxyVote	Optional	Boolean. Indicates that this is a vote on behalf of a customer rather than a vote by the customer. This field exists just for your info, and doesn’t affect the system in any way.	false
follow	Optional	Boolean. If true, then the contributor is registered as a follow of the suggestion they are voting for, and will receive email notifications when the suggestion is updated, if enabled for your account.	false

Remove a vote

URL:https://api.featureupvote.com/api/v1/boards/{boardRef}/suggestions/{suggestionId}/votes/{upvoteId}          

Method: DELETE

Removes the vote with the specified upvoteId           . If not found, a helpful error message is returned.

The vote must belong to the specified suggestion.

Create a webhook endpoint for new or changed suggestions and comments

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}/hooks                

Method: POST

Returns info about the newly created webhook in the response body.

The request body must be a JSON object, with the following properties:

Property	Description	Required	Type
target_url	A URL on your server that will receive a GET request when the webhook is triggered.	Required	String, max 250 characters
event	The type of event to be notified of. Each webhook can only receive one type of event.	Required	String. One of “new_suggestion”, “new_comment”, “suggestion_changed”

Delete a webhook endpoint

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}/hooks/unsubscribe                

Method: POST

The request body must be a JSON object, with the following properties:

Property	Description	Required	Type
target_url	The URL of the webhook you are unsubscribing from Feature Upvote.	Required	String, max 250 characters

List webhooks

URL: https://api.featureupvote.com/api/v1/boards/{boardRef}/hooks                

Method: GET

Returns a list of all webhooks currently registered for the specified board.

Caution

This guide is a work in progress and may contain errors.

If you find an error - or find the instructions confusing - please write to us at support@featureupvote.com.

We’re friendly, we like to help, and we want to make this an excellent guide.

Related articles

• API usage example in Java
• API usage example in Python
• API usage example in JavaScript