API Reference
Canny's API lets you access and modify your Canny data programmatically. We also support webhooks, where we notify your server of events as they happen.
All API and webhook requests are sent via HTTPS. All responses, including errors, return JSON.
This API enables you to seamlessly integrate Canny with your existing services.
Authentication
API requests must be authenticated by including your secret API key. You can find your secret API key in
Your Subdomain > Settings > API
. This key is secret, so be careful not to share it publicly and don't store it in the client side of your app.
You can include your secret API key in a request by adding it as a POST parameter with key apiKey.
Example request:
$ curl https://canny.io/api/v1/boards/list \
    -d apiKey=YOUR_API_KEY
Boards
Boards are the high-level objects where your users can post and vote on ideas for a specific topic, typically feature requests. The API allows you to fetch a specific board, or a list of all boards for your company.
The board object
Attributes
id
string
A unique identifier for the board.
created
timestamp
Time at which the board was created. Measured in seconds since the Unix epoch.
description
string
The board's description. This shows up publicly on your board, setting context for what users should be posting ideas about.
name
string
The board's name.
postCount
number
The number of non-deleted posts associated with the board. This number includes posts that are marked as closed or complete.
urlName
string
The "URL Name" for the board. The board's URL will be https://your-subdomain.canny.io/{board.urlName}.
Example board object:
{
  "id": "553c3ef8b8cdcd1501ba1234",
  "created": 1446788856447,
  "description": "Test Board Description",
  "name": "Feature Requests",
  "postCount": 123,
  "urlName": "feature-requests"
}
Retrieve board
Retrieves the details of an existing board, specified by its id.
Arguments
apiKey
string
Your secret API key.
id
string
The board's unique identifier.
Returns
Returns a board object, if a valid id was supplied.
Endpoint
https://canny.io/api/v1/boards/retrieve
Example Request
$ curl https://canny.io/api/v1/boards/retrieve \
    -d apiKey=YOUR_API_KEY \
    -d id=553c3ef8b8cdcd1501ba1234
Example Response
{
  "id": "553c3ef8b8cdcd1501ba1234",
  "created": 1446788851234,
  "description": "Test Board Description",
  "name": "Feature Requests",
  "postCount": 123,
  "urlName": "feature-requests"
}
List all boards
Returns a list of all boards associated with your company, in no particular order.
Arguments
apiKey
string
Your secret API key.
Returns
A dictionary with a "boards" property that contains an array of board objects.
Endpoint
https://canny.io/api/v1/boards/list
Example Request
$ curl https://canny.io/api/v1/boards/list \
    -d apiKey=YOUR_API_KEY
Example Response
{
  "boards": [{
    "id": "553c3ef8b8cdcd1501ba1234",
    "created": 1446788851234,
    "description": "Test Board Description",
    "name": "Feature Requests",
    "postCount": 123,
    "urlName": "feature-requests"
  }, {
    "id": "553c3ef8b8cdcd1501ba1238",
    "created": 1446788852468,
    "description": "Test Board Description",
    "name": "Bug Reports",
    "postCount": 42,
    "urlName": "bug-reports"
  }]
}
Posts
A post is an object that represents an idea posted to a board. They are always associated with a user and a board. Users can vote on them. The API allows you to fetch a specific post, or a list of posts for a board.
The post object
Attributes
id
string
A unique identifier for the post.
author
User object
The user who created the board.
board
Board object
The board this post is associated with.
commentCount
number
The number of non-deleted comments associated with this post.
created
timestamp
Time at which the post was created. Measured in seconds since the Unix epoch.
details
string
Any details the user included in the post. This is the longer text field (where the shorter one is "title").
imageURLs
array
An array of the URLs of the images associated with this post
score
number
The number of votes that have been cast on this post.
status
string
The post's status: "open", "planned", "in progress", "complete", or "closed".
title
string
A brief title describing the post. This is the shorter text input (where the longer is details).
urlName
string
The "URL Name" for the post. The post's URL will be https://your-subdomain.canny.io/board-url-name/p/{post.urlName}.
Example post object:
{
  "id": "553c3ef8b8cdcd1501ba1238",
  "author": {
    "id": "553c3ef8b8cdcd1501ba123a",
    "created": 1446788856000,
    "email": "test@test.test",
    "name": "Sally Doe",
    "urlName": "sally-doe",
    "userID": "1234"
  },
  "board": {
    "id": "553c3ef8b8cdcd1501ba1234",
    "created": 1446788856447,
    "description": "Test Board Description",
    "name": "Feature Requests",
    "postCount": 123,
    "urlName": "feature-requests"
  },
  "commentCount": 10,
  "created": 1446788852000,
  "details": "Test post details",
  "imageURLs": [
    "https://canny.io/images/93fc5808937760b82c3dc00aa5cd86b8.png",
    "https://canny.io/images/316e5600645b81e4be287a52d506dbfd.jpg"
  ],
  "score": 72,
  "status": "in progress",
  "title": "An awesome feature request",
  "urlName": "an-awesome-feature-request"
}
Retrieve post
Retrieves the details of an existing post, specified by its id.
Arguments
apiKey
string
Your secret API key.
id
string
The post's unique identifier.
Returns
Returns a post object, if a valid id was supplied.
Endpoint
https://canny.io/api/v1/posts/retrieve
Example Request
$ curl https://canny.io/api/v1/posts/retrieve \
    -d apiKey=YOUR_API_KEY \
    -d id=553c3ef8b8cdcd1501ba1238
