Platform API Reference

Last updated 07 August 2018

Overview

The platform API empowers developers to automate, extend and combine Heroku with other services. You can use the platform API to programmatically create apps, provision add-ons and perform other tasks that could previously only be accomplished with the Heroku CLI or Dashboard. For details on getting started, see Getting Started with the Platform API.

Authentication

OAuth should be used to authorize and revoke access to your account to yourself and third parties. Details can be found in the OAuth article.

For personal scripts you may also use HTTP bearer authentication, but OAuth is recommended for any third party services. HTTP bearer authentication must be constructed using an API token, passed as the Authorization header for each request, for example Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef. The quick start guide has more details.

Caching

All responses include an ETag (or Entity Tag) header, identifying the specific version of a returned resource. You may use this value to check for changes to a resource by repeating the request and passing the ETag value in the If-None-Match header. If the resource has not changed, a 304 Not Modified status will be returned with an empty body. If the resource has changed, the request will proceed normally.

Clients

Clients must address requests to api.heroku.com using HTTPS and specify the Accept: application/vnd.heroku+json; version=3 Accept header. Clients should specify a User-Agent header to facilitate tracking and debugging.

CORS

The Platform API supports cross-origin resource sharing (CORS) so that requests can be sent from browsers using JavaScript served from any domain.

Schema

The API has a machine-readable JSON schema that describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. You can access the schema using cURL:

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

{
  "description": "The platform API empowers developers to automate, extend and combine Heroku with other services.",
  "definitions": {
  ...
  }
}

cURL Examples

cURL examples are provided to facilitate experimentation. Variable values are represented as $SOMETHING so that you can manipulate them using environment variables. Examples use the -n option to fetch credentials from a ~/.netrc file, which should include an entry for api.heroku.com similar to the following:

machine api.heroku.com
  login {your-email}
  password {your-api-token}

Because Heroku’s V3 API is only accessible through HTTP Accept header, it may also be convenient to create a cURL alias for easy access:

alias c3='curl -n -H "Accept: application/vnd.heroku+json; version=3"'

Custom Types

Data Integrity

Both unique id and more human-friendly attributes can be used reference resources. For example you can use name or id to refer to an app. Though the human-friendly version may be more convenient, id should be preferred to avoid ambiguity.

You may pass the If-Match header with an ETag value from a previous response to ensure a resource has not changed since you last received it. If the resource has changed, you will receive a 412 Precondition Failed response. If the resource has not changed, the request will proceed normally.

Errors

Failing responses will have an appropriate status and a JSON body containing more details about a particular error. See error responses for more example ids.

Error Attributes

Note that the url is included only when relevant and may not be present in the response.

Error Response

HTTP/1.1 429 Too Many Requests

{
  "id":       "rate_limit",
  "message":  "Your account reached the API rate limit\nPlease wait a few minutes before making new requests",
  "url":      "https://devcenter.heroku.com/articles/platform-api-reference#rate-limits"
}

Escaping

Some attributes are text fields. Those fields will not be escaped to prevent XSS flaws. It is up to the client to escape that data.

Methods

Method Override

When using a client that does not support all of the methods, you can override by using a POST and setting the X-Http-Method-Override header to the desired methed. For instance, to do a PATCH request, do a POST with header X-Http-Method-Override: PATCH.

Parameters

Values that can be provided for an action are divided between optional and required values. The expected type for each value is specified and unlisted values should be considered immutable. Parameters should be JSON encoded and passed in the request body.

Ranges

List requests will return a Content-Range header indicating the range of values returned. Large lists may require additional requests to retrieve. If a list response has been truncated you will receive a 206 Partial Content status and the Next-Range header set. To retrieve the next range, repeat the request with the Range header set to the value of the previous request’s Next-Range header.

The number of values returned in a range can be controlled using a max key in the Range header. For example, to get only the first 10 values, set this header: Range: id ..; max=10;. max can also be passed when iterating over Next-Range. The default page size is 200 and maximum page size is 1000.

The property used to sort values in a list response can be changed. The default property is id, as in Range: id ..;. To learn what other properties you can use to sort a list response, inspect the Accept-Ranges headers. For the apps resource, for example, you can sort on either id or name:

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

...
Accept-Ranges: id, name
...

The default sort order for resource lists responses is ascending. You can opt for descending sort order by passing a order key in the range header:

$ curl -i -n -X GET https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3" -H "Range: name ..; order=desc;"

Combining with the max key would look like this:

$ curl -i -n -X GET https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Range: name ..; order=desc,max=10;"

Rate Limits

The API limits the number of requests each user can make per hour to protect against abuse and buggy code. Each account has a pool of request tokens that can hold at most 4500 tokens. Each API call removes one token from the pool. Tokens are added to the account pool at a rate of roughly 75 per minute (or 4500 per hour), up to a maximum of 4500. If no tokens remain, further calls will return 429 Too Many Requests until more tokens become available.

You can use the RateLimit-Remaining response header to check your current token count. You can also query the rate limit endpoint to get your token count. Requests to the rate limit endpoint do not count toward the limit. If you find your account is being rate limited but don’t know the cause, consider cycling your API key on the account page on Heroku dashboard.

Request Id

Each API response contains a unique request id in the Request-Id header to facilitate tracking. When reporting issues, providing this value makes it easier to pinpoint problems and provide solutions more quickly.

Responses

Values returned by the API are split into a section with example status code and relevant headers (with common http headers omitted) and a section with an example JSON body (if any).

Response Headers

Stability

Each resource in the Heroku Platform API Schema is annotated with a stability attribute, which will be set to one of three values: prototype, development, or production. This attribute reflects the change management policy in place for the resource. For a full explanation of these policies, please see the Dev Center API compatibility article.

Statuses

The result of responses can be determined by returned status.

Successful Responses

Error Responses

Error responses can be divided in to two classes. Client errors result from malformed requests and should be addressed by the client. Heroku errors result from problems on the server side and must be addressed internally.

Client Error Responses

Heroku Error Responses

Versioning

The current version of the API is version 3. See the API compatibility policy article for details on versioning.

Account

Stability: production

An account represents an individual signed up to use the Heroku platform.

Attributes

Account Info

Info for account.

GET /account

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "organization": {
      "name": "example"
    },
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "sms_number": "+1 ***-***-1234",
  "suspended_at": "2012-01-01T12:00:00Z",
  "delinquent_at": "2012-01-01T12:00:00Z",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false,
  "default_organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  }
}

Account Update

Update account.

PATCH /account

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/account \
  -d '{
  "allow_tracking": true,
  "beta": false,
  "name": "Tina Edmonds"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "organization": {
      "name": "example"
    },
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "sms_number": "+1 ***-***-1234",
  "suspended_at": "2012-01-01T12:00:00Z",
  "delinquent_at": "2012-01-01T12:00:00Z",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false,
  "default_organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  }
}

Account Delete

Delete account. Note that this action cannot be undone.

DELETE /account

Curl Example

$ curl -n -X DELETE https://api.heroku.com/account \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "organization": {
      "name": "example"
    },
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "sms_number": "+1 ***-***-1234",
  "suspended_at": "2012-01-01T12:00:00Z",
  "delinquent_at": "2012-01-01T12:00:00Z",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false,
  "default_organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  }
}

Account Info By User

Info for account.

GET /users/{account_email_or_id_or_self}

Curl Example

$ curl -n https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "organization": {
      "name": "example"
    },
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "sms_number": "+1 ***-***-1234",
  "suspended_at": "2012-01-01T12:00:00Z",
  "delinquent_at": "2012-01-01T12:00:00Z",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false,
  "default_organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  }
}

Account Update By User

Update account.

PATCH /users/{account_email_or_id_or_self}

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
  -d '{
  "allow_tracking": true,
  "beta": false,
  "name": "Tina Edmonds"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "organization": {
      "name": "example"
    },
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "sms_number": "+1 ***-***-1234",
  "suspended_at": "2012-01-01T12:00:00Z",
  "delinquent_at": "2012-01-01T12:00:00Z",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false,
  "default_organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  }
}

Account Delete By User

Delete account. Note that this action cannot be undone.

DELETE /users/{account_email_or_id_or_self}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "organization": {
      "name": "example"
    },
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "sms_number": "+1 ***-***-1234",
  "suspended_at": "2012-01-01T12:00:00Z",
  "delinquent_at": "2012-01-01T12:00:00Z",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false,
  "default_organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  }
}

Account Feature

Stability: production

An account feature represents a Heroku labs capability that can be enabled or disabled for an account on Heroku.

Attributes

Account Feature Info

Info for an existing account feature.

