This documentation is no longer supported, please refer to the platform API reference.

This API will be sunset on April 15, 2017.


Authentication to the Heroku API is accomplished using an API key, available on the My Account page.

Once you have an API key, use HTTP Basic Authentication with a blank username and the API key as a password. Here's an example using curl (the colon separates username and password):

curl -H "Accept: application/json" -u :apikeyhere


An Accept header that contains either application/json or application/xml is required to use the API.

To list all of your apps in XML, use this curl command:

curl -H "Accept: application/xml" -u :apikeyhere

Response Codes

200 OK

Request succeeded, response contains requested data.

401 Unauthorized

You are attempting to access the API with invalid credentials.

402 Payment Required

You must confirm your billing info to use this API.

403 Forbidden

Your access level does not permit this API call.

404 Not Found

The API endpoint or resource you are attempting to fetch does not exist.

412 Precondition Failed

This API has been deprecated.

422 Unprocessable Entity

An error has occurred, see response body for details.

423 Locked

This API command requires confirmation. Pass the app name as a confirm parameter.

Error Responses


{ "error": "The error message" }


<?xml version="1.0">
  <error>The error message</error>