Example Response
{
  "id": "553c3ef8b8cdcd1501ba1238",
  "author": {
    "id": "553c3ef8b8cdcd1501ba123a",
    "created": 1446788856000,
    "email": "test@test.test",
    "name": "Sally Doe",
    "urlName": "sally-doe",
    "userID": "1234"
  },
  "board": {
    "created": 1446788856447,
    "description": "Test Board Description",
    "id": "553c3ef8b8cdcd1501ba1234",
    "name": "Feature Requests",
    "postCount": 123,
    "urlName": "feature-requests"
  },
  "commentCount": 10,
  "created": 1446788852000,
  "details": "Test post details",
  "imageURLs": [
    "https://canny.io/images/93fc5808937760b82c3dc00aa5cd86b8.png",
    "https://canny.io/images/316e5600645b81e4be287a52d506dbfd.jpg"
  ],
  "score": 72,
  "status": "in progress",
  "title": "An awesome feature request",
  "urlName": "an-awesome-feature-request"
}
List posts for board
Returns a list of posts. Include parameters to specify board, pagination, filtering, and sorting.
Arguments
apiKey
string
Your secret API key.
boardID
string (optional)
The id of the board you'd like to fetch posts for.
authorID
string (optional)
If specified, will only fetch posts by the author with this id.
limit
number (optional)
The number of posts you'd like to fetch. Defaults to 10 if not specified.
skip
number (optional)
The number of posts you'd like to skip before starting to fetch. Defaults to 0 if not specified.
sort
string (optional)
The order in which the posts should be fetched. Options include: "newest", "oldest", "score", "trending". Defaults to "newest" if not specified.
status
string (optional)
A comma separated list of statuses. Only posts with these statuses will be fetched. Defaults to "open,planned,in progress" if not specified.
Returns
A dictionary with a "posts" property that contains an array of post objects. There's also a "hasMore" property that specifies whether this query returns more posts than the limit.
Endpoint
https://canny.io/api/v1/posts/list
Example Request
$ curl https://canny.io/api/v1/posts/list \
    -d apiKey=YOUR_API_KEY \
    -d boardID=553c3ef8b8cdcd1501ba1234