GET /account/features/{account_feature_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/account/features/$ACCOUNT_FEATURE_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "description": "Causes account to example.",
  "doc_url": "http://devcenter.heroku.com/articles/example",
  "enabled": true,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "name",
  "state": "public",
  "updated_at": "2012-01-01T12:00:00Z",
  "display_name": "My Feature",
  "feedback_email": "feedback@heroku.com"
}

Account Feature List

List existing account features.

Acceptable order values for the Range header are id or name.

GET /account/features

Curl Example

$ curl -n https://api.heroku.com/account/features \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "description": "Causes account to example.",
    "doc_url": "http://devcenter.heroku.com/articles/example",
    "enabled": true,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "name",
    "state": "public",
    "updated_at": "2012-01-01T12:00:00Z",
    "display_name": "My Feature",
    "feedback_email": "feedback@heroku.com"
  }
]

Account Feature Update

Update an existing account feature.

PATCH /account/features/{account_feature_id_or_name}

Required Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/account/features/$ACCOUNT_FEATURE_ID_OR_NAME \
  -d '{
  "enabled": true
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "description": "Causes account to example.",
  "doc_url": "http://devcenter.heroku.com/articles/example",
  "enabled": true,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "name",
  "state": "public",
  "updated_at": "2012-01-01T12:00:00Z",
  "display_name": "My Feature",
  "feedback_email": "feedback@heroku.com"
}

Add-on

Stability: production

Add-ons represent add-ons that have been provisioned and attached to one or more apps.

Attributes

Add-on List

List all existing add-ons.

Acceptable order values for the Range header are id or name.

GET /addons

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "actions": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "label": "Example",
      "action": "example",
      "url": "http://example.com?resource_id=:resource_id",
      "requires_owner": true
    },
    "addon_service": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql"
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "billed_price": {
      "cents": 0,
      "contract": false,
      "unit": "month"
    },
    "config_vars": [
      "FOO",
      "BAZ"
    ],
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "plan": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql:dev"
    },
    "provider_id": "abcd1234",
    "state": "provisioned",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
  }
]

Add-on Info

Info for an existing add-on.

GET /addons/{add_on_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "billed_price": {
    "cents": 0,
    "contract": false,
    "unit": "month"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on Create

Create a new add-on.

POST /apps/{app_id_or_name}/addons

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/addons \
  -d '{
  "attachment": {
    "name": "DATABASE_FOLLOWER"
  },
  "config": {
    "db-version": "1.2.3"
  },
  "confirm": "example",
  "plan": "01234567-89ab-cdef-0123-456789abcdef"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "billed_price": {
    "cents": 0,
    "contract": false,
    "unit": "month"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on Delete

Delete an existing add-on.

DELETE /apps/{app_id_or_name}/addons/{add_on_id_or_name}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADD_ON_ID_OR_NAME \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "billed_price": {
    "cents": 0,
    "contract": false,
    "unit": "month"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on Info By App

Info for an existing add-on.

GET /apps/{app_id_or_name}/addons/{add_on_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADD_ON_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "billed_price": {
    "cents": 0,
    "contract": false,
    "unit": "month"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on List By App

List existing add-ons for an app.

Acceptable order values for the Range header are id or name.

GET /apps/{app_id_or_name}/addons

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "actions": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "label": "Example",
      "action": "example",
      "url": "http://example.com?resource_id=:resource_id",
      "requires_owner": true
    },
    "addon_service": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql"
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "billed_price": {
      "cents": 0,
      "contract": false,
      "unit": "month"
    },
    "config_vars": [
      "FOO",
      "BAZ"
    ],
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "plan": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql:dev"
    },
    "provider_id": "abcd1234",
    "state": "provisioned",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
  }
]

Add-on Update

Change add-on plan. Some add-ons may not support changing plans. In that case, an error will be returned.

PATCH /apps/{app_id_or_name}/addons/{add_on_id_or_name}

Required Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADD_ON_ID_OR_NAME \
  -d '{
  "plan": "01234567-89ab-cdef-0123-456789abcdef"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "billed_price": {
    "cents": 0,
    "contract": false,
    "unit": "month"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on List By User

List all existing add-ons a user has access to

Acceptable order values for the Range header are id or name.

GET /users/{account_email_or_id_or_self}/addons

Curl Example

$ curl -n https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF/addons \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "actions": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "label": "Example",
      "action": "example",
      "url": "http://example.com?resource_id=:resource_id",
      "requires_owner": true
    },
    "addon_service": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql"
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "billed_price": {
      "cents": 0,
      "contract": false,
      "unit": "month"
    },
    "config_vars": [
      "FOO",
      "BAZ"
    ],
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "plan": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql:dev"
    },
    "provider_id": "abcd1234",
    "state": "provisioned",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
  }
]

Add-on List By Team

List add-ons used across all Team apps

Acceptable order values for the Range header are id or name.

GET /teams/{team_name_or_id}/addons

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/addons \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "actions": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "label": "Example",
      "action": "example",
      "url": "http://example.com?resource_id=:resource_id",
      "requires_owner": true
    },
    "addon_service": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql"
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "billed_price": {
      "cents": 0,
      "contract": false,
      "unit": "month"
    },
    "config_vars": [
      "FOO",
      "BAZ"
    ],
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "plan": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql:dev"
    },
    "provider_id": "abcd1234",
    "state": "provisioned",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
  }
]

Add-on Action

Stability: development

Add-on Actions are lifecycle operations for add-on provisioning and deprovisioning. They allow whitelisted add-on providers to (de)provision add-ons in the background and then report back when (de)provisioning is complete.

Add-on Action Provision

Mark an add-on as provisioned for use.

POST /addons/{add_on_id_or_name}/actions/provision

Curl Example

$ curl -n -X POST https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/actions/provision \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "billed_price": {
    "cents": 0,
    "contract": false,
    "unit": "month"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on Action Deprovision

Mark an add-on as deprovisioned.

POST /addons/{add_on_id_or_name}/actions/deprovision

Curl Example

$ curl -n -X POST https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/actions/deprovision \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actions": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "label": "Example",
    "action": "example",
    "url": "http://example.com?resource_id=:resource_id",
    "requires_owner": true
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "billed_price": {
    "cents": 0,
    "contract": false,
    "unit": "month"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "acme-inc-primary-database",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "abcd1234",
  "state": "provisioned",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on Attachment

Stability: prototype

An add-on attachment represents a connection between an app and an add-on that it has been given access to.

Attributes

Add-on Attachment Create

Create a new add-on attachment.

POST /addon-attachments

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/addon-attachments \
  -d '{
  "addon": "01234567-89ab-cdef-0123-456789abcdef",
  "app": "01234567-89ab-cdef-0123-456789abcdef",
  "confirm": "example",
  "name": "DATABASE",
  "namespace": "role:analytics"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "DATABASE",
  "namespace": "role:analytics",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on Attachment Delete

Delete an existing add-on attachment.

DELETE /addon-attachments/{add_on_attachment_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/addon-attachments/$ADD_ON_ATTACHMENT_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "DATABASE",
  "namespace": "role:analytics",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on Attachment Info

Info for existing add-on attachment.

GET /addon-attachments/{add_on_attachment_id}

Curl Example

$ curl -n https://api.heroku.com/addon-attachments/$ADD_ON_ATTACHMENT_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "DATABASE",
  "namespace": "role:analytics",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on Attachment List

List existing add-on attachments.

The only acceptable order value for the Range header is id.

GET /addon-attachments

Curl Example

$ curl -n https://api.heroku.com/addon-attachments \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-inc-primary-database",
      "app": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      }
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "DATABASE",
    "namespace": "role:analytics",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
  }
]

Add-on Attachment List by Add-on

List existing add-on attachments for an add-on.

The only acceptable order value for the Range header is id.

GET /addons/{add_on_id_or_name}/addon-attachments

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/addon-attachments \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-inc-primary-database",
      "app": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      }
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "DATABASE",
    "namespace": "role:analytics",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
  }
]

Add-on Attachment List by App

List existing add-on attachments for an app.

The only acceptable order value for the Range header is id.

GET /apps/{app_id_or_name}/addon-attachments

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addon-attachments \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-inc-primary-database",
      "app": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      }
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "DATABASE",
    "namespace": "role:analytics",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
  }
]

Add-on Attachment Info by App

Info for existing add-on attachment for an app.

GET /apps/{app_id_or_name}/addon-attachments/{add_on_attachment_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addon-attachments/$ADD_ON_ATTACHMENT_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "DATABASE",
  "namespace": "role:analytics",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}

Add-on Config

Stability: development

Configuration of an Add-on

Attributes

Add-on Config List

Get an add-on’s config. Accessible by customers with access and by the add-on partner providing this add-on.

The only acceptable order value for the Range header is name.

GET /addons/{add_on_id_or_name}/config

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/config \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "name": "FOO",
    "value": "bar"
  }
]

