heroku dev center

Platform API Reference

Last Updated: 24 February 2015

api

Table of Contents

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 Heroku toolbelt 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

Name JSON Type Description
date-time string timestamp in iso8601 format
uuid string uuid in 8-4-4-4-12 format

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

Name Type Description Example
id string id of error raised "rate_limit"
message string end user message of error raised "Your account reached the API limit. Please wait a few minutes before making new requests"
url string reference url with more information about the error https://devcenter.heroku.com/articles/platform-api-reference#rate-limits

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"
}

Legacy API

Those utilizing the legacy, v2 API should instead consult legacy-api-docs.heroku.com

Methods

Method Usage
DELETE used for destroying existing objects
GET used for retrieving lists and individual objects
HEAD used for retrieving metadata about existing objects
PATCH used for updating existing objects
POST used for creating new objects

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 2400 tokens. Each API call removes one token from the pool. Tokens are added to the account pool at a rate of roughly 20 per minute (or 1200 per hour), up to a maximum of 2400. 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

Header Description
RateLimit-Remaining allowed requests remaining in current interval

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

Status Description
200 OK request succeeded
201 Created resource created, for example a new app was created or an add-on was provisioned
202 Accepted request accepted, but the processing has not been completed
206 Partial Content request succeeded, but this is only a partial response, see ranges

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
Status Error ID Description
400 Bad Request bad_request request invalid, validate usage and try again
401 Unauthorized unauthorized request not authenticated, API token is missing, invalid or expired
402 Payment Required delinquent either the account has become delinquent as a result of non-payment, or the account’s payment method must be confirmed to continue
403 Forbidden forbidden request not authorized, provided credentials do not provide access to specified resource
403 Forbidden suspended request not authorized, account or application was suspended.
404 Not Found not_found request failed, the specified resource does not exist
406 Not Acceptable not_acceptable request failed, set Accept: application/vnd.heroku+json; version=3 header and try again
416 Requested Range Not Satisfiable requested_range_not_satisfiable request failed, validate Content-Range header and try again
422 Unprocessable Entity invalid_params request failed, validate parameters try again
422 Unprocessable Entity verification_needed request failed, enter billing information in the Heroku Dashboard before utilizing resources.
429 Too Many Requests rate_limit request failed, wait for rate limits to reset and try again, see rate limits
Heroku Error Responses
Status Description
500 Internal Server Error error occurred, we are notified, but contact support if the issue persists
503 Service Unavailable API is unavailable, check response body or Heroku status for details

Versioning

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

Account Feature

Stability: production

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

Attributes

Name Type Description Example
created_at date-time when account feature was created "2012-01-01T12:00:00Z"
description string description of account feature "Causes account to example."
doc_url string documentation URL of account feature "http://devcenter.heroku.com/articles/example"
enabled boolean whether or not account feature has been enabled true
id uuid unique identifier of account feature "01234567-89ab-cdef-0123-456789abcdef"
name string unique name of account feature "name"
state string state of account feature "public"
updated_at date-time when account feature was updated "2012-01-01T12:00:00Z"

Account Feature Info

Info for an existing account feature.

GET /account/features/{account_feature_id_or_name}

Curl Example

$ curl -n -X GET 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: 2400

{
  "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"
}

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 -X GET 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: 2400

[
  {
    "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"
  }
]

Account Feature Update

Update an existing account feature.

PATCH /account/features/{account_feature_id_or_name}

Required Parameters

Name Type Description Example
enabled boolean whether or not account feature has been enabled true

Curl Example

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

Response Example

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

{
  "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"
}

Account

Stability: production

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

Attributes

Name Type Description Example
allow_tracking boolean whether to allow third party web activity tracking
default: true 		true
beta boolean whether allowed to utilize beta Heroku features false
created_at date-time when account was created "2012-01-01T12:00:00Z"
email email unique email address of account "username@example.com"
id uuid unique identifier of an account "01234567-89ab-cdef-0123-456789abcdef"
last_login date-time when account last authorized with Heroku "2012-01-01T12:00:00Z"
name nullable string full name of the account owner "Tina Edmonds"
two_factor_authentication boolean whether two-factor auth is enabled on the account false
updated_at date-time when account was updated "2012-01-01T12:00:00Z"
verified boolean whether account has been verified with billing information false

Account Info

Info for account.

GET /account

Curl Example

$ curl -n -X GET 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: 2400

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false
}

Account Update

Update account.

PATCH /account

Optional Parameters

Name Type Description Example
allow_tracking boolean whether to allow third party web activity tracking
default: true 		true
beta boolean whether allowed to utilize beta Heroku features false
name nullable string full name of the account owner "Tina Edmonds"
password string current password on the account "currentpassword"

Curl Example

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

Response Example

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

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false
}

Account Change Email

Change Email for account.

PATCH /account

Required Parameters

Name Type Description Example
email email unique email address of account "username@example.com"
password string current password on the account "currentpassword"

Curl Example

$ curl -n -X PATCH https://api.heroku.com/account \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "email": "username@example.com",
  "password": "currentpassword"
}'

Response Example

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

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false
}

Account Change Password

Change Password for account.

PATCH /account

Required Parameters

Name Type Description Example
new_password string the new password for the account when changing the password "newpassword"
password string current password on the account "currentpassword"

Curl Example

$ curl -n -X PATCH https://api.heroku.com/account \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "new_password": "newpassword",
  "password": "currentpassword"
}'

Response Example

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

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false
}

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 "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: 2400

{
  "allow_tracking": true,
  "beta": false,
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "last_login": "2012-01-01T12:00:00Z",
  "name": "Tina Edmonds",
  "two_factor_authentication": false,
  "updated_at": "2012-01-01T12:00:00Z",
  "verified": false
}

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

Name Type Description Example
created_at date-time when addon-service was created "2012-01-01T12:00:00Z"
human_name string human-readable name of the addon service provider "Heroku Postgres"
id uuid unique identifier of this addon-service "01234567-89ab-cdef-0123-456789abcdef"
name string unique name of this addon-service "heroku-postgresql"
updated_at date-time when addon-service was updated "2012-01-01T12:00:00Z"

Add-on Service Info

Info for existing addon-service.

GET /addon-services/{addon_service_id_or_name}

Curl Example

$ curl -n -X GET https://api.heroku.com/addon-services/$ADDON_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: 2400

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "heroku-postgresql",
  "human_name": "Heroku Postgres",
  "updated_at": "2012-01-01T12:00:00Z"
}

Add-on Service List

List existing addon-services.

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

GET /addon-services

Curl Example

$ curl -n -X GET 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: 2400

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

Add-on

Stability: production

Add-ons represent add-ons that have been provisioned for an app.

Attributes

Name Type Description Example
addon_service:id uuid unique identifier of this addon-service "01234567-89ab-cdef-0123-456789abcdef"
addon_service:name string unique name of this addon-service "heroku-postgresql"
app:id uuid unique identifier of app "01234567-89ab-cdef-0123-456789abcdef"
app:name string unique name of app "example"
config_vars array config vars associated with this application ["FOO","BAZ"]
created_at date-time when add-on was created "2012-01-01T12:00:00Z"
id uuid unique identifier of add-on "01234567-89ab-cdef-0123-456789abcdef"
name string name of the add-on unique within its app "heroku-postgresql-teal"
plan:id uuid unique identifier of this plan "01234567-89ab-cdef-0123-456789abcdef"
plan:name string unique name of this plan "heroku-postgresql:dev"
provider_id string id of this add-on with its provider "app123@heroku.com"
updated_at date-time when add-on was updated "2012-01-01T12:00:00Z"

Add-on Create

Create a new add-on.

POST /apps/{app_id_or_name}/addons

Required Parameters

Name Type Description Example
plan string unique identifier or name of this plan "01234567-89ab-cdef-0123-456789abcdef" or "heroku-postgresql:dev"

Optional Parameters

Name Type Description Example
config object custom add-on provisioning options {"db-version":"1.2.3"}

Curl Example

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

Response Example

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

{
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "heroku-postgresql-teal",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "app123@heroku.com",
  "updated_at": "2012-01-01T12:00:00Z"
}

Add-on Delete

Delete an existing add-on.

DELETE /apps/{app_id_or_name}/addons/{addon_id_or_name}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADDON_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: 2400

{
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "heroku-postgresql-teal",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "app123@heroku.com",
  "updated_at": "2012-01-01T12:00:00Z"
}