Example Response
{
  "hasMore": true,
  "posts": [{
    "id": "553c3ef8b8cdcd1501ba1238",
    "author": {
      "id": "553c3ef8b8cdcd1501ba123a",
      "created": 1446788856000,
      "email": "test@test.test",
      "name": "Sally Doe",
      "urlName": "sally-doe",
      "userID": "1234"
    },
    "boardID": "553c3ef8b8cdcd1501ba2222",
    "commentCount": 10,
    "created": 1446788852000,
    "details": "Test post details",
    "imageURLs": [
      "https://canny.io/images/93fc5808937760b82c3dc00aa5cd86b8.png",
      "https://canny.io/images/316e5600645b81e4be287a52d506dbfd.jpg"
    ],
    "score": 72,
    "status": "in progress",
    "title": "An awesome feature request",
    "urlName": "an-awesome-feature-request"
  }]
}
Change post status
Changes a post's status (eg. to 'planned'), specified by its id.
Arguments
apiKey
string
Your secret API key.
changerID
string
The identifier of the admin to record as having changed the post's status. This will be visible in the post's activity section.
postID
string
The post's unique identifier.
shouldNotifyVoters
boolean
Whether or not to notify non-admin voters of the status change.
status
string
The status to change the post to. Options include: "open", "planned", "in progress", "fixed", or "closed".
Returns
Returns "success" if the post's status was successfully changed.
Note:
If you try to change a post's status to its current status (eg. "planned" to "planned"), the endpoint will respond with "success" but none of the side-effects will trigger (post activity unit, slack notification, user notification, etc).
Endpoint
https://canny.io/api/v1/posts/change_status
Example Request
$ curl https://canny.io/api/v1/posts/change_status \
    -d apiKey=YOUR_API_KEY \
    -d changerID=553c3ef8b8cdcd1501ba123a \
    -d postID=553c3ef8b8cdcd1501ba1238 \
    -d shouldNotifyVoters=true \
    -d status="in progress"
Example Responses
success
{"error":"invalid post id"}
Comments
Users and teammates can leave comments on posts. Therefore, comment objects are always associated with a post. The API allows you to fetch a specific comment, or a list of comments for a post.
The comment object
Attributes
id
string
A unique identifier for the comment.
author
User object
The user who created the comment.
created
timestamp
Time at which the comment was created. Measured in seconds since the Unix epoch.
imageURLs
array
An array of the URLs of the images associated with this comment.
parentID
string
The id of the comment that this comment is a reply to. If this comment is not a reply, this field will be null.
postID
string
The id of the post this comment is associated with.
value
string
The text value of this comment.
Example comment object:
{
  "id": "553c3ef8b8cdcd1501ba1238",
  "author": {
    "id": "553c3ef8b8cdcd1501ba123a",
    "created": 1446788856000,
    "email": "test@test.test",
    "name": "Sally Doe",
    "urlName": "sally-doe",
    "userID": "1234"
  },
  "created": 1446788852000,
  "imageURLs": [
    "https://canny.io/images/93fc5808937760b82c3dc00aa5cd86b8.png",
    "https://canny.io/images/316e5600645b81e4be287a52d506dbfd.jpg"
  ],
  "parentID": "553c3ef8b8cdcd1501ba3333",
  "postID": "553c3ef8b8cdcd1501ba4444",
  "value": "Some cool comment"
}
Retrieve comment
Retrieves the details of an existing comment, specified by its id.
Arguments
apiKey
string
Your secret API key.
id
string
The comment's unique identifier.
Returns
Returns a comment object, if a valid id was supplied.
Endpoint
https://canny.io/api/v1/comments/retrieve
Example Request
$ curl https://canny.io/api/v1/comments/retrieve \
    -d apiKey=YOUR_API_KEY \
    -d id=553c3ef8b8cdcd1501ba1238
Example Response
{
  "id": "553c3ef8b8cdcd1501ba1238",
  "author": {
    "id": "553c3ef8b8cdcd1501ba123a",
    "created": 1446788856000,
    "email": "test@test.test",
    "name": "Sally Doe",
    "urlName": "sally-doe",
    "userID": "1234"
  },
  "created": 1446788852000,
  "imageURLs": [
    "https://canny.io/images/93fc5808937760b82c3dc00aa5cd86b8.png",
    "https://canny.io/images/316e5600645b81e4be287a52d506dbfd.jpg"
  ],
  "parentID": "553c3ef8b8cdcd1501ba3333",
  "postID": "553c3ef8b8cdcd1501ba4444",
  "value": "Some cool comment"
}
List comments for post
Returns a list of comments associated with a specific post, in no particular order.
Arguments
apiKey
string
Your secret API key.
postID
string
The id of the post you'd like to fetch comments for
Returns
A dictionary with a "comments" property that contains an array of all comment objects associated with the provided post id.
Endpoint
https://canny.io/api/v1/comments/list
Example Request
$ curl https://canny.io/api/v1/comments/list \
    -d apiKey=YOUR_API_KEY \
    -d postID=553c3ef8b8cdcd1501ba2468