Add-on Config Update

Update an add-on’s config. Can only be accessed by the add-on partner providing this add-on.

PATCH /addons/{add_on_id_or_name}/config

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/config \
  -d '{
  "config": [
    {
      "name": "FOO",
      "value": "bar"
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "name": "FOO",
    "value": "bar"
  }
]

Add-on Plan Action

Stability: development

Add-on Plan Actions are Provider functionality for specific add-on installations

Attributes

Add-on Region Capability

Stability: production

Add-on region capabilities represent the relationship between an Add-on Service and a specific Region. Only Beta and GA add-ons are returned by these endpoints.

Attributes

Add-on Region Capability List

List all existing add-on region capabilities.

The only acceptable order value for the Range header is id.

GET /addon-region-capabilities

Curl Example

$ curl -n https://api.heroku.com/addon-region-capabilities \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "supports_private_networking": true,
    "addon_service": {
      "cli_plugin_name": "heroku-papertrail",
      "created_at": "2012-01-01T12:00:00Z",
      "human_name": "Heroku Postgres",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql",
      "state": "ga",
      "supports_multiple_installations": false,
      "supports_sharing": false,
      "updated_at": "2012-01-01T12:00:00Z"
    },
    "region": {
      "country": "United States",
      "created_at": "2012-01-01T12:00:00Z",
      "description": "United States",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "locale": "Virginia",
      "name": "us",
      "private_capable": false,
      "provider": {
        "name": "amazon-web-services",
        "region": "us-east-1"
      },
      "updated_at": "2012-01-01T12:00:00Z"
    }
  }
]

Add-on Region Capability List by Add-on Service

List existing add-on region capabilities for an add-on-service

The only acceptable order value for the Range header is id.

GET /addon-services/{add_on_service_id_or_name}/region-capabilities

Curl Example

$ curl -n https://api.heroku.com/addon-services/$ADD_ON_SERVICE_ID_OR_NAME/region-capabilities \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "supports_private_networking": true,
    "addon_service": {
      "cli_plugin_name": "heroku-papertrail",
      "created_at": "2012-01-01T12:00:00Z",
      "human_name": "Heroku Postgres",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql",
      "state": "ga",
      "supports_multiple_installations": false,
      "supports_sharing": false,
      "updated_at": "2012-01-01T12:00:00Z"
    },
    "region": {
      "country": "United States",
      "created_at": "2012-01-01T12:00:00Z",
      "description": "United States",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "locale": "Virginia",
      "name": "us",
      "private_capable": false,
      "provider": {
        "name": "amazon-web-services",
        "region": "us-east-1"
      },
      "updated_at": "2012-01-01T12:00:00Z"
    }
  }
]

Add-on Region Capability List By Region

List existing add-on region capabilities for a region.

The only acceptable order value for the Range header is id.

GET /regions/{region_id_or_name}/addon-region-capabilities

Curl Example

$ curl -n https://api.heroku.com/regions/$REGION_ID_OR_NAME/addon-region-capabilities \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "supports_private_networking": true,
    "addon_service": {
      "cli_plugin_name": "heroku-papertrail",
      "created_at": "2012-01-01T12:00:00Z",
      "human_name": "Heroku Postgres",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql",
      "state": "ga",
      "supports_multiple_installations": false,
      "supports_sharing": false,
      "updated_at": "2012-01-01T12:00:00Z"
    },
    "region": {
      "country": "United States",
      "created_at": "2012-01-01T12:00:00Z",
      "description": "United States",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "locale": "Virginia",
      "name": "us",
      "private_capable": false,
      "provider": {
        "name": "amazon-web-services",
        "region": "us-east-1"
      },
      "updated_at": "2012-01-01T12:00:00Z"
    }
  }
]

Add-on Service

Stability: production

Add-on services represent add-ons that may be provisioned for apps. Endpoints under add-on services can be accessed without authentication.

Attributes

Add-on Service Info

Info for existing add-on-service.

GET /addon-services/{add_on_service_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/addon-services/$ADD_ON_SERVICE_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "cli_plugin_name": "heroku-papertrail",
  "created_at": "2012-01-01T12:00:00Z",
  "human_name": "Heroku Postgres",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "heroku-postgresql",
  "state": "ga",
  "supports_multiple_installations": false,
  "supports_sharing": false,
  "updated_at": "2012-01-01T12:00:00Z"
}

Add-on Service List

List existing add-on-services.

Acceptable order values for the Range header are id or name.

GET /addon-services

Curl Example

$ curl -n https://api.heroku.com/addon-services \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "cli_plugin_name": "heroku-papertrail",
    "created_at": "2012-01-01T12:00:00Z",
    "human_name": "Heroku Postgres",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql",
    "state": "ga",
    "supports_multiple_installations": false,
    "supports_sharing": false,
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Add-on Webhook

Stability: production

Represents the details of a webhook subscription

Attributes

Add-on Webhook Create

Create an add-on webhook subscription. Can only be accessed by the add-on partner providing this add-on.

POST /addons/{add_on_id_or_name}/webhooks

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks \
  -d '{
  "authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
  "url": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Add-on Webhook Delete

Removes an add-on webhook subscription. Can only be accessed by the add-on partner providing this add-on.

DELETE /addons/{add_on_id_or_name}/webhooks/{app_webhook_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Add-on Webhook Info

Returns the info for an add-on webhook subscription. Can only be accessed by the add-on partner providing this add-on.

GET /addons/{add_on_id_or_name}/webhooks/{app_webhook_id}

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Add-on Webhook List

List all webhook subscriptions for a particular add-on. Can only be accessed by the add-on partner providing this add-on.

GET /addons/{add_on_id_or_name}/webhooks

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-inc-primary-database"
    },
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": [
      "api:release"
    ],
    "level": "notify",
    "updated_at": "2015-01-01T12:00:00Z",
    "url": "example"
  }
]

Add-on Webhook Update

Updates the details of an add-on webhook subscription. Can only be accessed by the add-on partner providing this add-on.

PATCH /addons/{add_on_id_or_name}/webhooks/{app_webhook_id}

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
  -d '{
  "authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
  "url": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Add-on Webhook Delivery

Stability: production

Represents the delivery of a webhook notification, including its current status.

Add-on Webhook Delivery Info

Returns the info for an existing delivery. Can only be accessed by the add-on partner providing this add-on.

GET /addons/{add_on_id_or_name}/webhook-deliveries/{app_webhook_delivery_id}

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhook-deliveries/$APP_WEBHOOK_DELIVERY_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2015-01-01T12:00:00Z",
  "event": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": "api:release"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "num_attempts": 42,
  "next_attempt_at": "2015-01-01T12:00:00Z",
  "last_attempt": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "code": 42,
    "error_class": "example",
    "status": "scheduled",
    "created_at": "2015-01-01T12:00:00Z",
    "updated_at": "2015-01-01T12:00:00Z"
  },
  "status": "pending",
  "updated_at": "2015-01-01T12:00:00Z",
  "webhook": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "level": "notify"
  }
}

Add-on Webhook Delivery List

Lists existing deliveries for an add-on. Can only be accessed by the add-on partner providing this add-on.

GET /addons/{add_on_id_or_name}/webhook-deliveries

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhook-deliveries \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "event": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "include": "api:release"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "num_attempts": 42,
    "next_attempt_at": "2015-01-01T12:00:00Z",
    "last_attempt": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "code": 42,
      "error_class": "example",
      "status": "scheduled",
      "created_at": "2015-01-01T12:00:00Z",
      "updated_at": "2015-01-01T12:00:00Z"
    },
    "status": "pending",
    "updated_at": "2015-01-01T12:00:00Z",
    "webhook": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "level": "notify"
    }
  }
]

Add-on Webhook Event

Stability: production

Represents a webhook event that occurred.

Add-on Webhook Event Info

Returns the info for a specified webhook event. Can only be accessed by the add-on partner providing this add-on.

GET /addons/{add_on_id_or_name}/webhook-events/{app_webhook_event_id}

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhook-events/$APP_WEBHOOK_EVENT_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": "api:release",
  "payload": {
    "action": "create",
    "actor": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "data": null,
    "previous_data": null,
    "resource": "release",
    "version": "1"
  },
  "updated_at": "2015-01-01T12:00:00Z"
}

Add-on Webhook Event List

Lists existing webhook events for an add-on. Can only be accessed by the add-on partner providing this add-on.

GET /addons/{add_on_id_or_name}/webhook-events

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhook-events \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": "api:release",
    "payload": {
      "action": "create",
      "actor": {
        "email": "username@example.com",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      },
      "data": null,
      "previous_data": null,
      "resource": "release",
      "version": "1"
    },
    "updated_at": "2015-01-01T12:00:00Z"
  }
]

