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.

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)

Overview

API Resources