Example Response
{
  "comments": [{
    "id": "553c3ef8b8cdcd1501ba1238",
    "author": {
      "id": "553c3ef8b8cdcd1501ba123a",
      "created": 1446788856000,
      "email": "test@test.test",
      "name": "Sally Doe",
      "urlName": "sally-doe",
      "userID": "1234"
    },
    "created": 1446788852000,
    "imageURLs": [
      "https://canny.io/images/93fc5808937760b82c3dc00aa5cd86b8.png",
      "https://canny.io/images/316e5600645b81e4be287a52d506dbfd.jpg"
    ],
    "parentID": "553c3ef8b8cdcd1501ba3333",
    "postID": "553c3ef8b8cdcd1501ba4444",
    "value": "Some cool comment"
  }]
}
Votes
Users can vote on posts. Teammates can also vote on behalf of users. Vote objects are always associated with a post and a voter. The API allows you to fetch a specific vote, or a list of votes associated with a post.
The vote object
Attributes
id
string
A unique identifier for the vote.
by
User object
The admin who cast this vote on behalf of a user. If the user voted themselves, this field will be null.
created
timestamp
Time at which the vote was first cast. Measured in seconds since the Unix epoch.
postID
string
The id of the post this vote is associated with.
voter
User object
The user this post is associated with.
Example vote object:
{
  "id": "553c3ef8b8cdcd1501ba123b",
  "by": null,
  "created": 1446788852000,
  "postID": "553c3ef8b8cdcd1501ba4444",
  "voter": {
    "id": "553c3ef8b8cdcd1501ba123a",
    "created": 1446788856000,
    "email": "test@test.test",
    "name": "Sally Doe",
    "urlName": "sally-doe",
    "userID": "1234"
  }
}
Retrieve vote
Retrieves the details of an existing vote, specified by its id.
Arguments
apiKey
string
Your secret API key.
id
string
The vote's unique identifier.
Returns
Returns a vote object, if a valid id was supplied.
Endpoint
https://canny.io/api/v1/votes/retrieve
Example Request
$ curl https://canny.io/api/v1/votes/retrieve \
    -d apiKey=YOUR_API_KEY \
    -d id=553c3ef8b8cdcd1501ba123b
Example Response
{
  "id": "553c3ef8b8cdcd1501ba123b",
  "by": null,
  "created": 1446788852000,
  "postID": "553c3ef8b8cdcd1501ba4444",
  "voter": {
    "id": "553c3ef8b8cdcd1501ba123a",
    "created": 1446788856000,
    "email": "test@test.test",
    "name": "Sally Doe",
    "urlName": "sally-doe",
    "userID": "1234"
  }
}
List votes for post
Returns a list of votes associated with a specific post, in order of recency.
Arguments
apiKey
string
Your secret API key.
postID
string
The id of the post you'd like to fetch votes for
Returns
A dictionary with a "votes" property that contains an array of all vote objects associated with the provided post id.
Endpoint
https://canny.io/api/v1/votes/list
Example Request
$ curl https://canny.io/api/v1/votes/list \
    -d apiKey=YOUR_API_KEY \
    -d postID=553c3ef8b8cdcd1501ba2468