App

Stability: production

An app represents the program that you would like to deploy and run on Heroku.

Attributes

App Create

Create a new app.

POST /apps

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/apps \
  -d '{
  "name": "example",
  "region": "01234567-89ab-cdef-0123-456789abcdef",
  "stack": "01234567-89ab-cdef-0123-456789abcdef"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm": false,
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "https://git.heroku.com/example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "internal_routing": false,
  "maintenance": false,
  "name": "example",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "released_at": "2012-01-01T12:00:00Z",
  "repo_size": 0,
  "slug_size": 0,
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa",
    "shield": true
  },
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}

App Delete

Delete an existing app.

DELETE /apps/{app_id_or_name}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm": false,
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "https://git.heroku.com/example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "internal_routing": false,
  "maintenance": false,
  "name": "example",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "released_at": "2012-01-01T12:00:00Z",
  "repo_size": 0,
  "slug_size": 0,
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa",
    "shield": true
  },
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}

App Info

Info for existing app.

GET /apps/{app_id_or_name}

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm": false,
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "https://git.heroku.com/example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "internal_routing": false,
  "maintenance": false,
  "name": "example",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "released_at": "2012-01-01T12:00:00Z",
  "repo_size": 0,
  "slug_size": 0,
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa",
    "shield": true
  },
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}

App List

List existing apps.

Acceptable order values for the Range header are id, name or updated_at.

GET /apps

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name, updated_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "acm": false,
    "archived_at": "2012-01-01T12:00:00Z",
    "buildpack_provided_description": "Ruby/Rack",
    "build_stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar-14"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "git_url": "https://git.heroku.com/example.git",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "internal_routing": false,
    "maintenance": false,
    "name": "example",
    "owner": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "organization": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "region": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "us"
    },
    "released_at": "2012-01-01T12:00:00Z",
    "repo_size": 0,
    "slug_size": 0,
    "space": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "nasa",
      "shield": true
    },
    "stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar-14"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://example.herokuapp.com/"
  }
]

App List Owned and Collaborated

List owned and collaborated apps (excludes team apps).

Acceptable order values for the Range header are id, name or updated_at.

GET /users/{account_email_or_id_or_self}/apps

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name, updated_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "acm": false,
    "archived_at": "2012-01-01T12:00:00Z",
    "buildpack_provided_description": "Ruby/Rack",
    "build_stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar-14"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "git_url": "https://git.heroku.com/example.git",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "internal_routing": false,
    "maintenance": false,
    "name": "example",
    "owner": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "organization": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "region": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "us"
    },
    "released_at": "2012-01-01T12:00:00Z",
    "repo_size": 0,
    "slug_size": 0,
    "space": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "nasa",
      "shield": true
    },
    "stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar-14"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://example.herokuapp.com/"
  }
]

App Update

Update an existing app.

PATCH /apps/{app_id_or_name}

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME \
  -d '{
  "build_stack": "01234567-89ab-cdef-0123-456789abcdef",
  "maintenance": false,
  "name": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm": false,
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "https://git.heroku.com/example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "internal_routing": false,
  "maintenance": false,
  "name": "example",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "released_at": "2012-01-01T12:00:00Z",
  "repo_size": 0,
  "slug_size": 0,
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa",
    "shield": true
  },
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}

App Enable ACM

Enable ACM flag for an app

POST /apps/{app_id_or_name}/acm

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/acm \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm": false,
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "https://git.heroku.com/example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "internal_routing": false,
  "maintenance": false,
  "name": "example",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "released_at": "2012-01-01T12:00:00Z",
  "repo_size": 0,
  "slug_size": 0,
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa",
    "shield": true
  },
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}

App Disable ACM

Disable ACM flag for an app

DELETE /apps/{app_id_or_name}/acm

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/acm \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm": false,
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "https://git.heroku.com/example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "internal_routing": false,
  "maintenance": false,
  "name": "example",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "released_at": "2012-01-01T12:00:00Z",
  "repo_size": 0,
  "slug_size": 0,
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa",
    "shield": true
  },
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}

App Refresh ACM

Refresh ACM for an app

PATCH /apps/{app_id_or_name}/acm

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/acm \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm": false,
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "https://git.heroku.com/example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "internal_routing": false,
  "maintenance": false,
  "name": "example",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "organization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "released_at": "2012-01-01T12:00:00Z",
  "repo_size": 0,
  "slug_size": 0,
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa",
    "shield": true
  },
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar-14"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}

App Feature

Stability: production

An app feature represents a Heroku labs capability that can be enabled or disabled for an app on Heroku.

Attributes

App Feature Info

Info for an existing app feature.

GET /apps/{app_id_or_name}/features/{app_feature_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/features/$APP_FEATURE_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "description": "Causes app to example.",
  "doc_url": "http://devcenter.heroku.com/articles/example",
  "enabled": true,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "name",
  "state": "public",
  "updated_at": "2012-01-01T12:00:00Z",
  "display_name": "My Feature",
  "feedback_email": "feedback@heroku.com"
}

App Feature List

List existing app features.

Acceptable order values for the Range header are id or name.

GET /apps/{app_id_or_name}/features

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "description": "Causes app to example.",
    "doc_url": "http://devcenter.heroku.com/articles/example",
    "enabled": true,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "name",
    "state": "public",
    "updated_at": "2012-01-01T12:00:00Z",
    "display_name": "My Feature",
    "feedback_email": "feedback@heroku.com"
  }
]

App Feature Update

Update an existing app feature.

PATCH /apps/{app_id_or_name}/features/{app_feature_id_or_name}

Required Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/features/$APP_FEATURE_ID_OR_NAME \
  -d '{
  "enabled": true
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "description": "Causes app to example.",
  "doc_url": "http://devcenter.heroku.com/articles/example",
  "enabled": true,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "name",
  "state": "public",
  "updated_at": "2012-01-01T12:00:00Z",
  "display_name": "My Feature",
  "feedback_email": "feedback@heroku.com"
}

Application Formation Set

Stability: development

App formation set describes the combination of process types with their quantities and sizes as well as application process tier

Attributes

App Setup

Stability: production

An app setup represents an app on Heroku that is setup using an environment, addons, and scripts described in an app.json manifest file.

Attributes

App Setup Create

Create a new app setup from a gzipped tar archive containing an app.json manifest file.

POST /app-setups

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/app-setups \
  -d '{
  "app": {
    "locked": false,
    "name": "example",
    "organization": "example",
    "personal": false,
    "region": "us",
    "space": "nasa",
    "stack": "cedar-14"
  },
  "source_blob": {
    "checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "url": "https://example.com/source.tgz?token=xyz",
    "version": "v1.3.0"
  },
  "overrides": {
    "buildpacks": [
      {
        "url": "https://example.com/buildpack.tgz"
      }
    ],
    "env": {
      "FOO": "bar",
      "BAZ": "qux"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T12:00:00Z",
  "status": "failed",
  "failure_message": "invalid app.json",
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "build": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "status": "succeeded",
    "output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
  },
  "manifest_errors": [
    "config var FOO is required"
  ],
  "postdeploy": {
    "output": "assets precompiled",
    "exit_code": 1
  },
  "resolved_success_url": "https://example.herokuapp.com/welcome"
}

App Setup Info

Get the status of an app setup.

GET /app-setups/{app_setup_id}

Curl Example

$ curl -n https://api.heroku.com/app-setups/$APP_SETUP_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T12:00:00Z",
  "status": "failed",
  "failure_message": "invalid app.json",
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "build": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "status": "succeeded",
    "output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
  },
  "manifest_errors": [
    "config var FOO is required"
  ],
  "postdeploy": {
    "output": "assets precompiled",
    "exit_code": 1
  },
  "resolved_success_url": "https://example.herokuapp.com/welcome"
}

App Transfer

Stability: production

An app transfer represents a two party interaction for transferring ownership of an app.

Attributes

App Transfer Create

Create a new app transfer.

POST /account/app-transfers

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/account/app-transfers \
  -d '{
  "app": "01234567-89ab-cdef-0123-456789abcdef",
  "recipient": "01234567-89ab-cdef-0123-456789abcdef",
  "silent": false
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "recipient": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "state": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

App Transfer Delete

Delete an existing app transfer

DELETE /account/app-transfers/{app_transfer_id_or_name}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/account/app-transfers/$APP_TRANSFER_ID_OR_NAME \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "recipient": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "state": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

App Transfer Info

Info for existing app transfer.

