A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Canny API is how an app or AI agent works with a Canny feedback portal: listing and creating posts, changing a post's status, casting and removing votes, and reading or leaving comments. Access is granted through a single account-level secret API key sent with each request, and that key carries no per-resource permissions, so anything it can reach, it can reach in full. Canny can also push events to a registered URL when a post, vote, or comment is created.
How an app or AI agent connects to Canny determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the secret API key behind it.
The REST API answers at https://canny.io/api/v1, with a few list methods in a newer https://canny.io/api/v2 namespace. Almost every method is a POST that takes a JSON body, including reads like list and retrieve, because the secret API key travels in that body. Each method returns JSON.
Canny POSTs an event to a URL registered on the API and Webhooks settings page when a post is created, a vote is added, or a comment is left. The receiver verifies the request signature to confirm it came from Canny. This lets an integration react to portal activity without polling.
Canny authenticates every call with one secret API key, found on the company's API and Webhooks settings page. The key is sent as the apiKey field in the POST body. It is account-level: it carries no per-resource or per-method permissions, so any method it can call, it can call in full. It must be kept on a server and never exposed in client code.
The Canny API is split into areas an agent can act on, like posts, votes, comments, boards, and users. Each area has its own methods, and writes in some areas change feedback voters and customers can see, or remove their accounts.
List and read posts, create a post, update it, change its status, board, or category, merge posts, add and remove tags, and delete a post.
List the boards in a feedback portal and read a single board.
List and read votes, cast a vote on a post for a user, and remove a vote.
List and read comments, create a comment on a post, and delete a comment.
List and read categories, create a category on a board, and delete one.
List and read tags, create a tag, and delete one.
List and read users, create or update a user, and delete a user.
List companies, update a company's details, and delete a company.
List the history of status changes across posts.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
PostsList and read posts, create a post, update it, change its status, board, or category, merge posts, add and remove tags, and delete a post.11 | ||||||
| POST | /api/v1/posts/list | List posts, filtered by board, author, status, tag, or search query, and sorted. | read | — | Current | |
The Canny API key is account-level and carries no per-method scopes; any call this key can make, it can make. Read-only call. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/retrieve | Retrieve a single post by its id or urlName. | read | — | Current | |
Read-only. The path is POST even though it retrieves data, because the key travels in the request body. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/create | Create a post on a board, authored by a given user. | write | — | Current | |
Creates feedback visible in the portal. The key has no granular scope to narrow this. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook event post-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/update | Update a post's title, details, or other fields. | write | — | Current | |
Changes feedback voters can see. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/change_status | Change a post's status, like open, planned, in progress, or complete, optionally notifying voters. | write | — | Current | |
Setting a post to its current status returns the post but fires no side effects, like notifications or activity entries. shouldNotifyVoters controls whether voters are emailed. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook event post-status-changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/change_board | Move a post to a different board. | write | — | Current | |
Changes where the feedback appears. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/change_category | Set or clear a post's category. | write | — | Current | |
Changes how the post is filed on its board. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/merge | Merge one post into another, combining their votes. | write | — | Current | |
Merging moves votes and is not a simple undo. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/add_tag | Add a tag to a post. | write | — | Current | |
Changes how the post is labeled. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/remove_tag | Remove a tag from a post. | write | — | Current | |
Changes how the post is labeled. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/posts/delete | Delete a post. | write | — | Current | |
Removes the post and its feedback. The key has no scope to block this on its own. Acts onpost Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BoardsList the boards in a feedback portal and read a single board.2 | ||||||
| POST | /api/v1/boards/list | List all the boards in a feedback portal. | read | — | Current | |
Read-only. Acts onboard Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/boards/retrieve | Retrieve a single board by its id. | read | — | Current | |
Read-only. Acts onboard Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
VotesList and read votes, cast a vote on a post for a user, and remove a vote.4 | ||||||
| POST | /api/v1/votes/list | List votes, filtered by board, post, or user. | read | — | Current | |
Read-only. Acts onvote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/votes/retrieve | Retrieve a single vote by its id. | read | — | Current | |
Read-only. Acts onvote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/votes/create | Cast a vote on a post on behalf of a user. | write | — | Current | |
Votes on a post in a named user's name, changing its vote count. Acts onvote Permission (capability)None required VersionAvailable since the API’s base version Webhook event vote-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/votes/delete | Remove a user's vote from a post. | write | — | Current | |
Lowers a post's vote count by removing a vote. Acts onvote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommentsList and read comments, create a comment on a post, and delete a comment.4 | ||||||
| POST | /api/v1/comments/list | List comments, filtered by board, post, or author. | read | — | Current | |
Read-only. A cursor-paginated v2 variant is also offered at /api/v2/comments/list. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/comments/retrieve | Retrieve a single comment by its id. | read | — | Current | |
Read-only. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/comments/create | Create a comment on a post, authored by a given user. | write | — | Current | |
Adds a comment voters can see on the post. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook event comment-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/comments/delete | Delete a comment. | write | — | Current | |
Removes a comment from the post. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CategoriesList and read categories, create a category on a board, and delete one.4 | ||||||
| POST | /api/v1/categories/list | List the categories on a board. | read | — | Current | |
Read-only. Acts oncategory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/categories/retrieve | Retrieve a single category by its id. | read | — | Current | |
Read-only. Acts oncategory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/categories/create | Create a category on a board. | write | — | Current | |
Changes how a board organizes feedback. Acts oncategory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/categories/delete | Delete a category that has no subcategories. | write | — | Current | |
Removes a category from a board. Acts oncategory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList and read tags, create a tag, and delete one.4 | ||||||
| POST | /api/v1/tags/list | List the tags in a feedback portal. | read | — | Current | |
Read-only. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/tags/retrieve | Retrieve a single tag by its id. | read | — | Current | |
Read-only. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/tags/create | Create a tag on a board. | write | — | Current | |
Adds a tag teammates can apply to posts. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/tags/delete | Delete a tag. | write | — | Current | |
Removes the tag and unlinks it from posts. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersList and read users, create or update a user, and delete a user.4 | ||||||
| POST | /api/v1/users/list | List the users in a feedback portal. | read | — | Current | |
Read-only. Returns the people who have accounts, including names and email addresses. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/users/retrieve | Retrieve a single user by id, email, or the app's own userID. | read | — | Current | |
Read-only. Returns a person's profile, including their email address. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/users/create_or_update | Create a user, or update an existing one matched by id or email. | write | — | Current | |
Creates or edits the account of a real person, including their name and email. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/users/delete | Delete a user. | write | — | Current | |
Removes a person's account. The account-level key has no scope to block this on its own. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CompaniesList companies, update a company's details, and delete a company.3 | ||||||
| POST | /api/v2/companies/list | List companies, paginated with a cursor. | read | — | Current | |
Read-only. This list method lives in the newer v2 namespace and uses cursor pagination. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/companies/update | Create or update a company's details, like its name, monthly spend, and custom fields. | write | — | Current | |
Changes a customer-account record used to weight feedback. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/companies/delete | Delete a company. | write | — | Current | |
Removes a customer-account record. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Status changesList the history of status changes across posts.1 | ||||||
| POST | /api/v1/status_changes/list | List the history of status changes across posts, filtered by board. | read | — | Current | |
Read-only. Returns the record of which posts changed status, when, and to what. Acts onstatus change Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Canny can notify an app or AI agent when something happens in a feedback portal, like a post being created, a vote being added, or a comment being left. It posts the event to a registered URL, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
New post | Fires when a new post is created on a board, whether through the portal or the API. | /api/v1/posts/create |
Post status changed | Fires when a post's status changes, like moving to planned, in progress, or complete. | /api/v1/posts/change_status |
New vote | Fires when a vote is added to a post. | /api/v1/votes/create |
New comment | Fires when a comment is left on a post. | /api/v1/comments/create |
Canny limits how fast an app or AI agent can call, against the single account-level API key, and returns an error once a request runs too often.
Canny meters requests against the single account-level API key and returns an error once calls arrive too quickly, so a high-volume job should pace itself rather than burst. The reference does not publish an exact requests-per-minute number, and a throttled request comes back as an HTTP 429 with the standard advice to back off and retry. Because one key serves the whole account, every integration and agent sharing it draws on the same allowance.
List methods page in one of two ways. The v1 methods use skip-based pagination, with a limit for the page size and a skip offset to move through results. The newer v2 list methods, like comments and companies, use cursor-based pagination instead, where the response returns a cursor to pass into the next request. A list method returns a hasMore-style signal so a caller knows when to stop.
Responses are JSON. A single list page is capped per method, and some list methods cap the total results they will return, such as a maximum around 10,000 categories. There is no separate documented request-body size limit across the whole API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | error field in body | The request was rejected, for example a missing or invalid parameter like an unknown postID. Canny returns a JSON body with an error field describing the problem, such as {"error":"invalid postID"}. | Read the error field, correct the named parameter, and resend. |
| 401 | invalid apiKey | The secret API key is missing or invalid, so the request is not authenticated. | Send a valid apiKey from the API and Webhooks settings page in the request body. |
| 429 | rate limit | Requests against the API key arrived too quickly and were throttled. | Back off and retry with exponential backoff, honoring any Retry-After header before resending. |
| 500 | server error | An error on Canny's side, which is uncommon. | Retry after a short wait, and contact Canny support if it persists. |
Canny serves a stable v1 API and has begun adding a v2 namespace for a few list methods that use cursor pagination. It does not pin dated versions per account.
Canny serves a stable v1 REST API where almost every method is a POST that takes the secret API key in its JSON body. It does not pin a dated version per account or send a version header. A newer v2 namespace has been added for a few list methods, like comments and companies, that use cursor-based pagination, while v1 list methods use skip-based pagination. New methods are added over time rather than through breaking dated releases.
An integration calls the v1 or v2 path directly; there is no version header to pin.
Canny API reference ↗Bollard AI sits between a team's AI agents and Canny. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.