A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Aha! API is how an app or AI agent works with an Aha! account: listing and creating features, capturing ideas from customer feedback, organizing initiatives and releases, and updating goals and to-dos. Access is granted through an API key or an OAuth token, each tied to one user, and a call can reach exactly what that user can reach, because Aha! has no separate per-method permissions. Aha! can also push events to a webhook when a record is created, updated, or destroyed.
How an app or AI agent connects to Aha! determines what it can reach. There are a few routes, each carried by an API key or OAuth token that is tied to one user, and each call runs with that user's own access.
The REST API answers per account at {account}.aha.io/api/v1, where {account} is the customer's own subdomain. It is served under one major version, v1, and returns JSON over HTTPS.
Aha! publishes a first-party MCP server at https://{account}.aha.io/api/v1/mcp, available across the Aha! suite. It lets an AI assistant read, search, analyze, create, and update records the connected user can access, but it cannot delete records. Admins enable it and set view or edit access under the account's AI controls settings.
An activity webhook posts a JSON audit payload to a registered URL whenever a record is created, updated, or destroyed. It is configured at the account or workspace level and filtered by record type and field, and it sends only the fields that changed.
A user authorizes a registered application through the authorization code flow at {account}.aha.io/oauth/authorize, and the application exchanges the code at {account}.aha.io/oauth/token for a token to call the API on that user's behalf. Aha! recommends OAuth 2.0 because the application never sees the user's Aha! credentials. The token carries the user's full access; there are no granular scopes.
An API key is generated in the Aha! interface, tied to one user and account, and keeps working even after that user changes their password. It is sent the same way as an OAuth token, as a Bearer token, and inherits the user's full access. There are no granular scopes.
The Aha! API is split into the records a product team works with, such as features, ideas, initiatives, releases, epics, requirements, and goals. Each has its own methods to list, read, create, update, and delete, and every call runs with the access of the user behind the key.
List, read, create, update, and delete features, update their custom fields, and convert a feature to an epic.
List and search ideas in a product, read a single idea, and create an idea in an ideas portal.
List, read, create, update, and delete strategic initiatives.
List, read, create, update, and delete releases in a product.
List, read, create, update, and delete epics.
Read, create, update, and delete the requirements that belong to a feature.
List, read, create, update, and delete goals (strategic imperatives).
List the products (workspaces) in an account and read a single product.
List, read, create, update, and delete to-dos and approvals.
Read and create comments on a feature, idea, requirement, release, goal, epic, or initiative.
List the custom fields defined in the account and the options for a custom field.
Receive an activity webhook that posts record create, update, and destroy events to a registered URL.
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 | |
|---|---|---|---|---|---|---|
FeaturesList, read, create, update, and delete features, update their custom fields, and convert a feature to an epic.6 | ||||||
| GET | /api/v1/features | List features, optionally filtered by release, product, epic, goal, initiative, workflow status, or custom field. | read | — | Current | |
Aha! has no per-endpoint API scopes. The token reaches every feature the user can see in the workspaces they belong to. Acts onfeature Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/features/{id} | Get a specific feature by its reference number or id. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own view permission for the feature. Acts onfeature Permission (capability)None required VersionAvailable since the API’s base version Webhook event feature-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/releases/{release_id}/features | Create a feature within a release. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the target release in the Aha! interface. Acts onfeature Permission (capability)None required VersionAvailable since the API’s base version Webhook event feature-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/features/{id} | Update a feature, including its name, description, status, epic, goals, release, score, tags, or watchers. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the feature. Acts onfeature Permission (capability)None required VersionAvailable since the API’s base version Webhook event feature-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/features/{id}/custom_fields | Update a feature's custom field values. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the feature. Acts onfeature Permission (capability)None required VersionAvailable since the API’s base version Webhook event feature-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/features/{id} | Delete a feature. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to delete the feature; this removes it permanently. Acts onfeature Permission (capability)None required VersionAvailable since the API’s base version Webhook event feature-destroyedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IdeasList and search ideas in a product, read a single idea, and create an idea in an ideas portal.3 | ||||||
| GET | /api/v1/products/{product_id}/ideas | List ideas in a product, with filters such as a search term. | read | — | Current | |
Aha! has no per-endpoint API scopes. The token reaches ideas in products the user can access. Acts onidea Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/ideas/{id} | Get a specific idea by its reference number or id. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own view permission for the idea. Acts onidea Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/portals/{portal_id}/ideas | Create an idea in a specific ideas portal. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to submit ideas to the target portal. Acts onidea Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InitiativesList, read, create, update, and delete strategic initiatives.5 | ||||||
| GET | /api/v1/initiatives | List initiatives, optionally filtered by goal, product, workflow status, or custom field. | read | — | Current | |
Aha! has no per-endpoint API scopes. The token reaches initiatives the user can see. Acts oninitiative Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/initiatives/{id} | Get a specific initiative. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own view permission. Acts oninitiative Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/products/{product_id}/initiatives | Create an initiative in a product. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the product's strategy. Acts oninitiative Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/initiatives/{id} | Update an initiative. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the initiative. Acts oninitiative Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/initiatives/{id} | Delete an initiative. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to delete the initiative; this removes it permanently. Acts oninitiative Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReleasesList, read, create, update, and delete releases in a product.5 | ||||||
| GET | /api/v1/products/{product_id}/releases | List releases in a product. | read | — | Current | |
Aha! has no per-endpoint API scopes. The token reaches releases in products the user can access. Acts onrelease Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/releases/{id} | Get a specific release. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own view permission. Acts onrelease Permission (capability)None required VersionAvailable since the API’s base version Webhook event release-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/products/{product_id}/releases | Create a release in a product. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the product. Acts onrelease Permission (capability)None required VersionAvailable since the API’s base version Webhook event release-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/releases/{id} | Update a release. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the release. Acts onrelease Permission (capability)None required VersionAvailable since the API’s base version Webhook event release-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/releases/{id} | Delete a release. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to delete the release; this removes it permanently. Acts onrelease Permission (capability)None required VersionAvailable since the API’s base version Webhook event release-destroyedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EpicsList, read, create, update, and delete epics.5 | ||||||
| GET | /api/v1/epics | List epics, optionally filtered by release, product, goal, initiative, tag, assignee, workflow status, or custom field. | read | — | Current | |
Aha! has no per-endpoint API scopes. The token reaches epics the user can see. Acts onepic Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/epics/{id} | Get a specific epic. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own view permission. Acts onepic Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/releases/{release_id}/epics | Create an epic in a release. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the target release. Acts onepic Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/epics/{id} | Update an epic. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the epic. Acts onepic Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/epics/{id} | Delete an epic. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to delete the epic; this removes it permanently. Acts onepic Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RequirementsRead, create, update, and delete the requirements that belong to a feature.5 | ||||||
| GET | /api/v1/features/{feature_id}/requirements | List the requirements that belong to a feature. | read | — | Current | |
Aha! has no per-endpoint API scopes. The token reaches requirements on features the user can see. Acts onrequirement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/requirements/{id} | Get a specific requirement. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own view permission. Acts onrequirement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/features/{feature_id}/requirements | Create a requirement on a feature. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the parent feature. Acts onrequirement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/requirements/{id} | Update a requirement. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the requirement. Acts onrequirement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/requirements/{id} | Delete a requirement. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to delete the requirement; this removes it permanently. Acts onrequirement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GoalsList, read, create, update, and delete goals (strategic imperatives).5 | ||||||
| GET | /api/v1/goals | List goals across the account. | read | — | Current | |
Aha! has no per-endpoint API scopes. The token reaches goals the user can see. Acts ongoal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/goals/{id} | Get a specific goal. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own view permission. Acts ongoal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/products/{product_id}/goals | Create a goal in a product. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the product's strategy. Acts ongoal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/goals/{id} | Update a goal. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the goal. Acts ongoal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/goals/{id} | Delete a goal. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to delete the goal; this removes it permanently. Acts ongoal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProductsList the products (workspaces) in an account and read a single product.2 | ||||||
| GET | /api/v1/products | List the products (workspaces) in the account. | read | — | Current | |
Aha! has no per-endpoint API scopes. The token reaches products the user is a member of. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/products/{id} | Get a specific product. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own membership of the product. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
To-dosList, read, create, update, and delete to-dos and approvals.5 | ||||||
| GET | /api/v1/to-dos | List to-dos, optionally filtered by assignee, feature, release, epic, idea, requirement, or product. | read | — | Current | |
Aha! has no per-endpoint API scopes. The token reaches to-dos the user can see. Acts onto-do Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/to-dos/{id} | Get a specific to-do. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own view permission. Acts onto-do Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/features/{feature_id}/to-dos | Create a to-do associated with a record, such as a feature. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the associated record. Acts onto-do Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/to-dos/{id} | Update a to-do, including its status to mark it complete. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to edit the to-do. Acts onto-do Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/to-dos/{id} | Delete a to-do. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to delete the to-do; this removes it permanently. Acts onto-do Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommentsRead and create comments on a feature, idea, requirement, release, goal, epic, or initiative.2 | ||||||
| POST | /api/v1/features/{feature_id}/comments | Create a comment on a feature. | write | — | Current | |
Aha! has no per-endpoint API scopes. The user must be able to comment on the feature. Comments can also be created on epics, requirements, ideas, initiatives, goals, releases, release phases, and to-dos. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/features/{feature_id}/comments | List the comments on a feature. | read | — | Current | |
Aha! has no per-endpoint API scopes. Access follows the user's own view permission for the feature. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom fieldsList the custom fields defined in the account and the options for a custom field.2 | ||||||
| GET | /api/v1/custom_fields | List all custom fields defined in the account. | read | — | Current | |
Aha! has no per-endpoint API scopes. Custom fields are defined by record type and shared across all workspaces in the account. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/custom_fields/{key}/custom_field_options | List the options for a custom field that has a choice list or tags. | read | — | Current | |
Aha! has no per-endpoint API scopes. Returns the available options for fields such as choice lists and tags. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Aha! can notify an app or AI agent when a record changes, instead of the app repeatedly asking. An activity webhook posts a JSON payload to a registered URL whenever a record is created, updated, or destroyed.
| Event | What it signals | Triggered by |
|---|---|---|
create (feature) | Fires when a feature is created. The activity webhook sends an audit payload with the action, the feature id, the user, and the changed fields. | /api/v1/releases/{release_id}/features |
update (feature) | Fires when a feature is updated. The payload carries only the fields that changed, not the whole record. | /api/v1/features/{id}/api/v1/features/{id}/custom_fields |
destroy (feature) | Fires when a feature is deleted. | /api/v1/features/{id} |
create (release) | Fires when a release is created. | /api/v1/products/{product_id}/releases |
update (release) | Fires when a release is updated, carrying only the changed fields. | /api/v1/releases/{id} |
destroy (release) | Fires when a release is deleted. | /api/v1/releases/{id} |
Aha! limits how fast an app or AI agent can call through a per-account quota, counted across every key on the account, with the current state returned in response headers and an over-limit request answered with a 429.
Aha! caps requests per account, not per key, so several keys or users on the same account share one quota. The ceilings are up to 300 requests per minute and up to 20 requests per second; exceeding either in its window returns a 429. The response carries X-Ratelimit-Limit, X-Ratelimit-Remaining, and X-Ratelimit-Reset headers, where X-Ratelimit-Reset is the UTC unix time the limit clears and the request can safely be retried. Aha! also asks that each request send a descriptive User-Agent header with a way to contact the developer, so it can reach the client if it sees a problem.
List endpoints return a pagination object with total_records, total_pages, and current_page. The page is chosen with the page query parameter and its size with per_page, which defaults to 30 records and tops out at 200.
Requests and responses are JSON. There is no single documented overall payload size limit; large result sets are split across pages of at most 200 records each.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request is malformed, such as an invalid parameter or body. | Correct the request structure and resend. |
| 403 | Forbidden | The authentication information is incorrect: a missing, wrong, or revoked token, or a token that does not belong to the account's host. | Check the Authorization header and that the token is valid for {account}.aha.io. |
| 404 | Not Found | The record does not exist, or the user behind the token cannot see it. | Confirm the path and id, and that the user has access to the record. |
| 429 | Too Many Requests | A rate limit was exceeded: more than 300 requests in a minute or more than 20 in a second, counted per account. | Wait until the X-Ratelimit-Reset unix time, then retry. |
| 500 | Internal Server Error | An unexpected error occurred on the Aha! side while handling the request. | Retry after a short delay; if it persists, contact Aha! support. |
| 504 | Gateway Timeout | The request took too long for Aha! to complete. | Narrow the request, such as paging smaller result sets, and retry. |
The Aha! REST API is served under a single major version, v1, in the path. New record types and fields are added to v1 without minting a new version string, so an integration built on v1 keeps working as the API grows.
Aha! launched its own MCP (Model Context Protocol) server across the Aha! suite, served on the account's host at {account}.aha.io/api/v1/mcp. It lets an AI assistant read, search, analyze, create, and update records the connected user can access, governed by AI controls in account settings, and it cannot delete records. This added a new connection route on top of the existing v1 REST API without changing the REST surface. Announced 20 May 2026.
The Aha! REST API is served under one major version, v1, carried in the path at {account}.aha.io/api/v1. Aha! adds new record types, endpoints, and fields to v1 over time rather than publishing dated, breaking versions, so an integration written against v1 keeps working as the surface grows. There is no version header to pin and no separate version timeline published.
There is one current major version, v1; changes are additive rather than dated breaking versions.
Aha! API documentation ↗Bollard AI sits between a team's AI agents and Aha!. Grant each agent exactly the access it needs, read or write, record type by record type, and every call is checked and logged.