GET /account/app-transfers/{app_transfer_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/account/app-transfers/$APP_TRANSFER_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "recipient": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "state": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

App Transfer List

List existing apps transfers.

Acceptable order values for the Range header are id or name.

GET /account/app-transfers

Curl Example

$ curl -n https://api.heroku.com/account/app-transfers \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "owner": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "recipient": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "state": "pending",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

App Transfer Update

Update an existing app transfer.

PATCH /account/app-transfers/{app_transfer_id_or_name}

Required Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/account/app-transfers/$APP_TRANSFER_ID_OR_NAME \
  -d '{
  "state": "pending"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "recipient": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "state": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

App Webhook

Stability: production

Represents the details of a webhook subscription

App Webhook Create

Create an app webhook subscription.

POST /apps/{app_id_or_name}/webhooks

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks \
  -d '{
  "authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
  "url": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

App Webhook Delete

Removes an app webhook subscription.

DELETE /apps/{app_id_or_name}/webhooks/{app_webhook_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

App Webhook Info

Returns the info for an app webhook subscription.

GET /apps/{app_id_or_name}/webhooks/{app_webhook_id}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

App Webhook List

List all webhook subscriptions for a particular app.

The only acceptable order value for the Range header is id.

GET /apps/{app_id_or_name}/webhooks

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": [
      "api:release"
    ],
    "level": "notify",
    "updated_at": "2015-01-01T12:00:00Z",
    "url": "example"
  }
]

App Webhook Update

Updates the details of an app webhook subscription.

PATCH /apps/{app_id_or_name}/webhooks/{app_webhook_id}

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
  -d '{
  "authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
  "url": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

App Webhook Delivery

Stability: production

Represents the delivery of a webhook notification, including its current status.

Attributes

App Webhook Delivery Info

Returns the info for an existing delivery.

GET /apps/{app_id_or_name}/webhook-deliveries/{app_webhook_delivery_id}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-deliveries/$APP_WEBHOOK_DELIVERY_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2015-01-01T12:00:00Z",
  "event": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": "api:release"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "num_attempts": 42,
  "next_attempt_at": "2015-01-01T12:00:00Z",
  "last_attempt": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "code": 42,
    "error_class": "example",
    "status": "scheduled",
    "created_at": "2015-01-01T12:00:00Z",
    "updated_at": "2015-01-01T12:00:00Z"
  },
  "status": "pending",
  "updated_at": "2015-01-01T12:00:00Z",
  "webhook": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "level": "notify"
  }
}

App Webhook Delivery List

Lists existing deliveries for an app.

The only acceptable order value for the Range header is id.

GET /apps/{app_id_or_name}/webhook-deliveries

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-deliveries \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "event": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "include": "api:release"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "num_attempts": 42,
    "next_attempt_at": "2015-01-01T12:00:00Z",
    "last_attempt": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "code": 42,
      "error_class": "example",
      "status": "scheduled",
      "created_at": "2015-01-01T12:00:00Z",
      "updated_at": "2015-01-01T12:00:00Z"
    },
    "status": "pending",
    "updated_at": "2015-01-01T12:00:00Z",
    "webhook": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "level": "notify"
    }
  }
]

App Webhook Event

Stability: production

Represents a webhook event that occurred.

Attributes

App Webhook Event Info

Returns the info for a specified webhook event.

GET /apps/{app_id_or_name}/webhook-events/{app_webhook_event_id}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-events/$APP_WEBHOOK_EVENT_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": "api:release",
  "payload": {
    "action": "create",
    "actor": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "data": null,
    "previous_data": null,
    "resource": "release",
    "version": "1"
  },
  "updated_at": "2015-01-01T12:00:00Z"
}

App Webhook Event List

Lists existing webhook events for an app.

The only acceptable order value for the Range header is id.

GET /apps/{app_id_or_name}/webhook-events

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-events \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": "api:release",
    "payload": {
      "action": "create",
      "actor": {
        "email": "username@example.com",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      },
      "data": null,
      "previous_data": null,
      "resource": "release",
      "version": "1"
    },
    "updated_at": "2015-01-01T12:00:00Z"
  }
]

Build

Stability: production

A build represents the process of transforming a code tarball into a slug

Attributes

Build Create

Create a new build.

POST /apps/{app_id_or_name}/builds

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/builds \
  -d '{
  "buildpacks": [
    {
      "url": "https://github.com/heroku/heroku-buildpack-ruby"
    }
  ],
  "source_blob": {
    "checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "url": "https://example.com/source.tgz?token=xyz",
    "version": "v1.3.0"
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "buildpacks": [
    {
      "url": "https://github.com/heroku/heroku-buildpack-ruby"
    }
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
  "source_blob": {
    "checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "url": "https://example.com/source.tgz?token=xyz",
    "version": "v1.3.0"
  },
  "release": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "slug": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "stack": "heroku-16",
  "status": "succeeded",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com"
  }
}

Build Info

Info for existing build.

GET /apps/{app_id_or_name}/builds/{build_id}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/builds/$BUILD_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "buildpacks": [
    {
      "url": "https://github.com/heroku/heroku-buildpack-ruby"
    }
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
  "source_blob": {
    "checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "url": "https://example.com/source.tgz?token=xyz",
    "version": "v1.3.0"
  },
  "release": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "slug": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "stack": "heroku-16",
  "status": "succeeded",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com"
  }
}

Build List

List existing build.

Acceptable order values for the Range header are id or started_at.

GET /apps/{app_id_or_name}/builds

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, started_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "buildpacks": [
      {
        "url": "https://github.com/heroku/heroku-buildpack-ruby"
      }
    ],
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
    "source_blob": {
      "checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "url": "https://example.com/source.tgz?token=xyz",
      "version": "v1.3.0"
    },
    "release": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "slug": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "stack": "heroku-16",
    "status": "succeeded",
    "updated_at": "2012-01-01T12:00:00Z",
    "user": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com"
    }
  }
]

Build Delete cache

Destroy a build cache.

DELETE /apps/{app_id_or_name}/build-cache

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/build-cache \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

Build Result

Stability: deprecation

A build result contains the output from a build.

Attributes

Build Result Info

Info for existing result.

GET /apps/{app_id_or_name}/builds/{build_id}/result

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/builds/$BUILD_ID/result \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "build": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "status": "succeeded",
    "output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
  },
  "exit_code": 0,
  "lines": [
    {
      "line": "-----> Ruby app detected\n",
      "stream": "STDOUT"
    }
  ]
}

Buildpack Installations

Stability: production

A buildpack installation represents a buildpack that will be run against an app.

Attributes

Buildpack Installations Update

Update an app’s buildpack installations.

PUT /apps/{app_id_or_name}/buildpack-installations

Required Parameters

Curl Example

$ curl -n -X PUT https://api.heroku.com/apps/$APP_ID_OR_NAME/buildpack-installations \
  -d '{
  "updates": [
    {
      "buildpack": "https://github.com/heroku/heroku-buildpack-ruby"
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "ordinal": 0,
    "buildpack": {
      "url": "https://github.com/heroku/heroku-buildpack-ruby",
      "name": "heroku/ruby"
    }
  }
]

Buildpack Installations List

List an app’s existing buildpack installations.

GET /apps/{app_id_or_name}/buildpack-installations

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/buildpack-installations \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "ordinal": 0,
    "buildpack": {
      "url": "https://github.com/heroku/heroku-buildpack-ruby",
      "name": "heroku/ruby"
    }
  }
]

Collaborator

Stability: production

A collaborator represents an account that has been given access to an app on Heroku.

Attributes

Collaborator Create

Create a new collaborator.

POST /apps/{app_id_or_name}/collaborators

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators \
  -d '{
  "silent": false,
  "user": "01234567-89ab-cdef-0123-456789abcdef"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "permissions": [
    {
      "name": "view",
      "description": "Can manage config, deploy, run commands and restart the app."
    }
  ],
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "federated": false,
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

Collaborator Delete

Delete an existing collaborator.

DELETE /apps/{app_id_or_name}/collaborators/{collaborator_email_or_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators/$COLLABORATOR_EMAIL_OR_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "permissions": [
    {
      "name": "view",
      "description": "Can manage config, deploy, run commands and restart the app."
    }
  ],
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "federated": false,
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

Collaborator Info

Info for existing collaborator.

GET /apps/{app_id_or_name}/collaborators/{collaborator_email_or_id}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators/$COLLABORATOR_EMAIL_OR_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "permissions": [
    {
      "name": "view",
      "description": "Can manage config, deploy, run commands and restart the app."
    }
  ],
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "federated": false,
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

Collaborator List

List existing collaborators.

Acceptable order values for the Range header are email or id.

GET /apps/{app_id_or_name}/collaborators

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: email, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "permissions": [
      {
        "name": "view",
        "description": "Can manage config, deploy, run commands and restart the app."
      }
    ],
    "role": "admin",
    "updated_at": "2012-01-01T12:00:00Z",
    "user": {
      "email": "username@example.com",
      "federated": false,
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
]

Config Vars

Stability: production

Config Vars allow you to manage the configuration information provided to an app on Heroku.

Config Vars Info for App

Get config-vars for app.

GET /apps/{app_id_or_name}/config-vars

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/config-vars \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "FOO": "bar",
  "BAZ": "qux"
}

