Getting Started with the Platform API

Last updated June 14, 2023

Prerequisites
Samples
Authentication
Calling the API
Alternatives
Wrap-up

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.

Prerequisites

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

Samples

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:

Authentication

Authentication is passed in the Authorization header with a value set to Bearer {token}.

If you are using curl and are logged in with the Heroku CLI, you can use curl -n to automatically set this header to the same token as the CLI. This token can also be retrieved with heroku auth:token, however it is only valid for a maximum of 1 year by default.

You can create a non-expiring token by running heroku authorizations:create:

$ heroku authorizations:create -d "getting started token"
Creating OAuth Authorization... done
Client:      <none>
ID:          a6e98151-f242-4592-b107-25fbac5ab410
Description: getting started token
Scope:       global
Token:       cf0e05d9-4eca-4948-a012-b91fe9704bab
Updated at:  Fri Jun 01 2018 13:26:56 GMT-0700 (PDT) (less than a minute ago)

Note for Federated Users

If you use SSO (your user account is associated with an Identity Provider) and attempt to create a non-expiring token, you will encounter the following error message: "This account is a federated account. Federated accounts cannot issue OAuth authorizations."

If you’d like to connect to the API and want to do so via non-expiring token, we recommend you create a separate user, invite them to your Heroku organization, but not add them to your Identity Provider. That user can then generate and manager tokens used by your organization.

Calling the API

Here is how to create an app with curl using the token from the netrc file:

$ curl -nX POST https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"

Alternatively, to create an app with an API key created with heroku authorizations:create and stored in the HEROKU_API_KEY environment variable:

$ curl -X POST https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer $HEROKU_API_KEY"

On Windows it would be defined like this:

> curl -X POST https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer %HEROKU_API_KEY%"

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

{
  "created_at":"2013-05-21T22:36:48-00:00",
  "id":"01234567-89ab-cdef-0123-456789abcdef",
  "git_url":"git@heroku.com:cryptic-ocean-8852.git",
  "name":"cryptic-ocean-8852",
  ...
}

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

$ curl -nX GET https://api.heroku.com/apps/01234567-89ab-cdef-0123-456789abcdef \
-H "Accept: application/vnd.heroku+json; version=3"

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

$ curl -nX GET https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"

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 -nX PATCH https://api.heroku.com/apps/01234567-89ab-cdef-0123-456789abcdef \
-H "Accept: application/vnd.heroku+json; version=3" \
-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 -n https://api.heroku.com/apps/my-awesome-app \
-H "Accept: application/vnd.heroku+json; version=3"

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

$ curl -nX DELETE https://api.heroku.com/apps/01234567-89ab-cdef-0123-456789abcdef \
-H "Accept: application/vnd.heroku+json; version=3"

Alternatives

The Heroku API plugin can be used to make arbitrary commands to the CLI:

$ heroku plugins:install api
$ heroku api POST /apps --body '{"name": "example-app"}'
POST api.heroku.com/apps... 201
{
  "name": "example-app",
  "region": {
    "id": "59accabd-516d-4f0e-83e6-6e3757701145",
    "name": "us"
  },
  "updated_at": "2018-06-01T21:00:41Z",
  "web_url": "https://example-app-1234567890ab.herokuapp.com/",
  ...
}

httpie is a useful cURL replacement that is a bit more user friendly. It automatically uses the authentication credential from netrc and it assumes you’re POSTing JSON by default:

$ http PATCH https://api.heroku.com/apps/example-app/config-vars \
"Accept:application/vnd.heroku+json; version=3" \
RAILS_ENV=production
HTTP/1.1 200 OK
Cache-Control: private, no-cache
Content-Encoding: gzip
Content-Length: 672
Content-Type: application/json
...
{
    "DATABASE_URL": "postgres://pg",
    "RAILS_ENV": "production"
}

Wrap-up

This tutorial demonstrates how to call the Heroku Platform API 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.

Keep reading

Platform API

Categories