Add-on Info

Info for an existing add-on.

GET /apps/{app_id_or_name}/addons/{addon_id_or_name}

Curl Example

$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADDON_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: 2400

{
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "heroku-postgresql-teal",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "app123@heroku.com",
  "updated_at": "2012-01-01T12:00:00Z"
}

Add-on List

List existing add-ons.

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

GET /apps/{app_id_or_name}/addons

Curl Example

$ curl -n -X GET 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: 2400

[
  {
    "addon_service": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql"
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "config_vars": [
      "FOO",
      "BAZ"
    ],
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql-teal",
    "plan": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql:dev"
    },
    "provider_id": "app123@heroku.com",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

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/{addon_id_or_name}

Required Parameters

Name Type Description Example
plan string unique identifier or name of this plan "01234567-89ab-cdef-0123-456789abcdef" or "heroku-postgresql:dev"

Curl Example

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

Response Example

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

{
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql"
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "config_vars": [
    "FOO",
    "BAZ"
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "heroku-postgresql-teal",
  "plan": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev"
  },
  "provider_id": "app123@heroku.com",
  "updated_at": "2012-01-01T12:00:00Z"
}

App Feature

Stability: production

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

Attributes

Name Type Description Example
created_at date-time when app feature was created "2012-01-01T12:00:00Z"
description string description of app feature "Causes app to example."
doc_url string documentation URL of app feature "http://devcenter.heroku.com/articles/example"
enabled boolean whether or not app feature has been enabled true
id uuid unique identifier of app feature "01234567-89ab-cdef-0123-456789abcdef"
name string unique name of app feature "name"
state string state of app feature "public"
updated_at date-time when app feature was updated "2012-01-01T12:00:00Z"

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 -X GET 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: 2400

{
  "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"
}

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 -X GET 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: 2400

[
  {
    "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"
  }
]

App Feature Update

Update an existing app feature.

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

Required Parameters

Name Type Description Example
enabled boolean whether or not app feature has been enabled true

Curl Example

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

Response Example

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

{
  "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"
}

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

Name Type Description Example
app:id uuid unique identifier of app "01234567-89ab-cdef-0123-456789abcdef"
app:name string unique name of app "example"
build:id uuid unique identifier of build "01234567-89ab-cdef-0123-456789abcdef"
build:status string status of build
one of:"failed" or "pending" or "succeeded" 		"succeeded"
created_at date-time when app setup was created "2012-01-01T12:00:00Z"
failure_message nullable string reason that app setup has failed "invalid app.json"
id uuid unique identifier of app setup "01234567-89ab-cdef-0123-456789abcdef"
manifest_errors array errors associated with invalid app.json manifest file ["config var FOO is required"]
postdeploy nullable object result of postdeploy script null
postdeploy:exit_code integer The exit code of the postdeploy script 1
postdeploy:output string output of the postdeploy script "assets precompiled"
resolved_success_url nullable string fully qualified success url "https://example.herokuapp.com/welcome"
status string the overall status of app setup
one of:"failed" or "pending" or "succeeded" 		"succeeded"
updated_at date-time when app setup was updated "2012-01-01T12:00:00Z"

App Setup Create

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

POST /app-setups

Required Parameters

Name Type Description Example
source_blob:url string URL of gzipped tarball of source code containing app.json manifest file "https://example.com/source.tgz?token=xyz"

Optional Parameters

Name Type Description Example
app:locked boolean are other organization members forbidden from joining this app. false
app:name string unique name of app "example"
app:organization string unique name of organization "example"
app:personal boolean force creation of the app in the user account even if a default org is set. false
app:region string unique name of region "us"
app:stack string unique name of stack "cedar"
overrides:env object overrides of the env specified in the app.json manifest file {"FOO":"bar","BAZ":"qux"}

Curl Example

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

Response Example

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

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T12:00:00Z",
  "status": "succeeded",
  "failure_message": "invalid app.json",
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "build": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "status": "succeeded"
  },
  "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 -X GET 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: 2400

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T12:00:00Z",
  "status": "succeeded",
  "failure_message": "invalid app.json",
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "build": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "status": "succeeded"
  },
  "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

Name Type Description Example
app:id uuid unique identifier of app "01234567-89ab-cdef-0123-456789abcdef"
app:name string unique name of app "example"
created_at date-time when app transfer was created "2012-01-01T12:00:00Z"
id uuid unique identifier of app transfer "01234567-89ab-cdef-0123-456789abcdef"
owner:email email unique email address of account "username@example.com"
owner:id uuid unique identifier of an account "01234567-89ab-cdef-0123-456789abcdef"
recipient:email email unique email address of account "username@example.com"
recipient:id uuid unique identifier of an account "01234567-89ab-cdef-0123-456789abcdef"
state string the current state of an app transfer
one of:"pending" or "accepted" or "declined" 		"pending"
updated_at date-time when app transfer was updated "2012-01-01T12:00:00Z"

App Transfer Create

Create a new app transfer.

POST /account/app-transfers

Required Parameters

Name Type Description Example
app string unique identifier or name of app "01234567-89ab-cdef-0123-456789abcdef" or "example"
recipient string unique identifier or email address of account "01234567-89ab-cdef-0123-456789abcdef" or "username@example.com"

Curl Example

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

Response Example

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