Config Vars Info for App Release

Get config-vars for a release.

GET /apps/{app_id_or_name}/releases/{release_id_or_version}/config-vars

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/releases/$RELEASE_ID_OR_VERSION/config-vars \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "FOO": "bar",
  "BAZ": "qux"
}

Config Vars Update

Update config-vars for app. You can update existing config-vars by setting them again, and remove by setting it to null.

PATCH /apps/{app_id_or_name}/config-vars

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/config-vars \
  -d '{
  "FOO": "bar",
  "BAZ": "qux"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "FOO": "bar",
  "BAZ": "qux"
}

Credit

Stability: development

A credit represents value that will be used up before further charges are assigned to an account.

Attributes

Credit Create

Create a new credit.

POST /account/credits

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/account/credits \
  -d '{
  "code1": "012abc",
  "code2": "012abc"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "amount": 10000,
  "balance": 5000,
  "created_at": "2012-01-01T12:00:00Z",
  "expires_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "title": "gift card",
  "updated_at": "2012-01-01T12:00:00Z"
}

Credit Info

Info for existing credit.

GET /account/credits/{credit_id}

Curl Example

$ curl -n https://api.heroku.com/account/credits/$CREDIT_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "amount": 10000,
  "balance": 5000,
  "created_at": "2012-01-01T12:00:00Z",
  "expires_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "title": "gift card",
  "updated_at": "2012-01-01T12:00:00Z"
}

Credit List

List existing credits.

The only acceptable order value for the Range header is id.

GET /account/credits

Curl Example

$ curl -n https://api.heroku.com/account/credits \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "amount": 10000,
    "balance": 5000,
    "created_at": "2012-01-01T12:00:00Z",
    "expires_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "title": "gift card",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Domain

Stability: production

Domains define what web routes should be routed to an app on Heroku.

Attributes

Domain Create

Create a new domain.

POST /apps/{app_id_or_name}/domains

Required Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/domains \
  -d '{
  "hostname": "subdomain.example.com"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm_status": "pending",
  "acm_status_reason": "Failing CCA check",
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "cname": "example.herokudns.com",
  "created_at": "2012-01-01T12:00:00Z",
  "hostname": "subdomain.example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "kind": "custom",
  "updated_at": "2012-01-01T12:00:00Z",
  "status": "pending"
}

Domain Delete

Delete an existing domain

DELETE /apps/{app_id_or_name}/domains/{domain_id_or_hostname}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/domains/$DOMAIN_ID_OR_HOSTNAME \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm_status": "pending",
  "acm_status_reason": "Failing CCA check",
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "cname": "example.herokudns.com",
  "created_at": "2012-01-01T12:00:00Z",
  "hostname": "subdomain.example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "kind": "custom",
  "updated_at": "2012-01-01T12:00:00Z",
  "status": "pending"
}

Domain Info

Info for existing domain.

GET /apps/{app_id_or_name}/domains/{domain_id_or_hostname}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/domains/$DOMAIN_ID_OR_HOSTNAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "acm_status": "pending",
  "acm_status_reason": "Failing CCA check",
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "cname": "example.herokudns.com",
  "created_at": "2012-01-01T12:00:00Z",
  "hostname": "subdomain.example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "kind": "custom",
  "updated_at": "2012-01-01T12:00:00Z",
  "status": "pending"
}

Domain List

List existing domains.

Acceptable order values for the Range header are hostname or id.

GET /apps/{app_id_or_name}/domains

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: hostname, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "acm_status": "pending",
    "acm_status_reason": "Failing CCA check",
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "cname": "example.herokudns.com",
    "created_at": "2012-01-01T12:00:00Z",
    "hostname": "subdomain.example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "kind": "custom",
    "updated_at": "2012-01-01T12:00:00Z",
    "status": "pending"
  }
]

Dyno

Stability: production

Dynos encapsulate running processes of an app on Heroku. Detailed information about dyno sizes can be found at: https://devcenter.heroku.com/articles/dyno-types.

Attributes

Dyno Create

Create a new dyno.

POST /apps/{app_id_or_name}/dynos

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos \
  -d '{
  "attach": true,
  "command": "bash",
  "env": {
    "COLUMNS": "80",
    "LINES": "24"
  },
  "force_no_tty": null,
  "size": "standard-1X",
  "type": "run",
  "time_to_live": 1800
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
  "command": "bash",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "run.1",
  "release": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "version": 11
  },
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "size": "standard-1X",
  "state": "up",
  "type": "run",
  "updated_at": "2012-01-01T12:00:00Z"
}

Dyno Restart

Restart dyno.

DELETE /apps/{app_id_or_name}/dynos/{dyno_id_or_name}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos/$DYNO_ID_OR_NAME \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

Dyno Restart all

Restart all dynos.

DELETE /apps/{app_id_or_name}/dynos

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

Dyno Stop

Stop dyno.

POST /apps/{app_id_or_name}/dynos/{dyno_id_or_name}/actions/stop

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos/$DYNO_ID_OR_NAME/actions/stop \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

Dyno Info

Info for existing dyno.

GET /apps/{app_id_or_name}/dynos/{dyno_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos/$DYNO_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
  "command": "bash",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "run.1",
  "release": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "version": 11
  },
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "size": "standard-1X",
  "state": "up",
  "type": "run",
  "updated_at": "2012-01-01T12:00:00Z"
}

Dyno List

List existing dynos.

Acceptable order values for the Range header are id or name.

GET /apps/{app_id_or_name}/dynos

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
    "command": "bash",
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "run.1",
    "release": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "version": 11
    },
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "size": "standard-1X",
    "state": "up",
    "type": "run",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Dyno Size

Stability: prototype

Dyno sizes are the values and details of sizes that can be assigned to dynos. This information can also be found at : https://devcenter.heroku.com/articles/dyno-types.

Attributes

Dyno Size Info

Info for existing dyno size.

GET /dyno-sizes/{dyno_size_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/dyno-sizes/$DYNO_SIZE_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "compute": 1,
  "cost": null,
  "dedicated": false,
  "dyno_units": 0,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "memory": 0.5,
  "name": "free",
  "private_space_only": false
}

Dyno Size List

List existing dyno sizes.

Acceptable order values for the Range header are id or name.

GET /dyno-sizes

Curl Example

$ curl -n https://api.heroku.com/dyno-sizes \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "compute": 1,
    "cost": null,
    "dedicated": false,
    "dyno_units": 0,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "memory": 0.5,
    "name": "free",
    "private_space_only": false
  }
]

Filters

Stability: development

Filters are special endpoints to allow for API consumers to specify a subset of resources to consume in order to reduce the number of requests that are performed. Each filter endpoint endpoint is responsible for determining its supported request format. The endpoints are over POST in order to handle large request bodies without hitting request uri query length limitations, but the requests themselves are idempotent and will not have side effects.

Filters Apps

Request an apps list filtered by app id.

Acceptable order values for the Range header are id, name or updated_at.

POST /filters/apps

Curl Example

$ curl -n -X POST https://api.heroku.com/filters/apps \
  -d '{
  "in": {
    "id": [
      "01234567-89ab-cdef-0123-456789abcdef"
    ]
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name, updated_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "archived_at": "2012-01-01T12:00:00Z",
    "buildpack_provided_description": "Ruby/Rack",
    "build_stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar-14"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "git_url": "https://git.heroku.com/example.git",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "internal_routing": false,
    "joined": false,
    "locked": false,
    "maintenance": false,
    "name": "example",
    "team": {
      "name": "example"
    },
    "owner": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "region": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "us"
    },
    "released_at": "2012-01-01T12:00:00Z",
    "repo_size": 0,
    "slug_size": 0,
    "space": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "nasa"
    },
    "stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar-14"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://example.herokuapp.com/"
  }
]

Formation

Stability: production

The formation of processes that should be maintained for an app. Update the formation to scale processes or change dyno sizes. Available process type names and commands are defined by the process_types attribute for the slug currently released on an app.

Attributes

Formation Info

Info for a process type

GET /apps/{app_id_or_name}/formation/{formation_id_or_type}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/formation/$FORMATION_ID_OR_TYPE \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "command": "bundle exec rails server -p $PORT",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "quantity": 1,
  "size": "standard-1X",
  "type": "web",
  "updated_at": "2012-01-01T12:00:00Z"
}

Formation List

List process type formation

Acceptable order values for the Range header are id or type.

