View categories

Categories

Getting Started with the Platform API

Last updated May 27, 2025

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

Prerequisites

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

Samples

The samples below usecurl 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 theAuthorization header with a value set toBearer {token}.

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

You can create a non-expiring token by runningheroku authorizations:create:

$ heroku authorizations:create -d "getting started token"Creating OAuth Authorization... doneClient:      <none>ID:          a6e98151-f242-4592-b107-25fbac5ab410Description: getting started tokenScope:       globalToken:       cf0e05d9-4eca-4948-a012-b91fe9704babUpdated 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 want to connect to the API via non-expiring token, we recommend creating a separate user, inviting them to your Heroku organization, but not adding them to your identity provider. That user can then generate and manage 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 withheroku authorizations:create and stored in theHEROKU_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

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

$ heroku plugins:install @heroku-cli/plugin-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=productionHTTP/1.1 200 OKCache-Control: private, no-cacheContent-Encoding: gzipContent-Length: 672Content-Type: application/json...{    "DATABASE_URL": "postgres://pg",    "RAILS_ENV": "production"}

Wrap-up

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