Getting Started with the Platform API

Last Updated: 28 October 2014


Table of Contents

This is a brief guide to help you get started with the Heroku Platform API. For a detailed reference, please see the Platform API Reference article.

If you have questions about the Heroku API, consider posting in the Heroku API forum.


  1. A shell with curl
  2. A Heroku user account. Signup is free and instant.


The samples below use curl simply for convenience. We recommend using your favorite programming language and a HTTP library with the API.

Alternatively, several client libraries are available, including platform-api for Ruby, node-heroku-client, Heroku.scala and heroku-go.


Authentication is passed in the Authorization header with a value set to :{token}, base64 encoded. You can find a token to use on the “Account” page (in the “API Key” section) on your dashboard or by running this command:

$ heroku auth:token

If you are using curl and the Heroku toolbelt, then curl can handle authentication details by reading the netrc file as demonstrated in the reference. The computation is included here for demonstration purposes.

Here’s how to generate the header value with Bash and store it in the $TUTORIAL_KEY var:

$ TUTORIAL_KEY=`heroku auth:token` ; echo $TUTORIAL_KEY

Calling the API

With the Authorization value in place, you can call the API. First create an app:

$ curl -X POST \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer $TUTORIAL_KEY"

Note that we pass two headers, Authorization to authenticate and Accept to specify API version.

The API returns JSON with details of the newly created app:


You can also query the API for info on the app you created by passing the id in the path:

$ curl -X GET \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer $TUTORIAL_KEY"

You can also list all the apps that you own or collaborate on:

$ curl -X GET \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer $TUTORIAL_KEY"

Let’s update the name of the app we created above by making a PATCH request to the same path you used for info:

$ curl -X PATCH \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer $TUTORIAL_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\":\"my-awesome-app\"}"

You can also use the name to query the app, which is especially handy when you have changed it to something more memorable:

$ curl \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer $TUTORIAL_KEY"

Finally, you can clean up and delete the test app:

$ curl -X DELETE \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer $TUTORIAL_KEY"


This tutorial demonstrates how to call the Heroku Platform API from Bash and using curl, but you can transfer this approach to whatever language and environment you favor. The tutorial focused specifically on creating, updating and deleting apps. The API has many more resources available, including add-ons, config vars and domains. They all work quite similarly to apps and detailed information can be found in the API reference.