GET /apps/{app_id_or_name}/formation

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, type
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "command": "bundle exec rails server -p $PORT",
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "quantity": 1,
    "size": "standard-1X",
    "type": "web",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Formation Batch Update

Batch update process types

PATCH /apps/{app_id_or_name}/formation

Required Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/formation \
  -d '{
  "updates": [
    {
      "quantity": 1,
      "size": "standard-1X",
      "type": "web"
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "command": "bundle exec rails server -p $PORT",
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "quantity": 1,
    "size": "standard-1X",
    "type": "web",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Formation Update

Update process type

PATCH /apps/{app_id_or_name}/formation/{formation_id_or_type}

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/formation/$FORMATION_ID_OR_TYPE \
  -d '{
  "quantity": 1,
  "size": "standard-1X"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "command": "bundle exec rails server -p $PORT",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "quantity": 1,
  "size": "standard-1X",
  "type": "web",
  "updated_at": "2012-01-01T12:00:00Z"
}

Identity Provider

Stability: production

Identity Providers represent the SAML configuration of an Organization.

Attributes

Identity Provider List By Organization

Get a list of an organization’s Identity Providers

GET /organizations/{organization_name}/identity-providers

Curl Example

$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_NAME/identity-providers \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "certificate": "-----BEGIN CERTIFICATE----- ...",
    "created_at": "2012-01-01T12:00:00Z",
    "entity_id": "https://customer-domain.idp.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "slo_target_url": "https://example.com/idp/logout",
    "sso_target_url": "https://example.com/idp/login",
    "organization": {
      "name": "example"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  }
]

Identity Provider Create By Organization

Create an Identity Provider for an organization

POST /organizations/{organization_name}/identity-providers

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/organizations/$ORGANIZATION_NAME/identity-providers \
  -d '{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "entity_id": "https://customer-domain.idp.com",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "entity_id": "https://customer-domain.idp.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login",
  "organization": {
    "name": "example"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "type": "team"
  }
}

Identity Provider Update By Organization

Update an organization’s Identity Provider

PATCH /organizations/{organization_name}/identity-providers/{identity_provider_id}

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/organizations/$ORGANIZATION_NAME/identity-providers/$IDENTITY_PROVIDER_ID \
  -d '{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "entity_id": "https://customer-domain.idp.com",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "entity_id": "https://customer-domain.idp.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login",
  "organization": {
    "name": "example"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "type": "team"
  }
}

Identity Provider Delete By Organization

Delete an organization’s Identity Provider

DELETE /organizations/{organization_name}/identity-providers/{identity_provider_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/organizations/$ORGANIZATION_NAME/identity-providers/$IDENTITY_PROVIDER_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "entity_id": "https://customer-domain.idp.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login",
  "organization": {
    "name": "example"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "type": "team"
  }
}

Identity Provider List By Team

Get a list of a team’s Identity Providers

GET /teams/{team_name_or_id}/identity-providers

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/identity-providers \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "certificate": "-----BEGIN CERTIFICATE----- ...",
    "created_at": "2012-01-01T12:00:00Z",
    "entity_id": "https://customer-domain.idp.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "slo_target_url": "https://example.com/idp/logout",
    "sso_target_url": "https://example.com/idp/login",
    "organization": {
      "name": "example"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  }
]

Identity Provider Create By Team

Create an Identity Provider for a team

POST /teams/{team_name_or_id}/identity-providers

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/teams/$TEAM_NAME_OR_ID/identity-providers \
  -d '{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "entity_id": "https://customer-domain.idp.com",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "entity_id": "https://customer-domain.idp.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login",
  "organization": {
    "name": "example"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "type": "team"
  }
}

Identity Provider Update By Team

Update a team’s Identity Provider

PATCH /teams/{team_name_or_id}/identity-providers/{identity_provider_id}

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/teams/$TEAM_NAME_OR_ID/identity-providers/$IDENTITY_PROVIDER_ID \
  -d '{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "entity_id": "https://customer-domain.idp.com",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "entity_id": "https://customer-domain.idp.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login",
  "organization": {
    "name": "example"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "type": "team"
  }
}

Identity Provider Delete By Team

Delete a team’s Identity Provider

DELETE /teams/{team_name}/identity-providers/{identity_provider_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/teams/$TEAM_NAME/identity-providers/$IDENTITY_PROVIDER_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "certificate": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "entity_id": "https://customer-domain.idp.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "slo_target_url": "https://example.com/idp/logout",
  "sso_target_url": "https://example.com/idp/login",
  "organization": {
    "name": "example"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "type": "team"
  }
}

Inbound Ruleset

Stability: prototype

An inbound-ruleset is a collection of rules that specify what hosts can or cannot connect to an application.

Attributes

Inbound Ruleset Current

Current inbound ruleset for a space

GET /spaces/{space_id_or_name}/inbound-ruleset

Curl Example

$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/inbound-ruleset \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "rules": [
    {
      "action": "allow",
      "source": "1.1.1.1/1"
    }
  ],
  "created_by": "username@example.com"
}

Inbound Ruleset Info

Info on an existing Inbound Ruleset

GET /spaces/{space_id_or_name}/inbound-rulesets/{inbound_ruleset_id}

Curl Example

$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/inbound-rulesets/$INBOUND_RULESET_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "rules": [
    {
      "action": "allow",
      "source": "1.1.1.1/1"
    }
  ],
  "created_by": "username@example.com"
}

Inbound Ruleset List

List all inbound rulesets for a space

The only acceptable order value for the Range header is id.

GET /spaces/{space_id_or_name}/inbound-rulesets

Curl Example

$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/inbound-rulesets \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "space": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "nasa"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "rules": [
      {
        "action": "allow",
        "source": "1.1.1.1/1"
      }
    ],
    "created_by": "username@example.com"
  }
]

Inbound Ruleset Create

Create a new inbound ruleset

PUT /spaces/{space_id_or_name}/inbound-ruleset

Optional Parameters

Curl Example

$ curl -n -X PUT https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/inbound-ruleset \
  -d '{
  "rules": [
    {
      "action": "allow",
      "source": "1.1.1.1/1"
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "space": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "rules": [
    {
      "action": "allow",
      "source": "1.1.1.1/1"
    }
  ],
  "created_by": "username@example.com"
}

Invoice

Stability: development

An invoice is an itemized bill of goods for an account which includes pricing and charges.

Attributes

Invoice Info

Info for existing invoice.

GET /account/invoices/{invoice_number}

Curl Example

$ curl -n https://api.heroku.com/account/invoices/$INVOICE_NUMBER \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "charges_total": 100.0,
  "created_at": "2012-01-01T12:00:00Z",
  "credits_total": 100.0,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "number": 9403943,
  "period_end": "01/31/2014",
  "period_start": "01/01/2014",
  "state": 1,
  "total": 100.0,
  "updated_at": "2012-01-01T12:00:00Z"
}

Invoice List

List existing invoices.

The only acceptable order value for the Range header is number.

GET /account/invoices

Curl Example

$ curl -n https://api.heroku.com/account/invoices \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: number
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "charges_total": 100.0,
    "created_at": "2012-01-01T12:00:00Z",
    "credits_total": 100.0,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "number": 9403943,
    "period_end": "01/31/2014",
    "period_start": "01/01/2014",
    "state": 1,
    "total": 100.0,
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Invoice Address

Stability: development

An invoice address represents the address that should be listed on an invoice.

Attributes

Invoice Address info

Retrieve existing invoice address.

GET /account/invoice-address

Curl Example

$ curl -n https://api.heroku.com/account/invoice-address \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "address_1": "40 Hickory Blvd.",
  "address_2": "Suite 300",
  "city": "Seattle",
  "country": "US",
  "heroku_id": "user930223902@heroku.com",
  "other": "Company ABC Inc. VAT 903820",
  "postal_code": "98101",
  "state": "WA",
  "use_invoice_address": true
}

Invoice Address update

Update invoice address for an account.

PUT /account/invoice-address

Optional Parameters

Curl Example

$ curl -n -X PUT https://api.heroku.com/account/invoice-address \
  -d '{
  "address_1": "40 Hickory Blvd.",
  "address_2": "Suite 300",
  "city": "Seattle",
  "country": "US",
  "other": "Company ABC Inc. VAT 903820",
  "postal_code": "98101",
  "state": "WA",
  "use_invoice_address": true
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "address_1": "40 Hickory Blvd.",
  "address_2": "Suite 300",
  "city": "Seattle",
  "country": "US",
  "heroku_id": "user930223902@heroku.com",
  "other": "Company ABC Inc. VAT 903820",
  "postal_code": "98101",
  "state": "WA",
  "use_invoice_address": true
}

Key

Stability: production

Keys represent public SSH keys associated with an account and are used to authorize accounts as they are performing git operations.

Attributes

Key Info

Info for existing key.

