Aha! REST API


Aha! provides a REST API that can be accessed directly from another web application or from within a Javascript single page application. The API can be used from any programming language.

This API should be used if you want to create new data in Aha! or extract data from Aha!. If you want to integrate Aha! workflow with another system then you should first consider our service integration framework.

Please email support@aha.io if you have questions or need help while using the API.

URLs

All API access is over HTTPS. HTTP requests will be redirected to HTTPS. The API should be accessed using the account specific domain <yourcompany>.aha.io. If the account specific domain cannot be used, then the API can be accessed via secure.aha.io and the account part of the domain should be specified in the X-AHA-ACCOUNT header, e.g.

X-AHA-ACCOUNT: yourcompany

Authentication

All API requests must be appropriately authenticated. Two authentication methods are supported. If you have a choice, Oauth2 is the preferred technique since it avoids the need to provide your Aha! credentials to an external application.

OAuth2 token

Before using an Oauth2 token to authenticate an API call the external application must be registered and the user must authorize the external application to access their account.

Once the user has authorized the application, the OAuth2 acccess token can be included in the header of the API request:

curl -H "Authorization: Bearer 1111111111" https://company.aha.io/api/v1/features/APP-1

or passed as a parameter:

curl https://company.aha.io/api/v1/features/APP-1?access_token=1111111111

HTTP basic authentication

The username and password of the user are included directly in the request.

curl -u "username@company.com:mypassword" https://company.aha.io/api/v1/features/APP-1

Pagination

If a request returns multiple items then the result will be paginated. The response includes pagination fields which describe how many records exist in the collection, and which page has been returned, e.g.

{
  "pagination": [
    {
      "total_records": 2,
      "total_pages": 1,
      "current_page": 1
    }
  ],
  "features": [
    {
      "reference_num": "APP-1",
      "name": "Add buttons everywhere",
      "id": "5938362174479841842"
    },
    {
      "reference_num": "APP-2",
      "name": "Second feature",
      "id": "5938399016717176704"
    }
  ]
}

To request a specific page of results pass the page parameter. The per_page parameter can be optionally used to change the number of records returned in each page.

curl https://company.aha.io/api/v1/releases/APP-R-1/features?page=2

Errors

Possible error status codes are:

  • 403 - the authentication information is incorrect.
  • 400 - there is an error in the construction of the request. The body of the response will contain more detail of the problem.
  • 404 - the requested record could not be found. This may also occur if the user does not have access to the requested record.
  • 500 - something went wrong on the server. This error should not occur. If it does please report the problem to support@aha.io.

Response Customization

It is possible to customize which fields will be included in the JSON returned for all API requests. This can be useful to include more fields in a list of records, or to reduce the information returned so that the API result is returned faster. The most common use case is to request additional fields in a list result to avoid the need to make a subsequent request for information about each record in the list.

To specify the desired fields include a query parameter with the name fields and a value corresponding to a list of the desired fields separated by commas. For example this parameter

fields=name,reference_num,workflow_status

will include only the name, reference number and status in the returned result.

All fields can be requested using the query parameter:

fields=*

This is not recommended in a production application because it can significantly slow down API responses. It can be useful during development to see all available fields.

Generally the value to use in the fields parameter is the name of the JSON attribute that you want to have included.

Including a fields parameter will override the default fields that are included in the result and only the requested fields will be returned.

User agent

Each request should contain a customized User-Agent header that includes a method of contacting the developer. We will use this if we observe any problems with your API client.

User-Agent: Test data generation script (chris@aha.io)

Notification Email Suppression

Creation of many records in Aha! will trigger email notifications to be sent. This may be undesirable if you are using the API to import records from other systems. Many email notifications can be disabled by including disable_mailers=true in the request parameters.

Overview

API Resources