{
  "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 "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: 2400

{
  "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 -X GET 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: 2400

{
  "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 -X GET 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: 2400

[
  {
    "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

Name Type Description Example
state string the current state of an app transfer
one of:"pending" or "accepted" or "declined" 		"pending"

Curl Example

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

Response Example

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

{
  "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

Stability: production

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

Attributes

Name Type Description Example
archived_at nullable date-time when app was archived "2012-01-01T12:00:00Z"
build_stack:id uuid unique identifier of stack "01234567-89ab-cdef-0123-456789abcdef"
build_stack:name string unique name of stack "cedar"
buildpack_provided_description nullable string description from buildpack of app "Ruby/Rack"
created_at date-time when app was created "2012-01-01T12:00:00Z"
git_url string git repo URL of app "git@heroku.com:example.git"
id uuid unique identifier "01234567-89ab-cdef-0123-456789abcdef"
maintenance boolean maintenance status of app false
name string name of app "example"
owner:email email email address of account "username@example.com"
owner:id uuid unique identifier "01234567-89ab-cdef-0123-456789abcdef"
region:id uuid unique identifier of region "01234567-89ab-cdef-0123-456789abcdef"
region:name string unique name of region "us"
released_at nullable date-time when app was released "2012-01-01T12:00:00Z"
repo_size nullable integer git repo size in bytes of app 0
slug_size nullable integer slug size in bytes of app 0
stack:id uuid unique identifier of stack "01234567-89ab-cdef-0123-456789abcdef"
stack:name string unique name of stack "cedar"
updated_at date-time when app was updated "2012-01-01T12:00:00Z"
web_url uri web URL of app "https://example.herokuapp.com/"

App Create

Create a new app.

POST /apps

Optional Parameters

Name Type Description Example
name string name of app "example"
region string unique identifier or name of region "01234567-89ab-cdef-0123-456789abcdef" or "us"
stack string unique identifier or name of stack "01234567-89ab-cdef-0123-456789abcdef" or "cedar"

Curl Example

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

Response Example

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

{
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "git@heroku.com:example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "maintenance": false,
  "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,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "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 "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: 2400

{
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "git@heroku.com:example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "maintenance": false,
  "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,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "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 -X GET 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: 2400

{
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "git@heroku.com:example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "maintenance": false,
  "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,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "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 -X GET 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: 2400

[
  {
    "archived_at": "2012-01-01T12:00:00Z",
    "buildpack_provided_description": "Ruby/Rack",
    "build_stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "git_url": "git@heroku.com:example.git",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "maintenance": false,
    "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,
    "stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    },
    "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

Name Type Description Example
build_stack string unique identifier or name of stack "01234567-89ab-cdef-0123-456789abcdef" or "cedar"
maintenance boolean maintenance status of app false
name string name of app "example"

Curl Example

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

Response Example

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

{
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "build_stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "git@heroku.com:example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "maintenance": false,
  "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,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}

Build Result

Stability: production

A build result contains the output from a build.

Attributes

Name Type Description Example
build:id uuid unique identifier of build "01234567-89ab-cdef-0123-456789abcdef"
build:status string status of build
one of:"failed" or "pending" or "succeeded" 		"succeeded"
exit_code number status from the build 0
lines array A list of all the lines of a build’s output. [{"line":"-----\u003E Ruby app detected\n","stream":"STDOUT"}]

Build Result Info

Info for existing result.

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

Curl Example

$ curl -n -X GET 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: 2400

{
  "build": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "status": "succeeded"
  },
  "exit_code": 0,
  "lines": [
    {
      "line": "-----> Ruby app detected\n",
      "stream": "STDOUT"
    }
  ]
}

Build

Stability: production

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

Attributes

Name Type Description Example
created_at date-time when build was created "2012-01-01T12:00:00Z"
id uuid unique identifier of build "01234567-89ab-cdef-0123-456789abcdef"
slug nullable object slug created by this build null
slug:id uuid unique identifier of slug "01234567-89ab-cdef-0123-456789abcdef"
source_blob:url string URL where gzipped tar archive of source code for build was downloaded. "https://example.com/source.tgz?token=xyz"
source_blob:version nullable string Version of the gzipped tarball. "v1.3.0"
status string status of build
one of:"failed" or "pending" or "succeeded" 		"succeeded"
updated_at date-time when build was updated "2012-01-01T12:00:00Z"
user:email email email address of account "username@example.com"
user:id uuid unique identifier "01234567-89ab-cdef-0123-456789abcdef"

Build Create

Create a new build.

POST /apps/{app_id_or_name}/builds

Required Parameters

Name Type Description Example
source_blob:url string URL where gzipped tar archive of source code for build was downloaded. "https://example.com/source.tgz?token=xyz"
source_blob:version nullable string Version of the gzipped tarball. "v1.3.0"

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "source_blob": {
    "url": "https://example.com/source.tgz?token=xyz",
    "version": "v1.3.0"
  },
  "slug": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "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 -X GET 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: 2400

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "source_blob": {
    "url": "https://example.com/source.tgz?token=xyz",
    "version": "v1.3.0"
  },
  "slug": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "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 -X GET 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: 2400

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "source_blob": {
      "url": "https://example.com/source.tgz?token=xyz",
      "version": "v1.3.0"
    },
    "slug": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "status": "succeeded",
    "updated_at": "2012-01-01T12:00:00Z",
    "user": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com"
    }
  }
]

Buildpack Installations

Stability: production

An buildpack installtion represents a buildpack that will be run against an app.

Attributes

Name Type Description Example
buildpack:url string location of the buildpack for the app "https://github.com/heroku/heroku-buildpack-ruby"
ordinal integer determines the order in which the buildpacks will execute 0

Buildpack Installations Update

Update an app’s buildpack installations.

PUT /apps/{app_id_or_name}/buildpack-installations

Required Parameters

Name Type Description Example
updates array [{"buildpack"=>"https://github.com/heroku/heroku-buildpack-ruby"}]

Curl Example

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

Response Example

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

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

Buildpack Installations List

Info for existing buildpack installations.

GET /apps/{app_id_or_name}/buildpack-installations

Curl Example

$ curl -n -X GET 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: 2400

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

Collaborator

Stability: production

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

Attributes

Name Type Description Example
created_at date-time when collaborator was created "2012-01-01T12:00:00Z"
id uuid unique identifier of collaborator "01234567-89ab-cdef-0123-456789abcdef"
updated_at date-time when collaborator was updated "2012-01-01T12:00:00Z"
user:email email email address of account "username@example.com"
user:id uuid unique identifier "01234567-89ab-cdef-0123-456789abcdef"

Collaborator Create

Create a new collaborator.

POST /apps/{app_id_or_name}/collaborators

Required Parameters

Name Type Description Example
user string unique identifier or email address of account "01234567-89ab-cdef-0123-456789abcdef" or "username@example.com"

Optional Parameters

Name Type Description Example
silent boolean whether to suppress email invitation when creating collaborator false

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "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 "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: 2400

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "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 -X GET 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: 2400

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "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 -X GET 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: 2400

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "updated_at": "2012-01-01T12:00:00Z",
    "user": {
      "email": "username@example.com",
      "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

Get config-vars for app.

GET /apps/{app_id_or_name}/config-vars

Curl Example

$ curl -n -X GET 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: 2400

{
  "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 \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "FOO": "bar",
  "BAZ": "qux"
}'

Response Example

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

{
  "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

Name Type Description Example
amount number total value of credit in cents 10000
balance number remaining value of credit in cents 5000
created_at date-time when credit was created "2012-01-01T12:00:00Z"
expires_at date-time when credit will expire "2012-01-01T12:00:00Z"
id uuid unique identifier of credit "01234567-89ab-cdef-0123-456789abcdef"
title string a name for credit "gift card"
updated_at date-time when credit was updated "2012-01-01T12:00:00Z"

Credit Create

Create a new credit.

POST /account/credits

Optional Parameters

Name Type Description Example
code1 string first code from a discount card "012abc"
code2 string second code from a discount card "012abc"

Curl Example

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

Response Example

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

{
  "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 -X GET 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: 2400

{
  "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 -X GET 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: 2400

[
  {
    "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

Name Type Description Example
created_at date-time when domain was created "2012-01-01T12:00:00Z"
hostname string full hostname "subdomain.example.com"
id uuid unique identifier of this domain "01234567-89ab-cdef-0123-456789abcdef"
updated_at date-time when domain was updated "2012-01-01T12:00:00Z"

Domain Create

Create a new domain.

POST /apps/{app_id_or_name}/domains

Required Parameters

Name Type Description Example
hostname string full hostname "subdomain.example.com"

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "hostname": "subdomain.example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

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 "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: 2400

{
  "created_at": "2012-01-01T12:00:00Z",
  "hostname": "subdomain.example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

Domain Info

Info for existing domain.

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

Curl Example

$ curl -n -X GET 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: 2400

{
  "created_at": "2012-01-01T12:00:00Z",
  "hostname": "subdomain.example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

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 -X GET 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: 2400

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "hostname": "subdomain.example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Dyno

Stability: production

Dynos encapsulate running processes of an app on Heroku.

Attributes

Name Type Description Example
attach_url nullable string a URL to stream output from for attached processes or null for non-attached processes "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}"
command string command used to start this process "bash"
created_at date-time when dyno was created "2012-01-01T12:00:00Z"
id uuid unique identifier of this dyno "01234567-89ab-cdef-0123-456789abcdef"
name string the name of this process on this dyno "run.1"
release:id uuid unique identifier of release "01234567-89ab-cdef-0123-456789abcdef"
release:version integer unique version assigned to the release 11
size string dyno size (default: “1X”) "1X"
state string current status of process (either: crashed, down, idle, starting, or up) "up"
type string type of process "run"
updated_at date-time when process last changed state "2012-01-01T12:00:00Z"

Dyno Create

Create a new dyno.

POST /apps/{app_id_or_name}/dynos

Required Parameters

Name Type Description Example
command string command used to start this process "bash"

Optional Parameters

Name Type Description Example
attach boolean whether to stream output or not true
env object custom environment to add to the dyno config vars {"COLUMNS":"80","LINES":"24"}
size string dyno size (default: “1X”) "1X"

Curl Example

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

Response Example

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

{
  "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
  },
  "size": "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 "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: 2400







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 "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: 2400








  






Dyno Info



Info for existing dyno.




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







Curl Example




  
$ curl -n -X GET 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: 2400








  
{
  "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
  },
  "size": "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 -X GET 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: 2400








  
[
  {
    "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
    },
    "size": "1X",
    "state": "up",
    "type": "run",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]







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




  

    Name
    Type
    Description
    Example
  

  

    command
    string
    command to use to launch this process
    "bundle exec rails server -p $PORT"
  

  

    created_at
    date-time
    when process type was created
    "2012-01-01T12:00:00Z"
  

  

    id
    uuid
    unique identifier of this process type
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    quantity
    integer
    number of processes to maintain
    1
  

  

    size
    string
    dyno size (default: “1X”)
    "1X"
  

  

    type
    string
    type of process to maintain
    "web"
  

  

    updated_at
    date-time
    when dyno type was updated
    "2012-01-01T12:00:00Z"
  





Formation Info



Info for a process type




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







Curl Example




  
$ curl -n -X GET 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: 2400








  
{
  "command": "bundle exec rails server -p $PORT",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "quantity": 1,
  "size": "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 -X GET 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: 2400








  
[
  {
    "command": "bundle exec rails server -p $PORT",
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "quantity": 1,
    "size": "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




  

    Name
    Type
    Description
    Example
  

  

    updates
    array
    Array with formation updates. Each element must have “process”, the id or name of the process type to be updated, and can optionally update its “quantity” or “size”.
    [{"process":"web","quantity":1,"size":"2X"}]
  





Curl Example




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







Response Example




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








  
{
  "command": "bundle exec rails server -p $PORT",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "quantity": 1,
  "size": "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




  

    Name
    Type
    Description
    Example
  

  

    quantity
    integer
    number of processes to maintain
    1
  

  

    size
    string
    dyno size (default: “1X”)
    "1X"
  





Curl Example




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







Response Example




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








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







Invoice



Stability: development



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



Attributes




  

    Name
    Type
    Description
    Example
  

  

    charges_total
    number
    total charges on this invoice
    100.0
  

  

    created_at
    date-time
    when invoice was created
    "2012-01-01T12:00:00Z"
  

  

    credits_total
    number
    total credits on this invoice
    100.0
  

  

    id
    uuid
    unique identifier of this invoice
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    number
    integer
    human readable invoice number
    9403943
  

  

    total
    number
    combined total of charges and credits on this invoice
    100.0
  

  

    updated_at
    date-time
    when invoice was updated
    "2012-01-01T12:00:00Z"
  





Invoice Info



Info for existing invoice.




  
GET /account/invoices/{invoice_number}







Curl Example




  
$ curl -n -X GET 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: 2400








  
{
  "charges_total": 100.0,
  "created_at": "2012-01-01T12:00:00Z",
  "credits_total": 100.0,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "number": 9403943,
  "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 -X GET 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: 2400








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







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




  

    Name
    Type
    Description
    Example
  

  

    comment
    string
    comment on the key
    "username@host"
  

  

    created_at
    date-time
    when key was created
    "2012-01-01T12:00:00Z"
  

  

    email
    string
    deprecated. Please refer to ‘comment’ instead
    "username@host"
  

  

    fingerprint
    string
    a unique identifying string based on contents
    "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf"
  

  

    id
    uuid
    unique identifier of this key
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    public_key
    string
    full public_key as uploaded
    "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com"
  

  

    updated_at
    date-time
    when key was updated
    "2012-01-01T12:00:00Z"
  





Key Create



Create a new key.




  
POST /account/keys







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    public_key
    string
    full public_key as uploaded
    "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com"
  





Curl Example




  
$ curl -n -X POST https://api.heroku.com/account/keys \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "public_key": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com"
}'







Response Example




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








  
{
  "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 Delete



Delete an existing key




  
DELETE /account/keys/{key_id_or_fingerprint}







Curl Example




  
$ curl -n -X DELETE 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: 2400








  
{
  "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 Info



Info for existing key.




  
GET /account/keys/{key_id_or_fingerprint}







Curl Example




  
$ curl -n -X GET 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: 2400








  
{
  "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 -X GET 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: 2400








  
[
  {
    "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 addons will add a log drain when they are provisioned to an app. These drains can only be removed by removing the add-on.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    addon
    nullable object
    addon that created the drain
    "example"
  

  

    addon:id
    uuid
    unique identifier of add-on
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    created_at
    date-time
    when log drain was created
    "2012-01-01T12:00:00Z"
  

  

    id
    uuid
    unique identifier of this log drain
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    token
    string
    token associated with the log drain
    "d.01234567-89ab-cdef-0123-456789abcdef"
  

  

    updated_at
    date-time
    when log drain was updated
    "2012-01-01T12:00:00Z"
  

  

    url
    string
    url associated with the log drain
    "https://example.com/drain"
  





Log Drain Create



Create a new log drain.




  
POST /apps/{app_id_or_name}/log-drains







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    url
    string
    url associated with the log drain
    "https://example.com/drain"
  





Curl Example




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







Response Example




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








  
{
  "addon": "example",
  "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}







Curl Example




  
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL \
-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: 2400








  
{
  "addon": "example",
  "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}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL \
-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: 2400








  
{
  "addon": "example",
  "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.



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




  
GET /apps/{app_id_or_name}/log-drains







Curl Example




  
$ curl -n -X GET 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: id, 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: 2400








  
[
  {
    "addon": "example",
    "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




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when log connection was created
    "2012-01-01T12:00:00Z"
  

  

    id
    uuid
    unique identifier of this log session
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    logplex_url
    string
    URL for log streaming session
    "https://logplex.heroku.com/sessions/01234567-89ab-cdef-0123-456789abcdef?srv=1325419200"
  

  

    updated_at
    date-time
    when log session was updated
    "2012-01-01T12:00:00Z"
  





Log Session Create



Create a new log session.




  
POST /apps/{app_id_or_name}/log-sessions







Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    dyno
    string
    dyno to limit results to
    "web.1"
  

  

    lines
    integer
    number of log lines to stream at once
    10
  

  

    source
    string
    log source to limit results to
    "app"
  

  

    tail
    boolean
    whether to stream ongoing logs
    true
  





Curl Example




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







Response Example




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








  
{
  "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




  

    Name
    Type
    Description
    Example
  

  

    access_token
    nullable object
    access token for this authorization
    null
  

  

    access_token:expires_in
    nullable integer
    seconds until OAuth token expires; may be `null` for tokens with indefinite lifetime
    2592000
  

  

    access_token:id
    uuid
    unique identifier of OAuth token
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    access_token:token
    string
    contents of the token to be used for authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    client
    nullable object
    identifier of the client that obtained this authorization, if any
    null
  

  

    client:id
    uuid
    unique identifier of this OAuth client
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    client:name
    string
    OAuth client name
    "example"
  

  

    client:redirect_uri
    string
    endpoint for redirection after authorization with OAuth client
    "https://example.com/auth/heroku/callback"
  

  

    created_at
    date-time
    when OAuth authorization was created
    "2012-01-01T12:00:00Z"
  

  

    grant
    nullable object
    this authorization’s grant
    null
  

  

    grant:code
    string
    grant code received from OAuth web application authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    grant:expires_in
    integer
    seconds until OAuth grant expires
    2592000
  

  

    grant:id
    uuid
    unique identifier of OAuth grant
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    id
    uuid
    unique identifier of OAuth authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    refresh_token
    nullable object
    refresh token for this authorization
    null
  

  

    refresh_token:expires_in
    nullable integer
    seconds until OAuth token expires; may be `null` for tokens with indefinite lifetime
    2592000
  

  

    refresh_token:id
    uuid
    unique identifier of OAuth token
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    refresh_token:token
    string
    contents of the token to be used for authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    scope
    array
    The scope of access OAuth authorization allows
    ["global"]
  

  

    updated_at
    date-time
    when OAuth authorization was updated
    "2012-01-01T12:00:00Z"
  





OAuth Authorization Create



Create a new OAuth authorization.




  
POST /oauth/authorizations







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    scope
    array
    The scope of access OAuth authorization allows
    ["global"]
  





Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    client
    string
    unique identifier of this OAuth client
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    description
    string
    human-friendly description of this OAuth authorization
    "sample authorization"
  

  

    expires_in
    nullable integer
    seconds until OAuth token expires; may be `null` for tokens with indefinite lifetime
    2592000
  





Curl Example




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







Response Example




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








  
{
  "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"
}







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 "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: 2400








  
{
  "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"
}







OAuth Authorization Info



Info for an OAuth authorization.




  
GET /oauth/authorizations/{oauth_authorization_id}







Curl Example




  
$ curl -n -X GET 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: 2400








  
{
  "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"
}







OAuth Authorization List



List OAuth authorizations.



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




  
GET /oauth/authorizations







Curl Example




  
$ curl -n -X GET 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: 2400








  
[
  {
    "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"
  }
]







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 "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: 2400








  
{
  "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"
}







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




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when OAuth client was created
    "2012-01-01T12:00:00Z"
  

  

    id
    uuid
    unique identifier of this OAuth client
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    ignores_delinquent
    nullable boolean
    whether the client is still operable given a delinquent account
    false
  

  

    name
    string
    OAuth client name
    "example"
  

  

    redirect_uri
    string
    endpoint for redirection after authorization with OAuth client
    "https://example.com/auth/heroku/callback"
  

  

    secret
    string
    secret used to obtain OAuth authorizations under this client
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    updated_at
    date-time
    when OAuth client was updated
    "2012-01-01T12:00:00Z"
  





OAuth Client Create



Create a new OAuth client.




  
POST /oauth/clients







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    name
    string
    OAuth client name
    "example"
  

  

    redirect_uri
    string
    endpoint for redirection after authorization with OAuth client
    "https://example.com/auth/heroku/callback"
  





Curl Example




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







Response Example




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








  
{
  "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 "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: 2400








  
{
  "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 -X GET 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: 2400








  
{
  "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 -X GET 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: 2400








  
[
  {
    "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




  

    Name
    Type
    Description
    Example
  

  

    name
    string
    OAuth client name
    "example"
  

  

    redirect_uri
    string
    endpoint for redirection after authorization with OAuth client
    "https://example.com/auth/heroku/callback"
  





Curl Example




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







Response Example




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








  
{
  "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 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




  

    Name
    Type
    Description
    Example
  

  

    access_token:expires_in
    nullable integer
    seconds until OAuth token expires; may be `null` for tokens with indefinite lifetime
    2592000
  

  

    access_token:id
    uuid
    unique identifier of OAuth token
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    access_token:token
    string
    contents of the token to be used for authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    authorization:id
    uuid
    unique identifier of OAuth authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    client
    nullable object
    OAuth client secret used to obtain token
    null
  

  

    client:secret
    string
    secret used to obtain OAuth authorizations under this client
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    created_at
    date-time
    when OAuth token was created
    "2012-01-01T12:00:00Z"
  

  

    grant:code
    string
    grant code received from OAuth web application authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    grant:type
    string
    type of grant requested, one of `authorization_code` or `refresh_token`
    "authorization_code"
  

  

    id
    uuid
    unique identifier of OAuth token
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    refresh_token:expires_in
    nullable integer
    seconds until OAuth token expires; may be `null` for tokens with indefinite lifetime
    2592000
  

  

    refresh_token:id
    uuid
    unique identifier of OAuth token
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    refresh_token:token
    string
    contents of the token to be used for authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    session:id
    uuid
    unique identifier of OAuth token
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    updated_at
    date-time
    when OAuth token was updated
    "2012-01-01T12:00:00Z"
  

  

    user:id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  





OAuth Token Create



Create a new OAuth token.




  
POST /oauth/tokens







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    client:secret
    string
    secret used to obtain OAuth authorizations under this client
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    grant:code
    string
    grant code received from OAuth web application authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    grant:type
    string
    type of grant requested, one of `authorization_code` or `refresh_token`
    "authorization_code"
  

  

    refresh_token:token
    string
    contents of the token to be used for authorization
    "01234567-89ab-cdef-0123-456789abcdef"
  





Curl Example




  
$ curl -n -X POST https://api.heroku.com/oauth/tokens \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-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"
  }
}'







Response Example




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








  
{
  "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 App Collaborator



Stability: prototype



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



Attributes




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when collaborator was created
    "2012-01-01T12:00:00Z"
  

  

    id
    uuid
    unique identifier of collaborator
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    role
    string
    role in the organization
one of:"admin" or "member" or "collaborator"

    "admin"
  

  

    updated_at
    date-time
    when collaborator was updated
    "2012-01-01T12:00:00Z"
  

  

    user:email
    email
    email address of account
    "username@example.com"
  

  

    user:id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  





Organization App Collaborator Create



Create a new collaborator on an organization app. Use this endpoint instead of the /apps/{app_id_or_name}/collaborator endpoint when you want the collaborator to be granted privileges according to their role in the organization.




  
POST /organizations/apps/{app_id_or_name}/collaborators







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    user
    string
    unique identifier or email address of account
    
"01234567-89ab-cdef-0123-456789abcdef" or "username@example.com"

  





Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    silent
    boolean
    whether to suppress email invitation when creating collaborator
    false
  





Curl Example




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







Response Example




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








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}







Organization App Collaborator Delete



Delete an existing collaborator from an organization app.




  
DELETE /organizations/apps/{organization_app_name}/collaborators/{organization_app_collaborator_email}







Curl Example




  
$ curl -n -X DELETE https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME/collaborators/$ORGANIZATION_APP_COLLABORATOR_EMAIL \
-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: 2400








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}







Organization App Collaborator Info



Info for a collaborator on an organization app.




  
GET /organizations/apps/{organization_app_name}/collaborators/{organization_app_collaborator_email}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME/collaborators/$ORGANIZATION_APP_COLLABORATOR_EMAIL \
-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: 2400








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}







Organization App Collaborator List



List collaborators on an organization app.



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




  
GET /organizations/apps/{organization_app_name}/collaborators







Curl Example




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







Response Example




  
HTTP/1.1 200 OK
Accept-Ranges: email
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: 2400








  
[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "role": "admin",
    "updated_at": "2012-01-01T12:00:00Z",
    "user": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
]







Organization App



Stability: prototype



An organization app encapsulates the organization specific functionality of Heroku apps.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    archived_at
    nullable date-time
    when app was archived
    "2012-01-01T12:00:00Z"
  

  

    buildpack_provided_description
    nullable string
    description from buildpack of app
    "Ruby/Rack"
  

  

    created_at
    date-time
    when app was created
    "2012-01-01T12:00:00Z"
  

  

    git_url
    string
    git repo URL of app
    "git@heroku.com:example.git"
  

  

    id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    joined
    boolean
    is the current member a collaborator on this app.
    false
  

  

    locked
    boolean
    are other organization members forbidden from joining this app.
    false
  

  

    maintenance
    boolean
    maintenance status of app
    false
  

  

    name
    string
    name of app
    "example"
  

  

    organization
    nullable object
    organization that owns this app
    null
  

  

    organization:name
    string
    unique name of organization
    "example"
  

  

    owner
    nullable object
    identity of app owner
    null
  

  

    owner:email
    email
    email address of account
    "username@example.com"
  

  

    owner:id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    region:id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    region:name
    string
    name of region
    "us"
  

  

    released_at
    nullable date-time
    when app was released
    "2012-01-01T12:00:00Z"
  

  

    repo_size
    nullable integer
    git repo size in bytes of app
    0
  

  

    slug_size
    nullable integer
    slug size in bytes of app
    0
  

  

    stack:id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    stack:name
    string
    name of stack
    "cedar"
  

  

    updated_at
    date-time
    when app was updated
    "2012-01-01T12:00:00Z"
  

  

    web_url
    uri
    web URL of app
    "https://example.herokuapp.com/"
  





Organization App Create



Create a new app in the specified organization, in the default organization if unspecified,  or in personal account, if default organization is not set.




  
POST /organizations/apps







Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    locked
    boolean
    are other organization members forbidden from joining this app.
    false
  

  

    name
    string
    name of app
    "example"
  

  

    organization
    string
    unique name of organization
    "example"
  

  

    personal
    boolean
    force creation of the app in the user account even if a default org is set.
    false
  

  

    region
    string
    name of region
    "us"
  

  

    stack
    string
    name of stack
    "cedar"
  





Curl Example




  
$ curl -n -X POST https://api.heroku.com/organizations/apps \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "locked": false,
  "name": "example",
  "organization": "example",
  "personal": false,
  "region": "us",
  "stack": "cedar"
}'







Response Example




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








  
{
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "git@heroku.com:example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "joined": false,
  "locked": false,
  "maintenance": false,
  "name": "example",
  "organization": {
    "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,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}







Organization App List



List apps in the default organization, or in personal account, if default organization is not set.



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




  
GET /organizations/apps







Curl Example




  
$ curl -n -X GET https://api.heroku.com/organizations/apps \
-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: 2400








  
[
  {
    "archived_at": "2012-01-01T12:00:00Z",
    "buildpack_provided_description": "Ruby/Rack",
    "created_at": "2012-01-01T12:00:00Z",
    "git_url": "git@heroku.com:example.git",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "joined": false,
    "locked": false,
    "maintenance": false,
    "name": "example",
    "organization": {
      "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,
    "stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://example.herokuapp.com/"
  }
]







Organization App List For Organization



List organization apps.



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




  
GET /organizations/{organization_name}/apps







Curl Example




  
$ curl -n -X GET https://api.heroku.com/organizations/$ORGANIZATION_NAME/apps \
-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: 2400








  
[
  {
    "archived_at": "2012-01-01T12:00:00Z",
    "buildpack_provided_description": "Ruby/Rack",
    "created_at": "2012-01-01T12:00:00Z",
    "git_url": "git@heroku.com:example.git",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "joined": false,
    "locked": false,
    "maintenance": false,
    "name": "example",
    "organization": {
      "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,
    "stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://example.herokuapp.com/"
  }
]







Organization App Info



Info for an organization app.




  
GET /organizations/apps/{organization_app_name}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_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: 2400








  
{
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "git@heroku.com:example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "joined": false,
  "locked": false,
  "maintenance": false,
  "name": "example",
  "organization": {
    "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,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}







Organization App Update Locked



Lock or unlock an organization app.




  
PATCH /organizations/apps/{organization_app_name}







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    locked
    boolean
    are other organization members forbidden from joining this app.
    false
  





Curl Example




  
$ curl -n -X PATCH https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "locked": false
}'







Response Example




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








  
{
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "git@heroku.com:example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "joined": false,
  "locked": false,
  "maintenance": false,
  "name": "example",
  "organization": {
    "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,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}







Organization App Transfer to Account



Transfer an existing organization app to another Heroku account.




  
PATCH /organizations/apps/{organization_app_name}







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    owner
    string
    unique identifier or email address of account
    
"01234567-89ab-cdef-0123-456789abcdef" or "username@example.com"

  





Curl Example




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







Response Example




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








  
{
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "git@heroku.com:example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "joined": false,
  "locked": false,
  "maintenance": false,
  "name": "example",
  "organization": {
    "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,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}







Organization App Transfer to Organization



Transfer an existing organization app to another organization.




  
PATCH /organizations/apps/{organization_app_name}







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    owner
    string
    unique name of organization
    "example"
  





Curl Example




  
$ curl -n -X PATCH https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "owner": "example"
}'







Response Example




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








  
{
  "archived_at": "2012-01-01T12:00:00Z",
  "buildpack_provided_description": "Ruby/Rack",
  "created_at": "2012-01-01T12:00:00Z",
  "git_url": "git@heroku.com:example.git",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "joined": false,
  "locked": false,
  "maintenance": false,
  "name": "example",
  "organization": {
    "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,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://example.herokuapp.com/"
}







Organization Member



Stability: prototype



An organization member is an individual with access to an organization.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when the membership record was created
    "2012-01-01T12:00:00Z"
  

  

    email
    string
    email address of the organization member
    "someone@example.org"
  

  

    role
    string
    role in the organization
one of:"admin" or "member" or "collaborator"

    "admin"
  

  

    two_factor_authentication
    boolean
    whether the organization member has two factor authentication enabled
    true
  

  

    updated_at
    date-time
    when the membership record was updated
    "2012-01-01T12:00:00Z"
  





Organization Member Create or Update



Create a new organization member, or update their role.




  
PUT /organizations/{organization_name}/members







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    email
    string
    email address of the organization member
    "someone@example.org"
  

  

    role
    string
    role in the organization
one of:"admin" or "member" or "collaborator"

    "admin"
  





Curl Example




  
$ curl -n -X PUT https://api.heroku.com/organizations/$ORGANIZATION_NAME/members \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "email": "someone@example.org",
  "role": "admin"
}'







Response Example




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








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "email": "someone@example.org",
  "role": "admin",
  "two_factor_authentication": true,
  "updated_at": "2012-01-01T12:00:00Z"
}







Organization Member Delete



Remove a member from the organization.




  
DELETE /organizations/{organization_name}/members/{organization_member_email}







Curl Example




  
$ curl -n -X DELETE https://api.heroku.com/organizations/$ORGANIZATION_NAME/members/$ORGANIZATION_MEMBER_EMAIL \
-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: 2400








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "email": "someone@example.org",
  "role": "admin",
  "two_factor_authentication": true,
  "updated_at": "2012-01-01T12:00:00Z"
}







Organization Member List



List members of the organization.



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




  
GET /organizations/{organization_name}/members







Curl Example




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







Response Example




  
HTTP/1.1 200 OK
Accept-Ranges: email
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: 2400








  
[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "email": "someone@example.org",
    "role": "admin",
    "two_factor_authentication": true,
    "updated_at": "2012-01-01T12:00:00Z"
  }
]







Organization



Stability: prototype



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



Attributes




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when the organization was created
    "2012-01-01T12:00:00Z"
  

  

    credit_card_collections
    boolean
    whether charges incurred by the org are paid by credit card.
    true
  

  

    default
    boolean
    whether to use this organization when none is specified
    true
  

  

    name
    string
    unique name of organization
    "example"
  

  

    provisioned_licenses
    boolean
    whether the org is provisioned licenses by salesforce.
    true
  

  

    role
    string
    role in the organization
one of:"admin" or "member" or "collaborator"

    "admin"
  

  

    updated_at
    date-time
    when the organization was updated
    "2012-01-01T12:00:00Z"
  





Organization List



List organizations in which you are a member.



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




  
GET /organizations







Curl Example




  
$ curl -n -X GET https://api.heroku.com/organizations \
-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: 2400








  
[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "credit_card_collections": true,
    "default": true,
    "name": "example",
    "provisioned_licenses": true,
    "role": "admin",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]







Organization Info



Info for an organization.




  
GET /organizations/{organization_name}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/organizations/$ORGANIZATION_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: 2400








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "credit_card_collections": true,
  "default": true,
  "name": "example",
  "provisioned_licenses": true,
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z"
}







Organization Update



Set or unset the organization as your default organization.




  
PATCH /organizations/{organization_name}







Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    default
    boolean
    whether to use this organization when none is specified
    true
  





Curl Example




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







Response Example




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








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "credit_card_collections": true,
  "default": true,
  "name": "example",
  "provisioned_licenses": true,
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z"
}







OTP Secret



Stability: development



This renders a secret that clients can use to build a one-time password to be supplied as a 2nd factor of authentication.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when OTP secret was created
    "2012-01-01T12:00:00Z"
  

  

    id
    uuid
    unique identifier of OTP secret
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    updated_at
    date-time
    when OTP secret was updated
    "2012-01-01T12:00:00Z"
  

  

    url
    string
    OTP secret rendered in URL format
    "otpauth://totp/username@example.com?issuer=Heroku\u0026secret=abcd1234"
  





OTP Secret Create



Create new OTP secret. This invalidates any existing OTP secrets on the account.




  
POST /account/otp-secret







Curl Example




  
$ curl -n -X POST https://api.heroku.com/account/otp-secret \
-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: 2400








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "otpauth://totp/username@example.com?issuer=Heroku&secret=abcd1234"
}







Payments



Stability: prototype



A payment represents money collected for an account



Attributes




  

    Name
    Type
    Description
    Example
  

  

    amount
    $500.00 in cents - which would be 50000
    amount of payment
    50000
  

  

    created_at
    date-time
    when payment was created
    "2012-01-01T12:00:00Z"
  

  

    id
    integer
    legacy unique identifier of payment
    9403943
  

  

    invoice
    nullable object
    identity of invoice
    null
  

  

    invoice:id
    uuid
    unique identifier of this invoice
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    invoice:number
    integer
    human readable invoice number
    9403943
  

  

    state
    string
    state of the payment
one of:"failure" or "pending" or "success"

    "pending"
  

  

    updated_at
    date-time
    when credit was updated
    "2012-01-01T12:00:00Z"
  

  

    user:email
    email
    email address of account
    "username@example.com"
  

  

    user:id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  





Payments create



Create a payment on an existing account




  
POST /account/payments







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    amount
    $500.00 in cents - which would be 50000
    amount of payment
    50000
  

  

    invoice
    string
    human readable invoice number
    9403943
  

  

    uuid
    uuid
    unique identifier for a payment transaction
    "01234567-89ab-cdef-0123-456789abcdef"
  





Curl Example




  
$ curl -n -X POST https://api.heroku.com/account/payments \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "amount": 50000,
  "invoice": 9403943,
  "uuid": "01234567-89ab-cdef-0123-456789abcdef"
}'







Response Example




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








  
{
  "amount": 50000,
  "created_at": "2012-01-01T12:00:00Z",
  "id": 9403943,
  "invoice": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "number": 9403943
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "state": "pending"
}







Payment Method



Stability: prototype



The on file payment method for an account



Attributes




  

    Name
    Type
    Description
    Example
  

  

    address_1
    string
    street address line 1
    "40 Hickory Lane"
  

  

    address_2
    string
    street address line 2
    "Suite 103"
  

  

    card_number
    string
    encrypted card number of payment method
    "encrypted-card-number"
  

  

    city
    string
    city
    "San Francisco"
  

  

    country
    string
    country
    "US"
  

  

    cvv
    string
    card verification value
    "123"
  

  

    expiration_month
    string
    expiration month
    "11"
  

  

    expiration_year
    string
    expiration year
    "2014"
  

  

    first_name
    string
    the first name for payment method
    "Jason"
  

  

    last_name
    string
    the last name for payment method
    "Walker"
  

  

    other
    string
    metadata
    "Additional information for payment method"
  

  

    postal_code
    string
    postal code
    "90210"
  

  

    state
    string
    state
    "CA"
  





Payment Method update



Update an existing payment method for an account.




  
PUT /account/payment-method







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    address_1
    string
    street address line 1
    "40 Hickory Lane"
  

  

    address_2
    string
    street address line 2
    "Suite 103"
  

  

    card_number
    string
    encrypted card number of payment method
    "encrypted-card-number"
  

  

    city
    string
    city
    "San Francisco"
  

  

    country
    string
    country
    "US"
  

  

    cvv
    string
    card verification value
    "123"
  

  

    expiration_month
    string
    expiration month
    "11"
  

  

    expiration_year
    string
    expiration year
    "2014"
  

  

    first_name
    string
    the first name for payment method
    "Jason"
  

  

    last_name
    string
    the last name for payment method
    "Walker"
  

  

    postal_code
    string
    postal code
    "90210"
  

  

    state
    string
    state
    "CA"
  





Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    other
    string
    metadata
    "Additional information for payment method"
  





Curl Example




  
$ curl -n -X PUT https://api.heroku.com/account/payment-method \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "address_1": "40 Hickory Lane",
  "address_2": "Suite 103",
  "card_number": "encrypted-card-number",
  "city": "San Francisco",
  "country": "US",
  "cvv": "123",
  "expiration_month": "11",
  "expiration_year": "2014",
  "first_name": "Jason",
  "last_name": "Walker",
  "other": "Additional information for payment method",
  "postal_code": "90210",
  "state": "CA"
}'







Response Example




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








  






Plan



Stability: production



Plans represent different configurations of add-ons that may be added to apps. Endpoints under add-on services can be accessed without authentication.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when plan was created
    "2012-01-01T12:00:00Z"
  

  

    default
    boolean
    whether this plan is the default for its addon service
    false
  

  

    description
    string
    description of plan
    "Heroku Postgres Dev"
  

  

    human_name
    string
    human readable name of the addon plan
    "Dev"
  

  

    id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    name
    string
    name of this plan
    "heroku-postgresql:dev"
  

  

    price:cents
    integer
    price in cents per unit of plan
    0
  

  

    price:unit
    string
    unit of price for plan
    "month"
  

  

    state
    string
    release status for plan
    "public"
  

  

    updated_at
    date-time
    when plan was updated
    "2012-01-01T12:00:00Z"
  





Plan Info



Info for existing plan.




  
GET /addon-services/{addon_service_id_or_name}/plans/{plan_id_or_name}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/addon-services/$ADDON_SERVICE_ID_OR_NAME/plans/$PLAN_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: 2400








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "default": false,
  "description": "Heroku Postgres Dev",
  "human_name": "Dev",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "heroku-postgresql:dev",
  "price": {
    "cents": 0,
    "unit": "month"
  },
  "state": "public",
  "updated_at": "2012-01-01T12:00:00Z"
}







Plan List



List existing plans.



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




  
GET /addon-services/{addon_service_id_or_name}/plans







Curl Example




  
$ curl -n -X GET https://api.heroku.com/addon-services/$ADDON_SERVICE_ID_OR_NAME/plans \
-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: 2400








  
[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "default": false,
    "description": "Heroku Postgres Dev",
    "human_name": "Dev",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql:dev",
    "price": {
      "cents": 0,
      "unit": "month"
    },
    "state": "public",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]







Rate Limit



Stability: production



Rate Limit represents the number of request tokens each account holds. Requests to this endpoint do not count towards the rate limit.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    remaining
    integer
    allowed requests remaining in current interval
    2399
  





Rate Limit Info



Info for rate limits.




  
GET /account/rate-limits







Curl Example




  
$ curl -n -X GET https://api.heroku.com/account/rate-limits \
-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: 2400








  
{
  "remaining": 2399
}







Recovery Code



Stability: development



Recovery codes grant access to accounts with two-factor authentication enabled.



Recovery Code Create



Generate new recovery codes. This invalidates any existing codes on the account.




  
POST /account/recovery-codes







Curl Example




  
$ curl -n -X POST https://api.heroku.com/account/recovery-codes \
-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: 2400








  
[
  "0123456789abcdef"
]







Region



Stability: production



A region represents a geographic location in which your application may run.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when region was created
    "2012-01-01T12:00:00Z"
  

  

    description
    string
    description of region
    "United States"
  

  

    id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    name
    string
    name of region
    "us"
  

  

    updated_at
    date-time
    when region was updated
    "2012-01-01T12:00:00Z"
  





Region Info



Info for existing region.




  
GET /regions/{region_id_or_name}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/regions/$REGION_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: 2400








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "description": "United States",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "us",
  "updated_at": "2012-01-01T12:00:00Z"
}







Region List



List existing regions.



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




  
GET /regions







Curl Example




  
$ curl -n -X GET https://api.heroku.com/regions \
-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: 2400








  
[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "description": "United States",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]







Release



Stability: production



A release represents a combination of code, config vars and add-ons for an app on Heroku.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when release was created
    "2012-01-01T12:00:00Z"
  

  

    description
    string
    description of changes in this release
    "Added new feature"
  

  

    id
    uuid
    unique identifier of release
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    slug
    nullable object
    slug running in this release
    null
  

  

    slug:id
    uuid
    unique identifier of slug
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    updated_at
    date-time
    when release was updated
    "2012-01-01T12:00:00Z"
  

  

    user:email
    email
    email address of account
    "username@example.com"
  

  

    user:id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    version
    integer
    unique version assigned to the release
    11
  





Release Info



Info for existing release.




  
GET /apps/{app_id_or_name}/releases/{release_id_or_version}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/releases/$RELEASE_ID_OR_VERSION \
-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: 2400








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "description": "Added new feature",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "slug": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com"
  },
  "version": 11
}







Release List



List existing releases.



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




  
GET /apps/{app_id_or_name}/releases







Curl Example




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







Response Example




  
HTTP/1.1 200 OK
Accept-Ranges: id, version
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: 2400








  
[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "description": "Added new feature",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "updated_at": "2012-01-01T12:00:00Z",
    "slug": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "user": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com"
    },
    "version": 11
  }
]







Release Create



Create new release. The API cannot be used to create releases on Bamboo apps.




  
POST /apps/{app_id_or_name}/releases







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    slug
    string
    unique identifier of slug
    "01234567-89ab-cdef-0123-456789abcdef"
  





Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    description
    string
    description of changes in this release
    "Added new feature"
  





Curl Example




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







Response Example




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








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "description": "Added new feature",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "slug": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com"
  },
  "version": 11
}







Release Rollback



Rollback to an existing release.




  
POST /apps/{app_id_or_name}/releases







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    release
    uuid
    unique identifier of release
    "01234567-89ab-cdef-0123-456789abcdef"
  





Curl Example




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







Response Example




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








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "description": "Added new feature",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z",
  "slug": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com"
  },
  "version": 11
}







Slug



Stability: production



A slug is a snapshot of your application code that is ready to run on the platform.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    blob:method
    string
    method to be used to interact with the slug blob
    "GET"
  

  

    blob:url
    string
    URL to interact with the slug blob
    "https://api.heroku.com/slugs/1234.tgz"
  

  

    buildpack_provided_description
    nullable string
    description from buildpack of slug
    "Ruby/Rack"
  

  

    commit
    nullable string
    identification of the code with your version control system (eg: SHA of the git HEAD)
    "60883d9e8947a57e04dc9124f25df004866a2051"
  

  

    commit_description
    nullable string
    an optional description of the provided commit
    "fixed a bug with API documentation"
  

  

    created_at
    date-time
    when slug was created
    "2012-01-01T12:00:00Z"
  

  

    id
    uuid
    unique identifier of slug
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    process_types
    object
    hash mapping process type names to their respective command
    {"web":"./bin/web -p $PORT"}
  

  

    size
    nullable integer
    size of slug, in bytes
    2048
  

  

    stack:id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    stack:name
    string
    name of stack
    "cedar"
  

  

    updated_at
    date-time
    when slug was updated
    "2012-01-01T12:00:00Z"
  





Slug Info



Info for existing slug.




  
GET /apps/{app_id_or_name}/slugs/{slug_id}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/slugs/$SLUG_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: 2400








  
{
  "blob": {
    "method": "GET",
    "url": "https://api.heroku.com/slugs/1234.tgz"
  },
  "buildpack_provided_description": "Ruby/Rack",
  "commit": "60883d9e8947a57e04dc9124f25df004866a2051",
  "commit_description": "fixed a bug with API documentation",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "process_types": {
    "web": "./bin/web -p $PORT"
  },
  "size": 2048,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "updated_at": "2012-01-01T12:00:00Z"
}







Slug Create



Create a new slug. For more information please refer to Deploying Slugs using the Platform API.




  
POST /apps/{app_id_or_name}/slugs







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    process_types
    object
    hash mapping process type names to their respective command
    {"web":"./bin/web -p $PORT"}
  





Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    buildpack_provided_description
    nullable string
    description from buildpack of slug
    "Ruby/Rack"
  

  

    commit
    nullable string
    identification of the code with your version control system (eg: SHA of the git HEAD)
    "60883d9e8947a57e04dc9124f25df004866a2051"
  

  

    commit_description
    nullable string
    an optional description of the provided commit
    "fixed a bug with API documentation"
  

  

    stack
    string
    unique identifier or name of stack
    
"01234567-89ab-cdef-0123-456789abcdef" or "cedar"

  





Curl Example




  
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/slugs \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "buildpack_provided_description": "Ruby/Rack",
  "commit": "60883d9e8947a57e04dc9124f25df004866a2051",
  "commit_description": "fixed a bug with API documentation",
  "process_types": {
    "web": "./bin/web -p $PORT"
  },
  "stack": "01234567-89ab-cdef-0123-456789abcdef"
}'







Response Example




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








  
{
  "blob": {
    "method": "GET",
    "url": "https://api.heroku.com/slugs/1234.tgz"
  },
  "buildpack_provided_description": "Ruby/Rack",
  "commit": "60883d9e8947a57e04dc9124f25df004866a2051",
  "commit_description": "fixed a bug with API documentation",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "process_types": {
    "web": "./bin/web -p $PORT"
  },
  "size": 2048,
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "updated_at": "2012-01-01T12:00:00Z"
}







Source



Stability: prototype



A source is a location for uploading and downloading an application’s source code.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    source_blob:get_url
    string
    URL to download the source
    "https://api.heroku.com/slugs/1234.tgz"
  

  

    source_blob:put_url
    string
    URL to upload the source
    "https://api.heroku.com/slugs/1234.tgz"
  





Source Create



Create URLs for uploading and downloading source.




  
POST /apps/{app_id_or_name}/sources







Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    source_blob:get_url
    string
    URL to download the source
    "https://api.heroku.com/slugs/1234.tgz"
  

  

    source_blob:put_url
    string
    URL to upload the source
    "https://api.heroku.com/slugs/1234.tgz"
  





Curl Example




  
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/sources \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "source_blob": {
    "get_url": "https://api.heroku.com/slugs/1234.tgz",
    "put_url": "https://api.heroku.com/slugs/1234.tgz"
  }
}'







Response Example




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








  
{
  "source_blob": {
    "get_url": "https://api.heroku.com/slugs/1234.tgz",
    "put_url": "https://api.heroku.com/slugs/1234.tgz"
  }
}







SSL Endpoint



Stability: production



SSL Endpoint is a public address serving custom SSL cert for HTTPS traffic to a Heroku app. Note that an app must have the ssl:endpoint addon installed before it can provision an SSL Endpoint using these APIs.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    certificate_chain
    string
    raw contents of the public certificate chain (eg: .crt or .pem file)
    "-----BEGIN CERTIFICATE----- ..."
  

  

    cname
    string
    canonical name record, the address to point a domain at
    "example.herokussl.com"
  

  

    created_at
    date-time
    when endpoint was created
    "2012-01-01T12:00:00Z"
  

  

    id
    uuid
    unique identifier of this SSL endpoint
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    name
    string
    unique name for SSL endpoint
    "example"
  

  

    updated_at
    date-time
    when endpoint was updated
    "2012-01-01T12:00:00Z"
  





SSL Endpoint Create



Create a new SSL endpoint.




  
POST /apps/{app_id_or_name}/ssl-endpoints







Required Parameters




  

    Name
    Type
    Description
    Example
  

  

    certificate_chain
    string
    raw contents of the public certificate chain (eg: .crt or .pem file)
    "-----BEGIN CERTIFICATE----- ..."
  

  

    private_key
    string
    contents of the private key (eg .key file)
    "-----BEGIN RSA PRIVATE KEY----- ..."
  





Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    preprocess
    boolean
    allow Heroku to modify an uploaded public certificate chain if deemed advantageous by adding missing intermediaries, stripping unnecessary ones, etc.
default: true

    true
  





Curl Example




  
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "preprocess": true,
  "private_key": "-----BEGIN RSA PRIVATE KEY----- ..."
}'







Response Example




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








  
{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "cname": "example.herokussl.com",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z"
}







SSL Endpoint Delete



Delete existing SSL endpoint.




  
DELETE /apps/{app_id_or_name}/ssl-endpoints/{ssl_endpoint_id_or_name}







Curl Example




  
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints/$SSL_ENDPOINT_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: 2400








  
{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "cname": "example.herokussl.com",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z"
}







SSL Endpoint Info



Info for existing SSL endpoint.




  
GET /apps/{app_id_or_name}/ssl-endpoints/{ssl_endpoint_id_or_name}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints/$SSL_ENDPOINT_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: 2400








  
{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "cname": "example.herokussl.com",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z"
}







SSL Endpoint List



List existing SSL endpoints.



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




  
GET /apps/{app_id_or_name}/ssl-endpoints







Curl Example




  
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints \
-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: 2400








  
[
  {
    "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
    "cname": "example.herokussl.com",
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]







SSL Endpoint Update



Update an existing SSL endpoint.




  
PATCH /apps/{app_id_or_name}/ssl-endpoints/{ssl_endpoint_id_or_name}







Optional Parameters




  

    Name
    Type
    Description
    Example
  

  

    certificate_chain
    string
    raw contents of the public certificate chain (eg: .crt or .pem file)
    "-----BEGIN CERTIFICATE----- ..."
  

  

    preprocess
    boolean
    allow Heroku to modify an uploaded public certificate chain if deemed advantageous by adding missing intermediaries, stripping unnecessary ones, etc.
default: true

    true
  

  

    private_key
    string
    contents of the private key (eg .key file)
    "-----BEGIN RSA PRIVATE KEY----- ..."
  

  

    rollback
    boolean
    indicates that a rollback should be performed
    false
  





Curl Example




  
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints/$SSL_ENDPOINT_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "preprocess": true,
  "private_key": "-----BEGIN RSA PRIVATE KEY----- ...",
  "rollback": false
}'







Response Example




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








  
{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "cname": "example.herokussl.com",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z"
}







Stack



Stability: production



Stacks are the different application execution environments available in the Heroku platform.



Attributes




  

    Name
    Type
    Description
    Example
  

  

    created_at
    date-time
    when stack was introduced
    "2012-01-01T12:00:00Z"
  

  

    id
    uuid
    unique identifier
    "01234567-89ab-cdef-0123-456789abcdef"
  

  

    name
    string
    name of stack
    "cedar"
  

  

    state
    string
    availability of this stack: beta, deprecated or public
    "public"
  

  

    updated_at
    date-time
    when stack was last modified
    "2012-01-01T12:00:00Z"
  





Stack Info



Stack info.




  
GET /stacks/{stack_name_or_id}







Curl Example




  
$ curl -n -X GET https://api.heroku.com/stacks/$STACK_NAME_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: 2400








  
{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "cedar",
  "state": "public",
  "updated_at": "2012-01-01T12:00:00Z"
}







Stack List



List available stacks.



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




  
GET /stacks







Curl Example




  
$ curl -n -X GET https://api.heroku.com/stacks \
-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: 2400








  
[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar",
    "state": "public",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]