GET /account/keys/{key_id_or_fingerprint}

Curl Example

$ curl -n https://api.heroku.com/account/keys/$KEY_ID_OR_FINGERPRINT \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "comment": "username@host",
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@host",
  "fingerprint": "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "public_key": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com",
  "updated_at": "2012-01-01T12:00:00Z"
}

Key List

List existing keys.

Acceptable order values for the Range header are fingerprint or id.

GET /account/keys

Curl Example

$ curl -n https://api.heroku.com/account/keys \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: fingerprint, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "comment": "username@host",
    "created_at": "2012-01-01T12:00:00Z",
    "email": "username@host",
    "fingerprint": "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "public_key": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Log Drain

Stability: production

Log drains provide a way to forward your Heroku logs to an external syslog server for long-term archiving. This external service must be configured to receive syslog packets from Heroku, whereupon its URL can be added to an app using this API. Some add-ons will add a log drain when they are provisioned to an app. These drains can only be removed by removing the add-on.

Attributes

Log Drain Create

Create a new log drain.

POST /apps/{app_id_or_name}/log-drains

Required Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains \
  -d '{
  "url": "https://example.com/drain"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "singing-swiftly-1242"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "token": "d.01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://example.com/drain"
}

Log Drain Update

Update an add-on owned log drain.

PUT /addons/{add_on_id_or_name}/log-drains/{log_drain_id_or_url_or_token}

Required Parameters

Curl Example

$ curl -n -X PUT https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL_OR_TOKEN \
  -d '{
  "url": "https://example.com/drain"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "singing-swiftly-1242"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "token": "d.01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://example.com/drain"
}

Log Drain Delete

Delete an existing log drain. Log drains added by add-ons can only be removed by removing the add-on.

DELETE /apps/{app_id_or_name}/log-drains/{log_drain_id_or_url_or_token}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL_OR_TOKEN \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "singing-swiftly-1242"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "token": "d.01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://example.com/drain"
}

Log Drain Info

Info for existing log drain.

GET /apps/{app_id_or_name}/log-drains/{log_drain_id_or_url_or_token}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL_OR_TOKEN \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "singing-swiftly-1242"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "token": "d.01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://example.com/drain"
}

Log Drain List By Add-on

List existing log drains for an add-on.

The only acceptable order value for the Range header is url.

GET /addons/{add_on_id_or_name}/log-drains

Curl Example

$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/log-drains \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: url
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "singing-swiftly-1242"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "d.01234567-89ab-cdef-0123-456789abcdef",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://example.com/drain"
  }
]

Log Drain List

List existing log drains.

The only acceptable order value for the Range header is url.

GET /apps/{app_id_or_name}/log-drains

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: url
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "singing-swiftly-1242"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "d.01234567-89ab-cdef-0123-456789abcdef",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://example.com/drain"
  }
]

Log Session

Stability: production

A log session is a reference to the http based log stream for an app.

Attributes

Log Session Create

Create a new log session.

POST /apps/{app_id_or_name}/log-sessions

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/log-sessions \
  -d '{
  "dyno": "web.1",
  "lines": 10,
  "source": "app",
  "tail": true
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "logplex_url": "https://logplex.heroku.com/sessions/01234567-89ab-cdef-0123-456789abcdef?srv=1325419200",
  "updated_at": "2012-01-01T12:00:00Z"
}

OAuth Authorization

Stability: production

OAuth authorizations represent clients that a Heroku user has authorized to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation

Attributes

OAuth Authorization Create

Create a new OAuth authorization.

POST /oauth/authorizations

Required Parameters

Optional Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/oauth/authorizations \
  -d '{
  "client": "01234567-89ab-cdef-0123-456789abcdef",
  "description": "sample authorization",
  "expires_in": 2592000,
  "scope": [
    "global"
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "redirect_uri": "https://example.com/auth/heroku/callback"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com",
    "full_name": "Tina Edmonds"
  }
}

OAuth Authorization Delete

Delete OAuth authorization.

DELETE /oauth/authorizations/{oauth_authorization_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "redirect_uri": "https://example.com/auth/heroku/callback"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com",
    "full_name": "Tina Edmonds"
  }
}

OAuth Authorization Info

Info for an OAuth authorization.

GET /oauth/authorizations/{oauth_authorization_id}

Curl Example

$ curl -n https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "redirect_uri": "https://example.com/auth/heroku/callback"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com",
    "full_name": "Tina Edmonds"
  }
}

OAuth Authorization List

List OAuth authorizations.

The only acceptable order value for the Range header is id.

GET /oauth/authorizations

Curl Example

$ curl -n https://api.heroku.com/oauth/authorizations \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "access_token": {
      "expires_in": 2592000,
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "token": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "client": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example",
      "redirect_uri": "https://example.com/auth/heroku/callback"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "grant": {
      "code": "01234567-89ab-cdef-0123-456789abcdef",
      "expires_in": 2592000,
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "refresh_token": {
      "expires_in": 2592000,
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "token": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "scope": [
      "global"
    ],
    "updated_at": "2012-01-01T12:00:00Z",
    "user": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com",
      "full_name": "Tina Edmonds"
    }
  }
]

OAuth Authorization Regenerate

Regenerate OAuth tokens. This endpoint is only available to direct authorizations or privileged OAuth clients.

POST /oauth/authorizations/{oauth_authorization_id}/actions/regenerate-tokens

Curl Example

$ curl -n -X POST https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID/actions/regenerate-tokens \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "redirect_uri": "https://example.com/auth/heroku/callback"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com",
    "full_name": "Tina Edmonds"
  }
}

OAuth Client

Stability: production

OAuth clients are applications that Heroku users can authorize to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation.

Attributes

OAuth Client Create

Create a new OAuth client.

POST /oauth/clients

Required Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/oauth/clients \
  -d '{
  "name": "example",
  "redirect_uri": "https://example.com/auth/heroku/callback"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "ignores_delinquent": false,
  "name": "example",
  "redirect_uri": "https://example.com/auth/heroku/callback",
  "secret": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

OAuth Client Delete

Delete OAuth client.

DELETE /oauth/clients/{oauth_client_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "ignores_delinquent": false,
  "name": "example",
  "redirect_uri": "https://example.com/auth/heroku/callback",
  "secret": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

OAuth Client Info

Info for an OAuth client

GET /oauth/clients/{oauth_client_id}

Curl Example

$ curl -n https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "ignores_delinquent": false,
  "name": "example",
  "redirect_uri": "https://example.com/auth/heroku/callback",
  "secret": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

OAuth Client List

List OAuth clients

The only acceptable order value for the Range header is id.

GET /oauth/clients

Curl Example

$ curl -n https://api.heroku.com/oauth/clients \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "ignores_delinquent": false,
    "name": "example",
    "redirect_uri": "https://example.com/auth/heroku/callback",
    "secret": "01234567-89ab-cdef-0123-456789abcdef",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

OAuth Client Update

Update OAuth client

PATCH /oauth/clients/{oauth_client_id}

Optional Parameters

Curl Example

$ curl -n -X PATCH https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID \
  -d '{
  "name": "example",
  "redirect_uri": "https://example.com/auth/heroku/callback"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "ignores_delinquent": false,
  "name": "example",
  "redirect_uri": "https://example.com/auth/heroku/callback",
  "secret": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

OAuth Client Rotate Credentials

Rotate credentials for an OAuth client

POST /oauth/clients/{oauth_client_id}/actions/rotate-credentials

Curl Example

$ curl -n -X POST https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID/actions/rotate-credentials \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "ignores_delinquent": false,
  "name": "example",
  "redirect_uri": "https://example.com/auth/heroku/callback",
  "secret": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

OAuth Grant

Stability: production

OAuth grants are used to obtain authorizations on behalf of a user. For more information please refer to the Heroku OAuth documentation

OAuth Token

Stability: production

OAuth tokens provide access for authorized clients to act on behalf of a Heroku user to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation

Attributes

OAuth Token Create

Create a new OAuth token.

POST /oauth/tokens

Required Parameters

Curl Example

$ curl -n -X POST https://api.heroku.com/oauth/tokens \
  -d '{
  "client": {
    "secret": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "authorization_code"
  },
  "refresh_token": {
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "authorization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "secret": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "authorization_code"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "session": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

OAuth Token Delete

Revoke OAuth access token.

DELETE /oauth/tokens/{oauth_token_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/oauth/tokens/$OAUTH_TOKEN_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "authorization": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "client": {
    "secret": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "authorization_code"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "refresh_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "session": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

Organization

Stability: prototype

Deprecated: Organizations allow you to manage access to a shared group of applications across your development team.

Attributes

Organization List

List organizations in which you are a member.

Acceptable order values for the Range header are id or name.

GET /organizations

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500