Example Response
{
  "votes": [{
    "id": "553c3ef8b8cdcd1501ba123b",
    "by": null,
    "created": 1446788852000,
    "postID": "553c3ef8b8cdcd1501ba2468",
    "voter": {
      "id": "553c3ef8b8cdcd1501ba123a",
      "created": 1446788856000,
      "email": "test@test.test",
      "name": "Sally Doe",
      "urlName": "sally-doe",
      "userID": "1234"
    }
  }]
}
Users
Users can create posts, votes, and comments. Your teammates also have user accounts. The API allows you to fetch a specific user.
The user object
Attributes
id
string
A unique identifier for the user.
created
timestamp
Time at which the user was created. Measured in seconds since the Unix epoch.
email
string
The user's email. This field can be null, for example when you create a new user by voting on behalf of them.
name
string
The user's name.
urlName
string
The "URL Name" for the user. This is the unique string used to mention them in a comment, and will later be used to generate predictible user profile URLs.
userID
string
The user's unique identifier in your application. This field can be null. We only have this data if the user was authenticated via single sign-on, or if it was added via API.
Example user object:
{
  "id": "553c3ef8b8cdcd1501ba123a",
  "created": 1446788856000,
  "email": "test@test.test",
  "name": "Sally Doe",
  "urlName": "sally-doe",
  "userID": "1234"
}
Retrieve user
Retrieves the details of an existing user. You must specify exactly one of: their Canny id, their id in your application, or their email. These fields are all unique per user.
You can only retrieve them based on their id in your application if the user was authenticated via single sign-on or created via API.
Arguments
apiKey
string
Your secret API key.
email
string (optional)
The user's email.
id
string (optional)
The user's unique identifier from Canny.
userID
string (optional)
The user's unique identifier in your application.
Returns
Returns a user object, if a valid identifier was supplied.
Endpoint
https://canny.io/api/v1/users/retrieve
Example Request (Canny id)
$ curl https://canny.io/api/v1/users/retrieve \
    -d apiKey=YOUR_API_KEY \
    -d id=553c3ef8b8cdcd1501ba123a
Example Request (your application's user id)
$ curl https://canny.io/api/v1/users/retrieve \
    -d apiKey=YOUR_API_KEY \
    -d userID=1234
Example Request (email)
$ curl https://canny.io/api/v1/users/retrieve \
    -d apiKey=YOUR_API_KEY \
    -d email="test@test.test"
Example Response
{
  "id": "553c3ef8b8cdcd1501ba123a",
  "created": 1446788856000,
  "email": "test@test.test",
  "name": "Sally Doe",
  "urlName": "sally-doe",
  "userID": "1234"
}
Webhooks
By setting up webhooks, your server will be notified of Canny events as they happen. For example, if a user creates a new post, we would send a request to your server to let you know.
You can set up webhooks for your account in
Your Subdomain > Settings > API
.
The event object
Attributes
created
timestamp
Time at which the event was created. Measured in seconds since the Unix epoch.
object
object
The object the event is about.
objectType
string
The type of object included in the event.
type
string
The type of event.
Example event object:
{
  "created": 1446788856020,
  "object": {
    "id": "553c3ef8b8cdcd1501ba1238",
    "author": {
      "id": "553c3ef8b8cdcd1501ba123a",
      "created": 1446788856000,
      "email": "test@test.test",
      "name": "Sally Doe",
      "urlName": "sally-doe",
      "userID": "1234"
    },
    "board": {
      "id": "553c3ef8b8cdcd1501ba1234",
      "created": 1446788856447,
      "description": "Test Board Description",
      "name": "Feature Requests",
      "postCount": 123,
      "urlName": "feature-requests"
    },
    "commentCount": 10,
    "created": 1446788852000,
    "details": "Test post details",
    "imageURLs": [
      "https://canny.io/images/93fc5808937760b82c3dc00aa5cd86b8.png",
      "https://canny.io/images/316e5600645b81e4be287a52d506dbfd.jpg"
    ],
    "score": 72,
    "status": "in progress",
    "title": "An awesome feature request",
    "urlName": "an-awesome-feature-request"
  },
  "objectType": "post",
  "type": "post.created"
}
Event types
This is a list of all types of events we send.
Event
post.created
Occurs when a new post is created.
post.deleted
Occurs when a post is deleted.
comment.created
Occurs when a new comment is created.
comment.deleted
Occurs when a comment is deleted.
vote.created
Occurs when a user votes on a post.
vote.deleted
Occurs when a user unvotes on a post.