Platform API Reference | Heroku Dev Center

Last updated February 13, 2026

Overview

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

Authentication

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

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

Caching

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

Clients

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

CORS

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

Schema

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

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

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

cURL Examples

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

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

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

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

Custom Types

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

Escaping

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

Methods

Method	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 4500 tokens. Each API call removes one token from the pool. Tokens are added to the account pool at a rate of roughly 75 per minute (or 4500 per hour), up to a maximum of 4500. If no tokens remain, further calls will return 429 Too Many Requests until more tokens become available.

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

Request Id

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

Responses

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

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
409 Conflict	conflict	request failed, see response body for suggested resolution
410 Gone	gone	requested resource can no longer be found at this location, see the Platform API Reference for alternatives.
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

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
country_of_residence	nullable string	country where account owner resides	"United States"
created_at	date-time	when account was created	"2012-01-01T12:00:00Z"
default_organization	nullable object	team selected by default	null
default_organization:id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
default_organization:name	string	unique name of team	"example"
default_team	nullable object	team selected by default	null
default_team:id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
default_team:name	string	unique name of team	"example"
delinquent_at	nullable date-time	when account became delinquent	"2012-01-01T12:00:00Z"
email	email	unique email address of account	"username@example.com"
federated	boolean	whether the user is federated and belongs to an Identity Provider	false
id	uuid	unique identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider	nullable object	Identity Provider details for federated users.	null
identity_provider:id	uuid	unique identifier of this identity provider	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:name	string	user-friendly unique identifier for this identity provider	"acme-sso"
identity_provider:organization:name	string	unique name of team	"example"
identity_provider:owner:id	uuid	unique identifier of the owner	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:owner:name	string	name of the owner	"acme"
identity_provider:owner:type	string	type of the owner one of:"team" or "enterprise-account"	"team"
identity_provider:team:name	string	unique name of team	"example"
last_login	nullable date-time	when account last authorized with Heroku	"2012-01-01T12:00:00Z"
name	nullable string	full name of the account owner	"Tina Edmonds"
sms_number	nullable string	SMS number of account	"+1 ***-***-1234"
suspended_at	nullable date-time	when account was suspended	"2012-01-01T12:00:00Z"
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 https://api.heroku.com/account \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

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"

Curl Example

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

Response Example

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

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

Account Delete

Delete account. Note that this action cannot be undone. Note: This endpoint requires the HTTP_HEROKU_PASSWORD or HTTP_HEROKU_PASSWORD_BASE64 header be set correctly for the user account.

DELETE /account

Curl Example

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

Response Example

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

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

Account Info By User

Info for account.

GET /users/{account_email_or_id_or_self}

Curl Example

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

Response Example

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

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

Account Update By User

Update account.

PATCH /users/{account_email_or_id_or_self}

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"

Curl Example

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

Response Example

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

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

Account Delete By User

Delete account. Note that this action cannot be undone. Note: This endpoint requires the HTTP_HEROKU_PASSWORD or HTTP_HEROKU_PASSWORD_BASE64 header be set correctly for the user account.

DELETE /users/{account_email_or_id_or_self}

Curl Example

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

Response Example

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

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

Account Delinquency

Stability: development

A Heroku account becomes delinquent due to non-payment. We suspend and delete delinquent accounts if their invoices remain unpaid.

Attributes

Name	Type	Description	Example
scheduled_deletion_time	nullable date-time	scheduled time of when we will delete your account due to delinquency	"2024-01-01T12:00:00Z"
scheduled_suspension_time	nullable date-time	scheduled time of when we will suspend your account due to delinquency	"2024-01-01T12:00:00Z"

Account Delinquency Info

Account delinquency information.

GET /account/delinquency

Curl Example

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

Response Example

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

{
  "scheduled_suspension_time": "2024-01-01T12:00:00Z",
  "scheduled_deletion_time": "2024-01-01T12:00:00Z"
}

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."
display_name	string	user readable feature name	"My Feature"
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
feedback_email	string	e-mail to send feedback about the feature	"feedback@heroku.com"
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 https://api.heroku.com/account/features/$ACCOUNT_FEATURE_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Account Feature List

List existing account features.

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

GET /account/features

Curl Example

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

Response Example

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

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

Account Feature Update

Update an existing account feature.

PATCH /account/features/{account_feature_id_or_name}

Required Parameters

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

Response Example

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

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

Add-on

Stability: production

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

Attributes

Name	Type	Description	Example
actions:action	string	identifier of the action to take that is sent via SSO	"example"
actions:id	uuid	a unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
actions:label	string	the display text shown in Dashboard	"Example"
actions:requires_owner	boolean	if the action requires the user to own the app	true
actions:url	string	absolute URL to use instead of an action	"http://example.com?resource_id=:resource_id"
addon_service:id	uuid	unique identifier of this add-on-service	"01234567-89ab-cdef-0123-456789abcdef"
addon_service:name	string	unique name of this add-on-service	"heroku-postgresql"
app:id	uuid	unique identifier of app	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	unique name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
billed_price	nullable object	billed price	null
billed_price:cents	integer	price in cents per unit of plan	0
billed_price:contract	boolean	price is negotiated in a contract outside of monthly add-on billing	false
billed_price:unit	string	unit of price for plan	"month"
billing_entity:id	uuid	unique identifier of the billing entity	"01234567-89ab-cdef-0123-456789abcdef"
billing_entity:name	string	name of the billing entity	"example"
billing_entity:type	string	type of Object of the billing entity; new types allowed at any time. one of:"app" or "team"	"app"
config_vars	array	config vars exposed to the owning app by this add-on	["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	globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$	"acme-inc-primary-database"
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	"abcd1234"
provision_message	string	A provision message	"example"
state	string	state in the add-on’s lifecycle one of:"provisioning" or "provisioned" or "deprovisioned"	"provisioned"
updated_at	date-time	when add-on was updated	"2012-01-01T12:00:00Z"
web_url	nullable uri	URL for logging into web interface of add-on (e.g. a dashboard)	"https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"

Add-on List

List all existing add-ons.

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

GET /addons

Curl Example

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

Response Example

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

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

Add-on Info

Info for an existing add-on.

GET /addons/{add_on_id_or_name}

Curl Example

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

Response Example

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

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

Add-on Create

Create a new add-on.

POST /apps/{app_id_or_name}/addons

Required Parameters

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
attachment:name	string	unique name for this add-on attachment to this app	"DATABASE"
config	object	custom add-on provisioning options	{"db-version":"1.2.3"}
confirm	string	name of billing entity for confirmation	"example"
name	string	globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$	"acme-inc-primary-database"

Curl Example

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

Response Example

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

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

Add-on Delete

Delete an existing add-on.

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

Curl Example

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

Response Example

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

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

Add-on Info By App

Info for an existing add-on.

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

Curl Example

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

Response Example

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

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

Add-on List By App

List existing add-ons for an app.

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

GET /apps/{app_id_or_name}/addons

Curl Example

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

Response Example

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

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

Add-on Update

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

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

Required Parameters

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
name	string	globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$	"acme-inc-primary-database"

Curl Example

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

Response Example

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

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

Add-on List By User

List all existing add-ons a user has access to

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

GET /users/{account_email_or_id_or_self}/addons

Curl Example

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

Response Example

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

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

Add-on List By Team

List add-ons used across all Team apps

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

GET /teams/{team_name_or_id}/addons

Curl Example

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

Response Example

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

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

Add-on Resolution

Resolve an add-on from a name, optionally passing an app name. If there are matches it returns at least one add-on (exact match) or many.

POST /actions/addons/resolve

Required Parameters

Name	Type	Description	Example
addon	string	globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$	"acme-inc-primary-database"

Optional Parameters

Name	Type	Description	Example
addon_service	string	unique name of this add-on-service	"heroku-postgresql"
app	string	unique name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"

Curl Example

$ curl -n -X POST https://api.heroku.com/actions/addons/resolve \
  -d '{
  "addon": "acme-inc-primary-database",
  "app": "example",
  "addon_service": "heroku-postgresql"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Add-on Action

Stability: development

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

Add-on Action Provision

Mark an add-on as provisioned for use.

POST /addons/{add_on_id_or_name}/actions/provision

Curl Example

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

Response Example

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

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

Add-on Action Deprovision

Mark an add-on as deprovisioned.

POST /addons/{add_on_id_or_name}/actions/deprovision

Curl Example

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

Response Example

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

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

Add-on Attachment

Stability: prototype

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

Attributes

Name	Type	Description	Example
addon:app:id	uuid	unique identifier of app	"01234567-89ab-cdef-0123-456789abcdef"
addon:app:name	string	unique name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
addon:id	uuid	unique identifier of add-on	"01234567-89ab-cdef-0123-456789abcdef"
addon:name	string	globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$	"acme-inc-primary-database"
app:id	uuid	unique identifier of app	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	unique name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
created_at	date-time	when add-on attachment was created	"2012-01-01T12:00:00Z"
id	uuid	unique identifier of this add-on attachment	"01234567-89ab-cdef-0123-456789abcdef"
log_input_url	nullable string	URL for add-on partners to write to an add-on’s logs	"https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
name	string	unique name for this add-on attachment to this app	"DATABASE"
namespace	nullable string	attachment namespace	"role:analytics"
updated_at	date-time	when add-on attachment was updated	"2012-01-01T12:00:00Z"
web_url	nullable uri	URL for logging into web interface of add-on in attached app context	"https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"

Add-on Attachment Create

Create a new add-on attachment.

POST /addon-attachments

Required Parameters

Name	Type	Description	Example
addon	string	unique identifier or globally name of the add-on	"01234567-89ab-cdef-0123-456789abcdef" or "acme-inc-primary-database"
app	string	unique identifier or name of app	"01234567-89ab-cdef-0123-456789abcdef" or "example"

Optional Parameters

Name	Type	Description	Example
confirm	string	name of owning app for confirmation	"example"
name	string	unique name for this add-on attachment to this app	"DATABASE"
namespace	nullable string	attachment namespace	"role:analytics"
namespace_config	nullable object	attachment namespace config, used to specify namespace via key-value pairs	{"cred":"analyst"}

Curl Example

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

Response Example

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

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "DATABASE",
  "namespace": "role:analytics",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
  "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}

Add-on Attachment Delete

Delete an existing add-on attachment.

DELETE /addon-attachments/{add_on_attachment_id}

Curl Example

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

Response Example

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

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "DATABASE",
  "namespace": "role:analytics",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
  "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}

Add-on Attachment Info

Info for existing add-on attachment.

GET /addon-attachments/{add_on_attachment_id}

Curl Example

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

Response Example

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

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "DATABASE",
  "namespace": "role:analytics",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
  "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}

Add-on Attachment List

List existing add-on attachments.

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

GET /addon-attachments

Curl Example

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

Response Example

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

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-inc-primary-database",
      "app": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      }
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "DATABASE",
    "namespace": "role:analytics",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
    "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
  }
]

Add-on Attachment List by Add-on

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

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

GET /addons/{add_on_id_or_name}/addon-attachments

Curl Example

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

Response Example

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

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-inc-primary-database",
      "app": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      }
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "DATABASE",
    "namespace": "role:analytics",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
    "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
  }
]

Add-on Attachment List by App

List existing add-on attachments for an app.

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

GET /apps/{app_id_or_name}/addon-attachments

Curl Example

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

Response Example

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

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-inc-primary-database",
      "app": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      }
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "DATABASE",
    "namespace": "role:analytics",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
    "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
  }
]

Add-on Attachment Info by App

Info for existing add-on attachment for an app.

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

Curl Example

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

Response Example

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

{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database",
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "DATABASE",
  "namespace": "role:analytics",
  "updated_at": "2012-01-01T12:00:00Z",
  "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
  "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}

Add-on Attachment Resolution

Resolve an add-on attachment from a name, optionally passing an app name. If there are matches it returns at least one add-on attachment (exact match) or many.

POST /actions/addon-attachments/resolve

Required Parameters

Name	Type	Description	Example
addon_attachment	string	unique name for this add-on attachment to this app	"DATABASE"

Optional Parameters

Name	Type	Description	Example
addon_service	string	unique name of this add-on-service	"heroku-postgresql"
app	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"

Curl Example

$ curl -n -X POST https://api.heroku.com/actions/addon-attachments/resolve \
  -d '{
  "addon_attachment": "DATABASE",
  "app": "example",
  "addon_service": "heroku-postgresql"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-inc-primary-database",
      "app": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      }
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "DATABASE",
    "namespace": "role:analytics",
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
    "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
  }
]

Add-on Config

Stability: development

Configuration of an Add-on

Attributes

Name	Type	Description	Example
name	string	unique name of the config	"FOO"
value	nullable string	value of the config	"bar"

Add-on Config List

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

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

GET /addons/{add_on_id_or_name}/config

Curl Example

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

Response Example

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

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

Add-on Config Update

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

PATCH /addons/{add_on_id_or_name}/config

Optional Parameters

Name	Type	Description	Example
config	array		[{"name":"FOO","value":"bar"}]

Curl Example

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

Response Example

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

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

Add-on Plan Action

Stability: development

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

Attributes

Name	Type	Description	Example
action	string	identifier of the action to take that is sent via SSO	"example"
id	uuid	a unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
label	string	the display text shown in Dashboard	"Example"
requires_owner	boolean	if the action requires the user to own the app	true
url	string	absolute URL to use instead of an action	"http://example.com?resource_id=:resource_id"

Add-on Region Capability

Stability: production

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

Attributes

Name	Type	Description	Example
addon_service:cli_plugin_name	nullable string	npm package name of the add-on service’s Heroku CLI plugin	"heroku-papertrail"
addon_service:created_at	date-time	when add-on-service was created	"2012-01-01T12:00:00Z"
addon_service:human_name	string	human-readable name of the add-on service provider	"Heroku Postgres"
addon_service:id	uuid	unique identifier of this add-on-service	"01234567-89ab-cdef-0123-456789abcdef"
addon_service:name	string	unique name of this add-on-service	"heroku-postgresql"
addon_service:state	string	release status for add-on service one of:"alpha" or "beta" or "ga" or "shutdown"	"ga"
addon_service:supported_generations/id	uuid	unique identifier of generation	"01234567-89ab-cdef-0123-456789abcdef"
addon_service:supported_generations/name	string	unique name of generation	"cedar"
addon_service:supports_multiple_installations	boolean	whether or not apps can have access to more than one instance of this add-on at the same time	false
addon_service:supports_sharing	boolean	whether or not apps can have access to add-ons billed to a different app	false
addon_service:updated_at	date-time	when add-on-service was updated	"2012-01-01T12:00:00Z"
id	uuid	unique identifier of this add-on-region-capability	"01234567-89ab-cdef-0123-456789abcdef"
region:country	string	country where the region exists	"United States"
region:created_at	date-time	when region was created	"2012-01-01T12:00:00Z"
region:description	string	description of region	"United States"
region:id	uuid	unique identifier of region	"01234567-89ab-cdef-0123-456789abcdef"
region:locale	string	area in the country where the region exists	"Virginia"
region:name	string	unique name of region	"us"
region:private_capable	boolean	whether or not region is available for creating a Private Space	false
region:provider:name	string	name of provider	"amazon-web-services"
region:provider:region	string	region name used by provider one of:"ap-south-1" or "eu-west-1" or "ap-southeast-1" or "ap-southeast-2" or "eu-central-1" or "eu-west-2" or "ap-northeast-2" or "ap-northeast-1" or "us-east-1" or "sa-east-1" or "us-west-1" or "us-west-2" or "ca-central-1"	"us-east-1"
region:updated_at	date-time	when region was updated	"2012-01-01T12:00:00Z"
supports_private_networking	boolean	whether the add-on can be installed to a Space	true

Add-on Region Capability List

List all existing add-on region capabilities.

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

GET /addon-region-capabilities

Curl Example

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

Response Example

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

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

Add-on Region Capability List by Add-on Service

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

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

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

Curl Example

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

Response Example

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

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

Add-on Region Capability List By Region

List existing add-on region capabilities for a region.

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

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

Curl Example

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

Response Example

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

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

Add-on Service

Stability: production

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

Attributes

Name	Type	Description	Example
cli_plugin_name	nullable string	npm package name of the add-on service’s Heroku CLI plugin	"heroku-papertrail"
created_at	date-time	when add-on-service was created	"2012-01-01T12:00:00Z"
human_name	string	human-readable name of the add-on service provider	"Heroku Postgres"
id	uuid	unique identifier of this add-on-service	"01234567-89ab-cdef-0123-456789abcdef"
name	string	unique name of this add-on-service	"heroku-postgresql"
state	string	release status for add-on service one of:"alpha" or "beta" or "ga" or "shutdown"	"ga"
supported_generations/id	uuid	unique identifier of generation	"01234567-89ab-cdef-0123-456789abcdef"
supported_generations/name	string	unique name of generation	"cedar"
supports_multiple_installations	boolean	whether or not apps can have access to more than one instance of this add-on at the same time	false
supports_sharing	boolean	whether or not apps can have access to add-ons billed to a different app	false
updated_at	date-time	when add-on-service was updated	"2012-01-01T12:00:00Z"

Add-on Service Info

Info for existing add-on-service.

GET /addon-services/{add_on_service_id_or_name}

Curl Example

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

Response Example

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

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

Add-on Service List

List existing add-on-services.

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

GET /addon-services

Curl Example

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

Response Example

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

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

Add-on Webhook

Stability: production

Represents the details of a webhook subscription

Attributes

Name	Type	Description	Example
created_at	date-time	when the webhook was created	"2015-01-01T12:00:00Z"
id	uuid	the webhook’s unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
include	array	the entities that the subscription provides notifications for	["api:release"]
level	string	if notify, Heroku makes a single, fire-and-forget delivery attempt. If sync, Heroku attempts multiple deliveries until the request is successful or a limit is reached one of:"notify" or "sync"	"notify"
updated_at	date-time	when the webhook was updated	"2015-01-01T12:00:00Z"
url	uri	the URL where the webhook’s notification requests are sent

Add-on Webhook Create

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

POST /addons/{add_on_id_or_name}/webhooks

Required Parameters

Name	Type	Description	Example
include	array	the entities that the subscription provides notifications for	["api:release"]
level	string	if notify, Heroku makes a single, fire-and-forget delivery attempt. If sync, Heroku attempts multiple deliveries until the request is successful or a limit is reached one of:"notify" or "sync"	"notify"
url	uri	the URL where the webhook’s notification requests are sent

Optional Parameters

Name	Type	Description	Example
authorization	nullable string	a custom Authorization header that Heroku will include with all webhook notifications	"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3"
secret	nullable string	a value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s Heroku-Webhook-Hmac-SHA256 header)	"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad"

Curl Example

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

Response Example

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

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

Add-on Webhook Delete

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

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

Curl Example

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

Response Example

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

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

Add-on Webhook Info

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

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

Curl Example

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

Response Example

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

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

Add-on Webhook List

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

GET /addons/{add_on_id_or_name}/webhooks

Curl Example

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

Response Example

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

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

Add-on Webhook Update

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

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

Optional Parameters

Name	Type	Description	Example
authorization	nullable string	a custom Authorization header that Heroku will include with all webhook notifications	"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3"
include	array	the entities that the subscription provides notifications for	["api:release"]
level	string	if notify, Heroku makes a single, fire-and-forget delivery attempt. If sync, Heroku attempts multiple deliveries until the request is successful or a limit is reached one of:"notify" or "sync"	"notify"
secret	nullable string	a value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s Heroku-Webhook-Hmac-SHA256 header)	"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad"
url	uri	the URL where the webhook’s notification requests are sent

Curl Example

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

Response Example

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

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

Add-on Webhook Delivery

Stability: production

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

Add-on Webhook Delivery Info

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

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

Curl Example

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

Response Example

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

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

Add-on Webhook Delivery List

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

GET /addons/{add_on_id_or_name}/webhook-deliveries

Curl Example

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

Response Example

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

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

Add-on Webhook Event

Stability: production

Represents a webhook event that occurred.

Add-on Webhook Event Info

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

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

Curl Example

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

Response Example

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

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

Add-on Webhook Event List

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

GET /addons/{add_on_id_or_name}/webhook-events

Curl Example

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

Response Example

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

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

Allowed Add-on Service

Stability: prototype

Entities that have been allowed to be used by a Team

Attributes

Name	Type	Description	Example
added_at	date-time	when the add-on service was allowed	"2012-01-01T12:00:00Z"
added_by:email	nullable email	unique email address of account	"username@example.com"
added_by:id	nullable uuid	unique identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
addon_service:human_name	string	human-readable name of the add-on service provider	"Heroku Postgres"
addon_service:id	uuid	unique identifier of this add-on-service	"01234567-89ab-cdef-0123-456789abcdef"
addon_service:name	string	unique name of this add-on-service	"heroku-postgresql"
id	uuid	unique identifier for this allowed add-on service record	"01234567-89ab-cdef-0123-456789abcdef"

Allowed Add-on Service List By Team

List all allowed add-on services for a team

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

GET /teams/{team_name_or_id}/allowed-addon-services

Curl Example

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

Response Example

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

[
  {
    "added_at": "2012-01-01T12:00:00Z",
    "added_by": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "addon_service": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql",
      "human_name": "Heroku Postgres"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
]

Allowed Add-on Service Create By Team

Allow an Add-on Service

POST /teams/{team_name_or_id}/allowed-addon-services

Optional Parameters

Name	Type	Description	Example
addon_service	string	name of the add-on service to allow	"heroku-postgresql"

Curl Example

$ curl -n -X POST https://api.heroku.com/teams/$TEAM_NAME_OR_ID/allowed-addon-services \
  -d '{
  "addon_service": "heroku-postgresql"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

[
  {
    "added_at": "2012-01-01T12:00:00Z",
    "added_by": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "addon_service": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-postgresql",
      "human_name": "Heroku Postgres"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
]

Allowed Add-on Service Delete By Team

Remove an allowed add-on service

DELETE /teams/{team_name_or_id}/allowed-addon-services/{allowed_add_on_service_id_or_name}

Curl Example

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

Response Example

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

{
  "added_at": "2012-01-01T12:00:00Z",
  "added_by": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "addon_service": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-postgresql",
    "human_name": "Heroku Postgres"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef"
}

App

Stability: production

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

Attributes

Name	Type	Description	Example
acm	boolean	ACM status of this app	false
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	"heroku-18"
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"
generation:id	uuid	unique identifier of the generation of the Heroku platform for this app	"01234567-89ab-cdef-0123-456789abcdef"
generation:name	string	unique name of the generation of the Heroku platform for this app	"cedar"
git_url	string	git repo URL of app pattern: ^https://git.heroku.com/[a-z][a-z0-9-]{2,29}.git$	"https://git.heroku.com/example.git"
id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
internal_routing	nullable boolean	describes whether a Private Spaces app is externally routable or not	false
maintenance	boolean	maintenance status of app	false
name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
organization	nullable object	identity of team	null
organization:id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
organization:name	string	unique name of team	"example"
owner:email	email	unique email address of account	"username@example.com"
owner:id	uuid	unique identifier of an account	"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
space	nullable object	identity of space	null
space:id	uuid	unique identifier of space	"01234567-89ab-cdef-0123-456789abcdef"
space:name	string	unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$	"nasa"
space:shield	boolean	true if this space has shield enabled	true
stack:id	uuid	unique identifier of stack	"01234567-89ab-cdef-0123-456789abcdef"
stack:name	string	unique name of stack	"heroku-18"
team	nullable object	identity of team	null
team:id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
team:name	string	unique name of team	"example"
updated_at	date-time	when app was updated	"2012-01-01T12:00:00Z"
web_url	nullable uri	web URL of app pattern: ^https?://[a-z][a-z0-9-]{3,43}.herokuapp.com/$	"https://example.herokuapp.com/"

App Create

Create a new app.

POST /apps

Optional Parameters

Name	Type	Description	Example
feature_flags	array	unique name of app feature	["name"]
name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
region	string	unique identifier or name of region	"01234567-89ab-cdef-0123-456789abcdef" or "us"
stack	string	unique name or identifier of stack	"heroku-18" or "01234567-89ab-cdef-0123-456789abcdef"

Curl Example

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

Response Example

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

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

App Delete

Delete an existing app.

DELETE /apps/{app_id_or_name}

Curl Example

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

Response Example

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

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

App Info

Info for existing app.

GET /apps/{app_id_or_name}

Curl Example

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

Response Example

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

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

App List

List existing apps.

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

GET /apps

Curl Example

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

Response Example

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

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

App List Owned and Collaborated

List owned and collaborated apps (excludes team apps).

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

GET /users/{account_email_or_id_or_self}/apps

Curl Example

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

Response Example

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

[
  {
    "acm": false,
    "archived_at": "2012-01-01T12:00:00Z",
    "buildpack_provided_description": "Ruby/Rack",
    "build_stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-18"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "generation": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    },
    "git_url": "https://git.heroku.com/example.git",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "internal_routing": false,
    "maintenance": false,
    "name": "example",
    "owner": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "organization": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "region": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "us"
    },
    "released_at": "2012-01-01T12:00:00Z",
    "repo_size": 0,
    "slug_size": 0,
    "space": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "nasa",
      "shield": true
    },
    "stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-18"
    },
    "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 name or identifier of stack	"heroku-18" or "01234567-89ab-cdef-0123-456789abcdef"
maintenance	boolean	maintenance status of app	false
name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"

Curl Example

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

Response Example

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

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

App Enable ACM

Enable ACM flag for an app

POST /apps/{app_id_or_name}/acm

Curl Example

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

Response Example

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

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

App Disable ACM

Disable ACM flag for an app

DELETE /apps/{app_id_or_name}/acm

Curl Example

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

Response Example

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

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

App Refresh ACM

Refresh ACM for an app

PATCH /apps/{app_id_or_name}/acm

Curl Example

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

Response Example

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

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

App Feature

Stability: production

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

Attributes

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."
display_name	string	user readable feature name	"My Feature"
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
feedback_email	string	e-mail to send feedback about the feature	"feedback@heroku.com"
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 https://api.heroku.com/apps/$APP_ID_OR_NAME/features/$APP_FEATURE_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

App Feature List

List existing app features.

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

GET /apps/{app_id_or_name}/features

Curl Example

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

Response Example

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

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

App Feature Update

Update an existing app feature.

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

Required Parameters

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

Response Example

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

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

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	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
build	nullable object	identity and status of build	null
build:id	uuid	unique identifier of build	"01234567-89ab-cdef-0123-456789abcdef"
build:output_stream_url	string	Build process output will be available from this URL as a stream. The stream is available as either text/plain or text/event-stream. Clients should be prepared to handle disconnects and can resume the stream by sending a Range header (for text/plain) or a Last-Event-Id header (for text/event-stream).	"https://build-output.heroku.com/streams/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"	"failed"
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:checksum	nullable string	an optional checksum of the gzipped tarball for verifying its integrity	"SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
source_blob:url	string	URL of gzipped tarball of source code containing app.json manifest file	"https://example.com/source.tgz?token=xyz"
source_blob:version	nullable string	Version of the gzipped tarball.	"v1.3.0"

Optional Parameters

Name	Type	Description	Example
app:locked	boolean	are other team members forbidden from joining this app.	false
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
app:organization	string	unique name of team	"example"
app:personal	boolean	force creation of the app in the user account even if a default team is set.	false
app:region	string	name of region	"us"
app:space	string	unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$	"nasa"
app:stack	string	unique name	"heroku-18"
overrides:buildpacks	array	overrides the buildpacks specified in the app.json manifest file	[{"url":"https://example.com/buildpack.tgz"}]
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 \
  -d '{
  "app": {
    "locked": false,
    "name": "example",
    "organization": "example",
    "personal": false,
    "region": "us",
    "space": "nasa",
    "stack": "heroku-18"
  },
  "source_blob": {
    "checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "url": "https://example.com/source.tgz?token=xyz",
    "version": "v1.3.0"
  },
  "overrides": {
    "buildpacks": [
      {
        "url": "https://example.com/buildpack.tgz"
      }
    ],
    "env": {
      "FOO": "bar",
      "BAZ": "qux"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

App Setup Info

Get the status of an app setup.

GET /app-setups/{app_setup_id}

Curl Example

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

Response Example

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

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

App Transfer

Stability: production

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

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"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 email address, identifier of an account or Implicit reference to currently authorized user	"username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" or "~"

Optional Parameters

Name	Type	Description	Example
silent	boolean	whether to suppress email notification when transferring apps	false

Curl Example

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

Response Example

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

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

App Transfer Delete

Delete an existing app transfer

DELETE /account/app-transfers/{app_transfer_id_or_name}

Curl Example

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

Response Example

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

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

App Transfer Info

Info for existing app transfer.

GET /account/app-transfers/{app_transfer_id_or_name}

Curl Example

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

Response Example

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

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

App Transfer List

List existing apps transfers.

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

GET /account/app-transfers

Curl Example

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

Response Example

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

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

App Transfer Update

Update an existing app transfer.

PATCH /account/app-transfers/{app_transfer_id_or_name}

Required Parameters

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

Response Example

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

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

App Webhook

Stability: production

Represents the details of a webhook subscription

App Webhook Create

Create an app webhook subscription.

POST /apps/{app_id_or_name}/webhooks

Required Parameters

Name	Type	Description	Example
include	array	the entities that the subscription provides notifications for	["api:release"]
level	string	if notify, Heroku makes a single, fire-and-forget delivery attempt. If sync, Heroku attempts multiple deliveries until the request is successful or a limit is reached one of:"notify" or "sync"	"notify"
url	uri	the URL where the webhook’s notification requests are sent

Optional Parameters

Name	Type	Description	Example
authorization	nullable string	a custom Authorization header that Heroku will include with all webhook notifications	"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3"
secret	nullable string	a value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s Heroku-Webhook-Hmac-SHA256 header)	"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad"

Curl Example

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

Response Example

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

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

App Webhook Delete

Removes an app webhook subscription.

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

Curl Example

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

Response Example

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

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

App Webhook Info

Returns the info for an app webhook subscription.

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

Curl Example

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

Response Example

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

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

App Webhook List

List all webhook subscriptions for a particular app.

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

GET /apps/{app_id_or_name}/webhooks

Curl Example

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

Response Example

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

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

App Webhook Update

Updates the details of an app webhook subscription.

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

Optional Parameters

Name	Type	Description	Example
authorization	nullable string	a custom Authorization header that Heroku will include with all webhook notifications	"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3"
include	array	the entities that the subscription provides notifications for	["api:release"]
level	string	if notify, Heroku makes a single, fire-and-forget delivery attempt. If sync, Heroku attempts multiple deliveries until the request is successful or a limit is reached one of:"notify" or "sync"	"notify"
secret	nullable string	a value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s Heroku-Webhook-Hmac-SHA256 header)	"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad"
url	uri	the URL where the webhook’s notification requests are sent

Curl Example

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

Response Example

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

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

App Webhook Delivery

Stability: production

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

Attributes

Name	Type	Description	Example
created_at	date-time	when the delivery was created	"2015-01-01T12:00:00Z"
event:id	uuid	the event’s unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
event:include	string	the type of entity that the event is related to	"api:release"
id	uuid	the delivery’s unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
last_attempt	nullable object	last attempt of a delivery	null
last_attempt:code	nullable integer	http response code received during attempt	null
last_attempt:created_at	date-time	when attempt was created	"2015-01-01T12:00:00Z"
last_attempt:error_class	nullable string	error class encountered during attempt	null
last_attempt:id	uuid	unique identifier of attempt	"01234567-89ab-cdef-0123-456789abcdef"
last_attempt:status	string	status of an attempt one of:"scheduled" or "succeeded" or "failed"	"scheduled"
last_attempt:updated_at	date-time	when attempt was updated	"2015-01-01T12:00:00Z"
next_attempt_at	nullable date-time	when delivery will be attempted again	null
num_attempts	integer	number of times a delivery has been attempted	42
status	string	the delivery’s status one of:"pending" or "scheduled" or "retrying" or "failed" or "succeeded"	"pending"
updated_at	date-time	when the delivery was last updated	"2015-01-01T12:00:00Z"
webhook:id	uuid	the webhook’s unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
webhook:level	string	if notify, Heroku makes a single, fire-and-forget delivery attempt. If sync, Heroku attempts multiple deliveries until the request is successful or a limit is reached one of:"notify" or "sync"	"notify"

App Webhook Delivery Info

Returns the info for an existing delivery.

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

Curl Example

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

Response Example

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

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

App Webhook Delivery List

Lists existing deliveries for an app.

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

GET /apps/{app_id_or_name}/webhook-deliveries

Curl Example

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

Response Example

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

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

App Webhook Event

Stability: production

Represents a webhook event that occurred.

Attributes

Name	Type	Description	Example
created_at	date-time	when event was created	"2015-01-01T12:00:00Z"
id	uuid	the event’s unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
include	string	the type of entity that the event is related to	"api:release"
payload:action	string	the type of event that occurred	"create"
payload:actor:email	email	unique email address	"username@example.com"
payload:actor:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
payload:data	object	the current details of the event
payload:previous_data	object	previous details of the event (if any)
payload:resource	string	the type of resource associated with the event	"release"
payload:version	string	the version of the details provided for the event	"1"
updated_at	date-time	when the event was last updated	"2015-01-01T12:00:00Z"

App Webhook Event Info

Returns the info for a specified webhook event.

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

Curl Example

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

Response Example

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

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

App Webhook Event List

Lists existing webhook events for an app.

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

GET /apps/{app_id_or_name}/webhook-events

Curl Example

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

Response Example

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

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

Audit Trail Archive

Stability: production

An audit trail archive represents a monthly json zipped file containing events

Attributes

Name	Type	Description	Example
checksum	string	checksum for the archive	"example"
created_at	date-time	when archive was created	"2015-01-01T12:00:00Z"
month	string	month of the archive one of:"01" or "02" or "03" or "04" or "05" or "06" or "07" or "08" or "09" or "10" or "11" or "12"	"10"
size	integer	size of the archive in bytes	100
url	string	url where to download the archive	"example"
year	integer	year of the archive Range: 2017 <= value	2019

Audit Trail Archive Info

Get archive for a single month.

GET /enterprise-accounts/{enterprise_account_id_or_name}/archives/{archive_year}/{archive_month}

Curl Example

$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/archives/$ARCHIVE_YEAR/$ARCHIVE_MONTH \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "created_at": "2015-01-01T12:00:00Z",
  "month": "10",
  "year": 2019,
  "url": "example",
  "checksum": "example",
  "size": 100
}

Audit Trail Archive List

List existing archives.

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

GET /enterprise-accounts/{enterprise_account_id_or_name}/archives

Curl Example

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

Response Example

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

[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "month": "10",
    "year": 2019,
    "url": "example",
    "checksum": "example",
    "size": 100
  }
]

Audit Trail Event

Stability: production

An audit trail event represents some action on the platform

Attributes

Name	Type	Description	Example
action	string	action for the event	"example"
actor:email	email		"username@example.com"
actor:id	uuid		"01234567-89ab-cdef-0123-456789abcdef"
app:id	uuid		"01234567-89ab-cdef-0123-456789abcdef"
app:name	string		"example"
created_at	date-time	when event was created	"2015-01-01T12:00:00Z"
data	object	data specific to the event
enterprise_account:id	uuid		"01234567-89ab-cdef-0123-456789abcdef"
enterprise_account:name	string		"example"
id	uuid	unique identifier of event	"01234567-89ab-cdef-0123-456789abcdef"
owner:email	email		"username@example.com"
owner:id	uuid		"01234567-89ab-cdef-0123-456789abcdef"
request:ip_address	ipv4		"192.0.2.1"
team:id	uuid		"01234567-89ab-cdef-0123-456789abcdef"
team:name	string		"example"
type	string	type of event	"example"

Audit Trail Event List

List existing events. Returns all events for one day, defaulting to current day. Order, actor, action, and type, and day query params can be specified as query parameters. For example, ‘/enterprise-accounts/:id/events?order=desc&actor=user@example.com&action=create&type=app&day=2020-09-30’ would return events in descending order and only return app created events by the user with user@example.com email address.

GET /enterprise-accounts/{enterprise_account_id_or_name}/events

Curl Example

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

Response Example

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

[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "example",
    "action": "example",
    "actor": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com"
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com"
    },
    "enterprise_account": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "request": {
      "ip_address": "192.0.2.1"
    },
    "data": null
  }
]

Build

Stability: production

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

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
buildpacks	nullable array	buildpacks executed for this build, in order (only applicable to Cedar-generation apps)	null
buildpacks/name	string	Buildpack Registry name of the buildpack for the app	"heroku/ruby"
buildpacks/url	string	the URL of the buildpack for the app	"https://github.com/heroku/heroku-buildpack-ruby"
created_at	date-time	when build was created	"2012-01-01T12:00:00Z"
generation	string	generation of build	"cedar"
id	uuid	unique identifier of build	"01234567-89ab-cdef-0123-456789abcdef"
output_stream_url	string	Build process output will be available from this URL as a stream. The stream is available as either text/plain or text/event-stream. Clients should be prepared to handle disconnects and can resume the stream by sending a Range header (for text/plain) or a Last-Event-Id header (for text/event-stream).	"https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
release	nullable object	release resulting from the build	{"id":"01234567-89ab-cdef-0123-456789abcdef"}
release:id	uuid	unique identifier of release	"01234567-89ab-cdef-0123-456789abcdef"
slug	nullable object	slug created by this build (only applicable for Cedar-generation apps)	null
slug:id	uuid	unique identifier of slug	"01234567-89ab-cdef-0123-456789abcdef"
source_blob:checksum	nullable string	an optional checksum of the gzipped tarball for verifying its integrity	"SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
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"
source_blob:version_description	nullable string	Version description of the gzipped tarball.	"* Fake User: Change session key"
stack	string	stack of build	"heroku-22"
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	unique email address	"username@example.com"
user:id	uuid	identifier of an account	"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:checksum	nullable string	an optional checksum of the gzipped tarball for verifying its integrity	"SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
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"
source_blob:version_description	nullable string	Version description of the gzipped tarball.	"* Fake User: Change session key"

Optional Parameters

Name	Type	Description	Example
buildpacks	nullable array	buildpacks executed for this build, in order (only applicable to Cedar-generation apps)	null
buildpacks/name	string	Buildpack Registry name of the buildpack for the app	"heroku/ruby"
buildpacks/url	string	the URL of the buildpack for the app	"https://github.com/heroku/heroku-buildpack-ruby"

Curl Example

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

Response Example

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

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

Build Info

Info for existing build.

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

Curl Example

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

Response Example

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

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

Build List

List existing build.

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

GET /apps/{app_id_or_name}/builds

Curl Example

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

Response Example

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

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

Build Delete cache

Destroy a build cache.

DELETE /apps/{app_id_or_name}/build-cache

Curl Example

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

Response Example

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

Build Cancel

Cancel running build.

DELETE /apps/{app_id_or_name}/builds/{build_id}

Curl Example

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

Response Example

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

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

Buildpack Installations

Stability: production

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

Attributes

Name	Type	Description	Example
buildpack:name	string	either the Buildpack Registry name or a URL of the buildpack for the app	"heroku/ruby"
buildpack:url	string	location of the buildpack for the app. Either a url (unofficial buildpacks) or an internal urn (heroku official buildpacks).	"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	The buildpack attribute can accept a name, a url, or a urn.	[{"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 \
  -d '{
  "updates": [
    {
      "buildpack": "https://github.com/heroku/heroku-buildpack-ruby"
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Buildpack Installations List

List an app’s existing buildpack installations.

GET /apps/{app_id_or_name}/buildpack-installations

Curl Example

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

Response Example

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

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

Collaborator

Stability: production

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

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"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"
permissions	array		[{"name":"view","description":"Can manage config, deploy, run commands and restart the app."}]
role	nullable string	role in the team one of:"admin" or "collaborator" or "member" or "owner" or null	"admin"
updated_at	date-time	when collaborator was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:federated	boolean	whether the user is federated and belongs to an Identity Provider	false
user:id	uuid	identifier of an account	"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 email address, identifier of an account or Implicit reference to currently authorized user	"username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" or "~"

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 \
  -d '{
  "silent": false,
  "user": "01234567-89ab-cdef-0123-456789abcdef"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Collaborator Delete

Delete an existing collaborator.

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

Curl Example

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

Response Example

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

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

Collaborator Info

Info for existing collaborator.

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

Curl Example

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

Response Example

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

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

Collaborator List

List existing collaborators.

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

GET /apps/{app_id_or_name}/collaborators

Curl Example

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

Response Example

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

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

Config Vars

Stability: production

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

Config Vars Info for App

Get config-vars for app.

GET /apps/{app_id_or_name}/config-vars

Curl Example

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

Response Example

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

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

Config Vars Info for App Release

Get config-vars for a release.

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

Curl Example

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

Response Example

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

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

Config Vars Update

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

PATCH /apps/{app_id_or_name}/config-vars

Curl Example

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

Response Example

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

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

Credit

Stability: development

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

Attributes

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 \
  -d '{
  "code1": "012abc",
  "code2": "012abc"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Credit Info

Info for existing credit.

GET /account/credits/{credit_id}

Curl Example

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

Response Example

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

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

Credit List

List existing credits.

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

GET /account/credits

Curl Example

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

Response Example

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

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

Domain

Stability: production

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

Attributes

Name	Type	Description	Example
acm_status	nullable string	status of this record’s ACM	"pending"
acm_status_reason	nullable string	reason for the status of this record’s ACM	"Failing CCA check"
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
cname	nullable string	canonical name record, the address to point a domain at	"example.herokudns.com"
created_at	date-time	when domain was created	"2012-01-01T12:00:00Z"
hostname	uri	full hostname	"subdomain.example.com"
id	uuid	unique identifier of this domain	"01234567-89ab-cdef-0123-456789abcdef"
kind	string	type of domain name one of:"heroku" or "custom"	"custom"
sni_endpoint	nullable object	sni endpoint the domain is associated with	null
sni_endpoint:id	uuid	unique identifier of this SNI endpoint	"01234567-89ab-cdef-0123-456789abcdef"
sni_endpoint:name	string	unique name for SNI endpoint pattern: ^[a-z][a-z0-9-]{2,29}$	"example"
status	string	status of this record’s cname	"pending"
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	uri	full hostname	"subdomain.example.com"
sni_endpoint	nullable string	null or unique identifier or name for SNI endpoint	null

Curl Example

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

Response Example

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

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

Domain Update

Associate an SNI endpoint

PATCH /apps/{app_id_or_name}/domains/{domain_id_or_hostname}

Required Parameters

Name	Type	Description	Example
sni_endpoint	nullable string	null or unique identifier or name for SNI endpoint	null

Curl Example

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

Response Example

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

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

Domain Delete

Delete an existing domain

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

Curl Example

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

Response Example

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

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

Domain Info

Info for existing domain.

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

Curl Example

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

Response Example

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

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

Domain List

List existing domains.

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

GET /apps/{app_id_or_name}/domains

Curl Example

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

Response Example

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

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

Dyno

Stability: production

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

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"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	"standard-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"}
force_no_tty	nullable boolean	force an attached one-off dyno to not run in a tty	null
size	string	dyno size	"standard-1X"
time_to_live	integer	seconds until dyno expires, after which it will soon be killed, max 86400 seconds (24 hours)	1800
type	string	type of process	"run"

Curl Example

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

Response Example

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

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

Dyno Restart

Restart dyno.

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

Curl Example

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

Response Example

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

Dyno Restart formation

Restart dynos of a given formation type.

DELETE /apps/{app_id_or_name}/formations/{dyno_formation_type}

Curl Example

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

Response Example

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

Dyno Restart all

Restart all dynos.

DELETE /apps/{app_id_or_name}/dynos

Curl Example

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

Response Example

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

Dyno Stop

Stop dyno.

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

Curl Example

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

Response Example

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

Dyno Stop formation

Stop dynos of a given formation type.

POST /apps/{app_id_or_name}/formations/{dyno_formation_type}/actions/stop

Curl Example

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

Response Example

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

Dyno Info

Info for existing dyno.

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

Curl Example

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

Response Example

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

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

Dyno List

List existing dynos.

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

GET /apps/{app_id_or_name}/dynos

Curl Example

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

Response Example

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

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

Dyno Size

Stability: prototype

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

Attributes

Name	Type	Description	Example
architecture	string	CPU architecture of this dyno size	"amd64"
compute	integer	minimum vCPUs, non-dedicated may get more depending on load	1
cost	nullable object	price information for this dyno size	null
dedicated	boolean	whether this dyno will be dedicated to one user	false
generation:id	uuid	unique identifier of the generation of the Heroku platform for this dyno size	"01234567-89ab-cdef-0123-456789abcdef"
generation:name	string	unique name of the generation of the Heroku platform for this dyno size	"cedar"
id	uuid	unique identifier of the dyno size	"01234567-89ab-cdef-0123-456789abcdef"
memory	number	amount of RAM in GB	0.5
name	string	name of the dyno size	"eco"
precise_dyno_units	number	unit of consumption for Heroku Enterprise customers to 2 decimal places	0.28
private_space_only	boolean	whether this dyno can only be provisioned in a private space	false

Dyno Size Info

Info for existing dyno size.

GET /dyno-sizes/{dyno_size_id_or_name}

Curl Example

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

Response Example

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

{
  "architecture": "amd64",
  "compute": 1,
  "cost": null,
  "dedicated": false,
  "precise_dyno_units": 0.28,
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "memory": 0.5,
  "name": "eco",
  "private_space_only": false
}

Dyno Size List

List existing dyno sizes.

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

GET /dyno-sizes

Curl Example

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

Response Example

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

[
  {
    "architecture": "amd64",
    "compute": 1,
    "cost": null,
    "dedicated": false,
    "precise_dyno_units": 0.28,
    "generation": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "memory": 0.5,
    "name": "eco",
    "private_space_only": false
  }
]

Dyno Size List App Dyno Sizes

List available dyno sizes for an app

GET /apps/{app_id_or_name}/available-dyno-sizes

Curl Example

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

Response Example

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

[
  {
    "architecture": "amd64",
    "compute": 1,
    "cost": null,
    "dedicated": false,
    "precise_dyno_units": 0.28,
    "generation": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "memory": 0.5,
    "name": "eco",
    "private_space_only": false
  }
]

Enterprise Account

Stability: development

Enterprise accounts allow companies to manage their development teams and billing.

Attributes

Name	Type	Description	Example
created_at	date-time	when the enterprise account was created	"2012-01-01T12:00:00Z"
id	uuid	unique identifier of the enterprise account	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider	nullable object	Identity Provider associated with the Enterprise Account	null
identity_provider:id	uuid	unique identifier of this identity provider	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:name	string	user-friendly unique identifier for this identity provider	"acme-sso"
identity_provider:owner:id	uuid	unique identifier of the owner	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:owner:name	string	name of the owner	"acme"
identity_provider:owner:type	string	type of the owner one of:"team" or "enterprise-account"	"team"
name	string	unique name of the enterprise account	"example"
partner_benefits	boolean	whether the enterprise account is part of the Salesforce Partner Program	false
permissions	array	the current user’s permissions for this enterprise account	["view"]
trial	boolean	whether the enterprise account is a trial or not	false
updated_at	date-time	when the enterprise account was updated	"2012-01-01T12:00:00Z"

Enterprise Account List

List enterprise accounts in which you are a member.

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

GET /enterprise-accounts

Curl Example

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

Response Example

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

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "created_at": "2012-01-01T12:00:00Z",
    "name": "example",
    "updated_at": "2012-01-01T12:00:00Z",
    "permissions": [
      "view"
    ],
    "trial": false,
    "partner_benefits": false,
    "identity_provider": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-sso",
      "owner": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme",
        "type": "team"
      }
    }
  }
]

Enterprise Account Info

Information about an enterprise account.

GET /enterprise-accounts/{enterprise_account_id_or_name}

Curl Example

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

Response Example

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

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z",
  "permissions": [
    "view"
  ],
  "trial": false,
  "partner_benefits": false,
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-sso",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  }
}

Enterprise Account Update

Update enterprise account properties

PATCH /enterprise-accounts/{enterprise_account_id_or_name}

Optional Parameters

Name	Type	Description	Example
name	string	unique name of the enterprise account	"example"

Curl Example

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

Response Example

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

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z",
  "permissions": [
    "view"
  ],
  "trial": false,
  "partner_benefits": false,
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-sso",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  }
}

Enterprise Account Daily Usage

Stability: development

Usage for an enterprise account at a daily resolution.

Attributes

Name	Type	Description	Example
addons	number	total add-on credits used	250.0
data	number	total add-on credits used for first party add-ons	34.89
date	date	date of the usage	"2019-01-01"
dynos	number	dynos used	1.548
id	uuid	enterprise account identifier	"01234567-89ab-cdef-0123-456789abcdef"
name	string	name of the enterprise account	"example-co"
partner	number	total add-on credits used for third party add-ons	12.34
space	number	space credits used	1.548
teams/addons	number	total add-on credits used	250.0
teams/apps	array	app usage in the team	[{"addons":250.0,"app_name":"example","data":34.89,"dynos":1.548,"partner":12.34}]
teams/data	number	total add-on credits used for first party add-ons	34.89
teams/dynos	number	dynos used	1.548
teams/id	uuid	team identifier	"01234567-89ab-cdef-0123-456789abcdef"
teams/name	string	name of the team	"ops"
teams/partner	number	total add-on credits used for third party add-ons	12.34
teams/space	number	space credits used	1.548

Enterprise Account Daily Usage Info

Retrieves usage for an enterprise account for a range of days. Start and end dates can be specified as query parameters using the date format YYYY-MM-DD. The enterprise account identifier can be found from the enterprise account list.

GET /enterprise-accounts/{enterprise_account_id}/usage/daily

Required Parameters

Name	Type	Description	Example
start	string	range start date pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$	"2019-01-25"

Optional Parameters

Name	Type	Description	Example
end	string	range end date pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$	"2019-02-25"

Curl Example

$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID/usage/daily \
 -G \
  -d start=2019-01-25 \
  -d end=2019-02-25 \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

[
  {
    "addons": 250.0,
    "teams": [
      {
        "addons": 250.0,
        "apps": [
          {
            "addons": 250.0,
            "app_name": "example",
            "data": 34.89,
            "dynos": 1.548,
            "partner": 12.34
          }
        ],
        "data": 34.89,
        "dynos": 1.548,
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "ops",
        "partner": 12.34,
        "space": 1.548
      }
    ],
    "data": 34.89,
    "date": "2019-01-01",
    "dynos": 1.548,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example-co",
    "partner": 12.34,
    "space": 1.548
  }
]

Enterprise Account Member

Stability: development

Enterprise account members are users with access to an enterprise account.

Attributes

Name	Type	Description	Example
enterprise_account:id	uuid	unique identifier of the enterprise account	"01234567-89ab-cdef-0123-456789abcdef"
enterprise_account:name	string	unique name of the enterprise account	"example"
id	uuid	unique identifier of the member	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider	nullable object	Identity Provider information the member is federated with	null
identity_provider:id	uuid	unique identifier of this identity provider	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:name	string	name of the identity provider	"acme"
identity_provider:owner:id	uuid	unique identifier of the owner	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:owner:name	string	name of the owner	"acme"
identity_provider:owner:type	string	type of the owner one of:"team" or "enterprise-account"	"team"
identity_provider:redacted	boolean	whether the identity_provider information is redacted or not	false
permissions/description	string		"View enterprise account members and teams."
permissions/name	string	permission in the enterprise account one of:"view" or "create" or "manage" or "billing"	"view"
two_factor_authentication	boolean	whether the Enterprise Account member has two factor authentication enabled	true
user:email	email	unique email address	"username@example.com"
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"

Enterprise Account Member List

List members in an enterprise account.

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

GET /enterprise-accounts/{enterprise_account_id_or_name}/members

Curl Example

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

Response Example

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

[
  {
    "enterprise_account": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "permissions": [
      {
        "description": "View enterprise account members and teams.",
        "name": "view"
      }
    ],
    "user": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "two_factor_authentication": true,
    "identity_provider": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "redacted": false,
      "owner": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme",
        "type": "team"
      }
    }
  }
]

Enterprise Account Member Create

Create a member in an enterprise account.

POST /enterprise-accounts/{enterprise_account_id_or_name}/members

Required Parameters

Name	Type	Description	Example
permissions	array	permissions for enterprise account	["view"]
user	string	unique email address or identifier of an account	"username@example.com" or "01234567-89ab-cdef-0123-456789abcdef"

Optional Parameters

Name	Type	Description	Example
federated	boolean	whether membership is being created as part of SSO JIT	false

Curl Example

$ curl -n -X POST https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/members \
  -d '{
  "user": "01234567-89ab-cdef-0123-456789abcdef",
  "permissions": [
    "view"
  ],
  "federated": false
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "enterprise_account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "permissions": [
    {
      "description": "View enterprise account members and teams.",
      "name": "view"
    }
  ],
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "two_factor_authentication": true,
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "redacted": false,
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  }
}

Enterprise Account Member Update

Update a member in an enterprise account.

PATCH /enterprise-accounts/{enterprise_account_id_or_name}/members/{enterprise_account_member_email_or_id}

Required Parameters

Name	Type	Description	Example
permissions	array	permissions for enterprise account	["view"]

Curl Example

$ curl -n -X PATCH https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/members/$ENTERPRISE_ACCOUNT_MEMBER_EMAIL_OR_ID \
  -d '{
  "permissions": [
    "view"
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "enterprise_account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "permissions": [
    {
      "description": "View enterprise account members and teams.",
      "name": "view"
    }
  ],
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "two_factor_authentication": true,
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "redacted": false,
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  }
}

Enterprise Account Member Delete

delete a member in an enterprise account.

DELETE /enterprise-accounts/{enterprise_account_id_or_name}/members/{enterprise_account_member_email_or_id}

Curl Example

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

Response Example

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

{
  "enterprise_account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "permissions": [
    {
      "description": "View enterprise account members and teams.",
      "name": "view"
    }
  ],
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "two_factor_authentication": true,
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "redacted": false,
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  }
}

Enterprise Account Monthly Usage

Stability: development

Usage for an enterprise account at a monthly resolution.

Attributes

Name	Type	Description	Example
addons	number	total add-on credits used	250.0
connect	number	max connect rows synced	15000
data	number	total add-on credits used for first party add-ons	34.89
dynos	number	dynos used	1.548
id	uuid	enterprise account identifier	"01234567-89ab-cdef-0123-456789abcdef"
month	string	year and month of the usage pattern: ^[0-9]{4}-[0-9]{2}$	"2019-01"
name	string	name of the enterprise account	"example-co"
partner	number	total add-on credits used for third party add-ons	12.34
space	number	space credits used	1.548
teams/addons	number	total add-on credits used	250.0
teams/apps	array	app usage in the team	[{"addons":250.0,"app_name":"example","data":34.89,"dynos":1.548,"partner":12.34}]
teams/connect	number	max connect rows synced	15000
teams/data	number	total add-on credits used for first party add-ons	34.89
teams/dynos	number	dynos used	1.548
teams/id	uuid	team identifier	"01234567-89ab-cdef-0123-456789abcdef"
teams/name	string	name of the team	"ops"
teams/partner	number	total add-on credits used for third party add-ons	12.34
teams/space	number	space credits used	1.548

Enterprise Account Monthly Usage Info

Retrieves usage for an enterprise account for a range of months. Start and end dates can be specified as query parameters using the date format YYYY-MM. If no end date is specified, one month of usage is returned. The enterprise account identifier can be found from the enterprise account list.

GET /enterprise-accounts/{enterprise_account_id}/usage/monthly

Required Parameters

Name	Type	Description	Example
start	string	range start date pattern: ^[0-9]{4}-[0-9]{2}$	"2019-01"

Optional Parameters

Name	Type	Description	Example
end	string	range end date pattern: ^[0-9]{4}-[0-9]{2}$	"2019-02"

Curl Example

$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID/usage/monthly \
 -G \
  -d start=2019-01 \
  -d end=2019-02 \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

[
  {
    "addons": 250.0,
    "teams": [
      {
        "addons": 250.0,
        "apps": [
          {
            "addons": 250.0,
            "app_name": "example",
            "data": 34.89,
            "dynos": 1.548,
            "partner": 12.34
          }
        ],
        "connect": 15000,
        "data": 34.89,
        "dynos": 1.548,
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "ops",
        "partner": 12.34,
        "space": 1.548
      }
    ],
    "connect": 15000,
    "data": 34.89,
    "dynos": 1.548,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "month": "2019-01",
    "name": "example-co",
    "partner": 12.34,
    "space": 1.548
  }
]

Filters

Stability: development

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

Filters Apps

Request an apps list filtered by app id.

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

POST /filters/apps

Curl Example

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

Response Example

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

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

Formation

Stability: production

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

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"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"
dyno_size:id	uuid	unique identifier of the dyno size	"01234567-89ab-cdef-0123-456789abcdef"
dyno_size:name	string	name of the dyno size	"eco"
id	uuid	unique identifier of this process type	"01234567-89ab-cdef-0123-456789abcdef"
quantity	integer	number of processes to maintain	1
size	string	deprecated, refer to ‘dyno_size’ instead	"standard-1X"
type	string	type of process to maintain pattern: ^[-\w]{1,128}$	"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 https://api.heroku.com/apps/$APP_ID_OR_NAME/formation/$FORMATION_ID_OR_TYPE \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Formation List

List process type formation

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

GET /apps/{app_id_or_name}/formation

Curl Example

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

Response Example

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

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

Formation Batch Update

Batch update process types

PATCH /apps/{app_id_or_name}/formation

Required Parameters

Name	Type	Description	Example
updates	array	Array with formation updates. Each element must have “type”, the id or name of the process type to be updated, and can optionally update its “quantity” or “dyno_size”.	[{"dyno_size":{"id":"01234567-89ab-cdef-0123-456789abcdef"},"quantity":1,"type":"web"}]

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/formation \
  -d '{
  "updates": [
    {
      "dyno_size": {
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      },
      "quantity": 1,
      "type": "web"
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Formation Update

Update process type

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

Optional Parameters

Name	Type	Description	Example
dyno_size:id	uuid	unique identifier of the dyno size	"01234567-89ab-cdef-0123-456789abcdef"
dyno_size:name	string	name of the dyno size	"Standard-1X"
quantity	integer	number of processes to maintain	1

Curl Example

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

Response Example

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

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

Generation

Stability: prototype

A generation represents a version of the Heroku platform that includes the app execution environment, routing, telemetry, and build systems.

Attributes

Name	Type	Description	Example
created_at	date-time	when generation was created	"2024-12-01T12:00:00Z"
id	uuid	unique identifier of generation	"01234567-89ab-cdef-0123-456789abcdef"
name	string	unique name of generation	"fir"
updated_at	date-time	when generation was updated	"2024-12-01T12:00:00Z"

Generation Info

Info for generation.

GET /generations/{stack_name_or_id}

Curl Example

$ curl -n https://api.heroku.com/generations/$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: 4500

{
  "created_at": "2024-12-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "fir",
  "updated_at": "2024-12-01T12:00:00Z"
}

Generation List

List available generations.

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

GET /generations

Curl Example

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

Response Example

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

[
  {
    "created_at": "2024-12-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "fir",
    "updated_at": "2024-12-01T12:00:00Z"
  }
]

Generation List by Team

List available generations for a team.

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

GET /teams/{team_name_or_id}/available-generations

Curl Example

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

Response Example

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

[
  {
    "created_at": "2024-12-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "fir",
    "updated_at": "2024-12-01T12:00:00Z"
  }
]

Identity Provider

Stability: production

Identity Providers represent the SAML configuration of teams or an Enterprise account

Attributes

Name	Type	Description	Example
certificate	string	raw contents of the public certificate (eg: .crt or .pem file)	"-----BEGIN CERTIFICATE----- ..."
created_at	date-time	when provider record was created	"2012-01-01T12:00:00Z"
entity_id	string	URL identifier provided by the identity provider	"https://customer-domain.idp.com"
id	uuid	unique identifier of this identity provider	"01234567-89ab-cdef-0123-456789abcdef"
organization	nullable object	team associated with this identity provider	null
organization:name	string	unique name of team	"example"
owner:id	uuid	unique identifier of the owner	"01234567-89ab-cdef-0123-456789abcdef"
owner:name	string	name of the owner	"acme"
owner:type	string	type of the owner one of:"team" or "enterprise-account"	"team"
slo_target_url	string	single log out URL for this identity provider	"https://example.com/idp/logout"
sso_target_url	string	single sign on URL for this identity provider	"https://example.com/idp/login"
updated_at	date-time	when the identity provider record was updated	"2012-01-01T12:00:00Z"

Identity Provider List By Team

Get a list of a team’s Identity Providers

GET /teams/{team_name}/identity-providers

Curl Example

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

Response Example

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

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

Identity Provider Create By Team

Create an Identity Provider for a team

POST /teams/{team_name}/identity-providers

Required Parameters

Name	Type	Description	Example
certificate	string	raw contents of the public certificate (eg: .crt or .pem file)	"-----BEGIN CERTIFICATE----- ..."
entity_id	string	URL identifier provided by the identity provider	"https://customer-domain.idp.com"
sso_target_url	string	single sign on URL for this identity provider	"https://example.com/idp/login"

Optional Parameters

Name	Type	Description	Example
slo_target_url	string	single log out URL for this identity provider	"https://example.com/idp/logout"

Curl Example

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

Response Example

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

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

Identity Provider Update By Team

Update a team’s Identity Provider

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

Optional Parameters

Name	Type	Description	Example
certificate	string	raw contents of the public certificate (eg: .crt or .pem file)	"-----BEGIN CERTIFICATE----- ..."
entity_id	string	URL identifier provided by the identity provider	"https://customer-domain.idp.com"
slo_target_url	string	single log out URL for this identity provider	"https://example.com/idp/logout"
sso_target_url	string	single sign on URL for this identity provider	"https://example.com/idp/login"

Curl Example

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

Response Example

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

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

Identity Provider Delete By Team

Delete a team’s Identity Provider

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

Curl Example

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

Response Example

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

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

Inbound Ruleset

Stability: prototype

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

Attributes

Name	Type	Description	Example
created_at	date-time	when inbound-ruleset was created	"2012-01-01T12:00:00Z"
created_by	email	unique email address	"username@example.com"
id	uuid	unique identifier of an inbound-ruleset	"01234567-89ab-cdef-0123-456789abcdef"
rules	array		[{"action":"allow","source":"1.1.1.1/1"}]
space:id	uuid	unique identifier of space	"01234567-89ab-cdef-0123-456789abcdef"
space:name	string	unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$	"nasa"

Inbound Ruleset Current

Current inbound ruleset for a space

GET /spaces/{space_id_or_name}/inbound-ruleset

Curl Example

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

Response Example

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

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

Inbound Ruleset Info

Info on an existing Inbound Ruleset

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

Curl Example

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

Response Example

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

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

Inbound Ruleset List

List all inbound rulesets for a space

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

GET /spaces/{space_id_or_name}/inbound-rulesets

Curl Example

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

Response Example

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

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

Inbound Ruleset Create

Create a new inbound ruleset

PUT /spaces/{space_id_or_name}/inbound-ruleset

Optional Parameters

Name	Type	Description	Example
rules	array		[{"action":"allow","source":"1.1.1.1/1"}]

Curl Example

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

Response Example

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

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

Invoice

Stability: development

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

Attributes

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
period_end	string	the ending date that the invoice covers	"01/31/2014"
period_start	string	the starting date that this invoice covers	"01/01/2014"
state	integer	payment status for this invoice (pending, successful, failed)	1
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 https://api.heroku.com/account/invoices/$INVOICE_NUMBER \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Invoice List

List existing invoices.

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

GET /account/invoices

Curl Example

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

Response Example

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

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

Invoice Address

Stability: development

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

Attributes

Name	Type	Description	Example
address_1	string	invoice street address line 1	"40 Hickory Blvd."
address_2	string	invoice street address line 2	"Suite 300"
city	string	invoice city	"Seattle"
country	string	country	"US"
heroku_id	string	heroku_id identifier reference	"user930223902@heroku.com"
other	string	metadata / additional information to go on invoice	"Company ABC Inc. VAT 903820"
postal_code	string	invoice zip code	"98101"
state	string	invoice state	"WA"
use_invoice_address	boolean	flag to use the invoice address for an account or not	true

Invoice Address info

Retrieve existing invoice address.

GET /account/invoice-address

Curl Example

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

Response Example

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

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

Invoice Address update

Update invoice address for an account.

PUT /account/invoice-address

Optional Parameters

Name	Type	Description	Example
address_1	string	invoice street address line 1	"40 Hickory Blvd."
address_2	string	invoice street address line 2	"Suite 300"
city	string	invoice city	"Seattle"
country	string	country	"US"
other	string	metadata / additional information to go on invoice	"Company ABC Inc. VAT 903820"
postal_code	string	invoice zip code	"98101"
state	string	invoice state	"WA"
use_invoice_address	boolean	flag to use the invoice address for an account or not	true

Curl Example

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

Response Example

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

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

Key

Stability: production

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

Attributes

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 Info

Info for existing key.

GET /account/keys/{key_id_or_fingerprint}

Curl Example

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

Response Example

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

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

Key List

List existing keys.

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

GET /account/keys

Curl Example

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

Response Example

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

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

Log Drain

Stability: production

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

Attributes

Name	Type	Description	Example
addon	nullable object	add-on that created the drain	{"id":"01234567-89ab-cdef-0123-456789abcdef","name":"singing-swiftly-1242","app":{"id":"01234567-89ab-cdef-0123-456789abcdef","name":"example"}}
addon:app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
addon:app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
addon:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
addon:name	string	globally name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$	"acme-inc-primary-database"
app	nullable object	application that is attached to this drain	{"id":"01234567-89ab-cdef-0123-456789abcdef","name":"example"}
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
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 \
  -d '{
  "url": "https://example.com/drain"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Log Drain Update

Update an add-on owned log drain.

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

Required Parameters

Name	Type	Description	Example
url	string	url associated with the log drain	"https://example.com/drain"

Curl Example

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

Response Example

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

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

Log Drain Delete

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

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

Curl Example

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

Response Example

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

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

Log Drain Info

Info for existing log drain.

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

Curl Example

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

Response Example

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

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

Log Drain List By Add-on

List existing log drains for an add-on.

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

GET /addons/{add_on_id_or_name}/log-drains

Curl Example

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

Response Example

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

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

Log Drain List

List existing log drains.

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

GET /apps/{app_id_or_name}/log-drains

Curl Example

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

Response Example

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

[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "singing-swiftly-1242",
      "app": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      }
    },
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "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_name	string	dyno name to limit results to	"'web.1' (Cedar-generation) or 'web-1234abcde-123ab' (Fir-generation)"
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
type	string	process type to limit results to	"web"

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/log-sessions \
  -d '{
  "dyno_name": "'web.1' (Cedar-generation) or 'web-1234abcde-123ab' (Fir-generation)",
  "type": "web",
  "lines": 10,
  "source": "app",
  "tail": true
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

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	"HRKU-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"
description	string	human-friendly description of this OAuth authorization	"sample authorization"
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	"HRKU-01234567-89ab-cdef-0123-456789abcdef"
scope	array	The scope of access OAuth authorization allows	["global"]
session	nullable object	this authorization’s session	null
session:id	uuid	unique identifier of OAuth token	"01234567-89ab-cdef-0123-456789abcdef"
updated_at	date-time	when OAuth authorization was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:full_name	nullable string	full name of the account owner	"Tina Edmonds"
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"

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 \
  -d '{
  "client": "01234567-89ab-cdef-0123-456789abcdef",
  "description": "sample authorization",
  "expires_in": 2592000,
  "scope": [
    "global"
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "HRKU-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",
  "description": "sample authorization",
  "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": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "session": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com",
    "full_name": "Tina Edmonds"
  }
}

OAuth Authorization Delete

Delete OAuth authorization.

DELETE /oauth/authorizations/{oauth_authorization_id}

Curl Example

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

Response Example

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

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "HRKU-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",
  "description": "sample authorization",
  "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": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "session": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com",
    "full_name": "Tina Edmonds"
  }
}

OAuth Authorization Info

Info for an OAuth authorization.

GET /oauth/authorizations/{oauth_authorization_id}

Curl Example

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

Response Example

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

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "HRKU-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",
  "description": "sample authorization",
  "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": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "session": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com",
    "full_name": "Tina Edmonds"
  }
}

OAuth Authorization Update

Update an existing OAuth authorization.

PATCH /oauth/authorizations/{oauth_authorization_id}

Required Parameters

Name	Type	Description	Example
client:id	uuid	unique identifier of this OAuth client	"01234567-89ab-cdef-0123-456789abcdef"
client:secret	string	secret used to obtain OAuth authorizations under this client	"01234567-89ab-cdef-0123-456789abcdef"

Optional Parameters

Name	Type	Description	Example
description	string	human-friendly description of this OAuth authorization	"sample authorization"

Curl Example

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

Response Example

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

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "HRKU-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",
  "description": "sample authorization",
  "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": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "session": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com",
    "full_name": "Tina Edmonds"
  }
}

OAuth Authorization List

List OAuth authorizations.

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

GET /oauth/authorizations

Curl Example

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

Response Example

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

[
  {
    "access_token": {
      "expires_in": 2592000,
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "token": "HRKU-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",
    "description": "sample authorization",
    "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": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
    },
    "scope": [
      "global"
    ],
    "session": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "user": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com",
      "full_name": "Tina Edmonds"
    }
  }
]

OAuth Authorization Regenerate

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

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

Curl Example

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

Response Example

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

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "HRKU-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",
  "description": "sample authorization",
  "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": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
  },
  "scope": [
    "global"
  ],
  "session": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com",
    "full_name": "Tina Edmonds"
  }
}

OAuth Client

Stability: production

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

Attributes

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 \
  -d '{
  "name": "example",
  "redirect_uri": "https://example.com/auth/heroku/callback"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

OAuth Client Delete

Delete OAuth client.

DELETE /oauth/clients/{oauth_client_id}

Curl Example

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

Response Example

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

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

OAuth Client Info

Info for an OAuth client. The output for unauthenticated requests excludes the secret parameter.

GET /oauth/clients/{oauth_client_id}

Curl Example

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

Response Example

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

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

OAuth Client List

List OAuth clients

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

GET /oauth/clients

Curl Example

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

Response Example

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

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

OAuth Client Update

Update OAuth client

PATCH /oauth/clients/{oauth_client_id}

Optional Parameters

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 \
  -d '{
  "name": "example",
  "redirect_uri": "https://example.com/auth/heroku/callback"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

OAuth Client Rotate Credentials

Rotate credentials for an OAuth client

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

Curl Example

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

Response Example

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

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

OAuth Grant

Stability: production

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

OAuth Token

Stability: production

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

Attributes

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	"HRKU-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	"HRKU-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	identifier of an account	"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	"HRKU-01234567-89ab-cdef-0123-456789abcdef"

Curl Example

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

Response Example

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

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "HRKU-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": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
  },
  "session": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

OAuth Token Delete

Revoke OAuth access token.

DELETE /oauth/tokens/{oauth_token_id}

Curl Example

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

Response Example

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

{
  "access_token": {
    "expires_in": 2592000,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "token": "HRKU-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": "HRKU-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"
  }
}

OCI Image

Stability: prototype

An OCI (Open Container Initiative) image is a standardized format for packaging and distributing containerized applications, ready to run on the platform.

Attributes

Name	Type	Description	Example
architecture	nullable string	build architecture for OCI image	"arm64"
base_image_name	string	name of the image used for the base layers of the OCI image	"heroku/heroku:22-cnb"
base_top_layer	string	the digest of the top most layer of the base image.	"sha256:ea36ae5fbc1e7230e0a782bf216fb46500e210382703baa6bab8acf2c6a23f78"
buildpacks	array	buildpacks of the OCI image	[{"id":"heroku/ruby","version":"2.0.0","homepage":"https://github.com/heroku/buildpacks-ruby"}]
commit	string	identification of the code in your version control system (eg: SHA of the git HEAD)	"60883d9e8947a57e04dc9124f25df004866a2051"
commit_description	string	an optional description of the provided commit	"fixed a bug with API documentation"
created_at	date-time	when the OCI image was created	"2012-01-01T12:00:00Z"
deleted_at	nullable date-time	when OCI image was deleted	"2012-01-01T12:00:00Z"
digest	string	unique identifier representing the content of the OCI image	"sha256:dc14ae5fbc1e7230e0a782bf216fb46500e210631703bcc6bab8acf2c6a23f42"
id	uuid	unique identifier of the OCI image	"01234567-89ab-cdef-0123-456789abcdef"
image_repo	string	name of the image registry repository used for storage	"d7ba1ace-b396-4691-968c-37ae53153426/builds"
process_types	object	process types of the OCI image	{"web":{"name":"web","display_cmd":"bundle exec puma -p $PORT","command":"/cnb/process/web","working_dir":"/workspace/webapp","default":true}}
stack:id	uuid	identifier of stack	"ba46bf09-7bd1-42fd-90df-a1a9a93eb4a2"
stack:name	string	unique name	"cnb"
updated_at	date-time	when the OCI image was updated	"2012-01-01T12:00:00Z"

OCI Image Info

Info for the OCI images of an app, filtered by identifier.

GET /apps/{app_id_or_name}/oci-images/{oci_image_id_or_digest}

Curl Example

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

Response Example

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

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "base_image_name": "heroku/heroku:22-cnb",
    "base_top_layer": "sha256:ea36ae5fbc1e7230e0a782bf216fb46500e210382703baa6bab8acf2c6a23f78",
    "commit": "60883d9e8947a57e04dc9124f25df004866a2051",
    "commit_description": "fixed a bug with API documentation",
    "image_repo": "d7ba1ace-b396-4691-968c-37ae53153426/builds",
    "digest": "sha256:dc14ae5fbc1e7230e0a782bf216fb46500e210631703bcc6bab8acf2c6a23f42",
    "stack": {
      "id": "ba46bf09-7bd1-42fd-90df-a1a9a93eb4a2",
      "name": "cnb"
    },
    "process_types": {
      "web": {
        "name": "web",
        "display_cmd": "bundle exec puma -p $PORT",
        "command": "/cnb/process/web",
        "working_dir": "/workspace/webapp",
        "default": true
      }
    },
    "buildpacks": [
      {
        "id": "heroku/ruby",
        "version": "2.0.0",
        "homepage": "https://github.com/heroku/buildpacks-ruby"
      }
    ],
    "created_at": "2012-01-01T12:00:00Z",
    "updated_at": "2012-01-01T12:00:00Z",
    "architecture": "arm64",
    "deleted_at": "2012-01-01T12:00:00Z"
  }
]

OCI Image Create

Create an new OCI image of an app

POST /apps/{app_id_or_name}/oci-images

Optional Parameters

Name	Type	Description	Example
architecture	nullable string	build architecture for OCI image	"arm64"
base_image_name	string	name of the image used for the base layers of the OCI image	"heroku/heroku:22-cnb"
base_top_layer	string	the digest of the top most layer of the base image.	"sha256:ea36ae5fbc1e7230e0a782bf216fb46500e210382703baa6bab8acf2c6a23f78"
buildpacks	array	buildpacks of the OCI image	[{"id":"heroku/ruby","version":"2.0.0","homepage":"https://github.com/heroku/buildpacks-ruby"}]
commit	string	identification of the code in your version control system (eg: SHA of the git HEAD)	"60883d9e8947a57e04dc9124f25df004866a2051"
commit_description	string	an optional description of the provided commit	"fixed a bug with API documentation"
digest	string	unique identifier representing the content of the OCI image	"sha256:dc14ae5fbc1e7230e0a782bf216fb46500e210631703bcc6bab8acf2c6a23f42"
image_repo	string	name of the image registry repository used for storage	"d7ba1ace-b396-4691-968c-37ae53153426/builds"
process_types	object	process types of the OCI image	{"web":{"name":"web","display_cmd":"bundle exec puma -p $PORT","command":"/cnb/process/web","working_dir":"/workspace/webapp","default":true}}
stack	string	unique name or identifier of stack	"cnb" or "01234567-89ab-cdef-0123-456789abcdef"

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/oci-images \
  -d '{
  "architecture": "arm64",
  "base_image_name": "heroku/heroku:22-cnb",
  "base_top_layer": "sha256:ea36ae5fbc1e7230e0a782bf216fb46500e210382703baa6bab8acf2c6a23f78",
  "commit": "60883d9e8947a57e04dc9124f25df004866a2051",
  "commit_description": "fixed a bug with API documentation",
  "image_repo": "d7ba1ace-b396-4691-968c-37ae53153426/builds",
  "digest": "sha256:dc14ae5fbc1e7230e0a782bf216fb46500e210631703bcc6bab8acf2c6a23f42",
  "stack": "01234567-89ab-cdef-0123-456789abcdef",
  "process_types": {
    "web": {
      "name": "web",
      "display_cmd": "bundle exec puma -p $PORT",
      "command": "/cnb/process/web",
      "working_dir": "/workspace/webapp",
      "default": true
    }
  },
  "buildpacks": [
    {
      "id": "heroku/ruby",
      "version": "2.0.0",
      "homepage": "https://github.com/heroku/buildpacks-ruby"
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "base_image_name": "heroku/heroku:22-cnb",
  "base_top_layer": "sha256:ea36ae5fbc1e7230e0a782bf216fb46500e210382703baa6bab8acf2c6a23f78",
  "commit": "60883d9e8947a57e04dc9124f25df004866a2051",
  "commit_description": "fixed a bug with API documentation",
  "image_repo": "d7ba1ace-b396-4691-968c-37ae53153426/builds",
  "digest": "sha256:dc14ae5fbc1e7230e0a782bf216fb46500e210631703bcc6bab8acf2c6a23f42",
  "stack": {
    "id": "ba46bf09-7bd1-42fd-90df-a1a9a93eb4a2",
    "name": "cnb"
  },
  "process_types": {
    "web": {
      "name": "web",
      "display_cmd": "bundle exec puma -p $PORT",
      "command": "/cnb/process/web",
      "working_dir": "/workspace/webapp",
      "default": true
    }
  },
  "buildpacks": [
    {
      "id": "heroku/ruby",
      "version": "2.0.0",
      "homepage": "https://github.com/heroku/buildpacks-ruby"
    }
  ],
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T12:00:00Z",
  "architecture": "arm64",
  "deleted_at": "2012-01-01T12:00:00Z"
}

PasswordReset

Stability: production

A password reset represents a in-process password reset attempt.

Attributes

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

PasswordReset Reset Password

Reset account’s password. This will send a reset password link to the user’s email address.

POST /password-resets

Required Parameters

Name	Type	Description	Example
email	email	unique email address	"username@example.com"

Curl Example

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

Response Example

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

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

PasswordReset Complete Reset Password

Complete password reset.

POST /password-resets/{password_reset_reset_password_token}/actions/finalize

Required Parameters

Name	Type	Description	Example
password	string	current password on the account	"currentpassword"
password_confirmation	string	confirmation of the new password	"newpassword"

Curl Example

$ curl -n -X POST https://api.heroku.com/password-resets/$PASSWORD_RESET_RESET_PASSWORD_TOKEN/actions/finalize \
  -d '{
  "password": "currentpassword",
  "password_confirmation": "newpassword"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Peering

Stability: prototype

Peering provides a way to peer your Private Space VPC to another AWS VPC.

Attributes

Name	Type	Description	Example
aws_account_id	string	The AWS account ID of your Private Space.	"123456789012"
aws_region	string	The AWS region of the peer connection.	"us-east-1"
aws_vpc_id	string	The AWS VPC ID of the peer.	"vpc-1234567890"
cidr_blocks	array	The CIDR blocks of the peer.	["10.0.0.0/16"]
expires	date-time	When a peering connection will expire.	"2020-01-01T12:00:00Z"
pcx_id	string	The AWS VPC Peering Connection ID of the peering.	"pcx-123456789012"
status	string	The status of the peering connection. one of:"initiating-request" or "pending-acceptance" or "provisioning" or "active" or "failed" or "expired" or "rejected" or "deleted"	"pending-acceptance"
type	string	The type of peering connection. one of:"heroku-managed" or "customer-managed" or "unknown"	"heroku-managed"

Peering List

List peering connections of a private space.

GET /spaces/{space_id_or_name}/peerings

Curl Example

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

Response Example

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

[
  {
    "type": "heroku-managed",
    "pcx_id": "pcx-123456789012",
    "cidr_blocks": [
      "10.0.0.0/16"
    ],
    "status": "pending-acceptance",
    "aws_vpc_id": "vpc-1234567890",
    "aws_region": "us-east-1",
    "aws_account_id": "123456789012",
    "expires": "2020-01-01T12:00:00Z"
  }
]

Peering Accept

Accept a pending peering connection with a private space.

POST /spaces/{space_id_or_name}/peerings/{peering_pcx_id}/actions/accept

Curl Example

$ curl -n -X POST https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/peerings/$PEERING_PCX_ID/actions/accept \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

Peering Destroy

Destroy an active peering connection with a private space.

DELETE /spaces/{space_id_or_name}/peerings/{peering_pcx_id}

Curl Example

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

Response Example

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

Peering Info

Fetch information for existing peering connection

GET /spaces/{space_id_or_name}/peerings/{peering_pcx_id}

Curl Example

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

Response Example

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

{
  "type": "heroku-managed",
  "pcx_id": "pcx-123456789012",
  "cidr_blocks": [
    "10.0.0.0/16"
  ],
  "status": "pending-acceptance",
  "aws_vpc_id": "vpc-1234567890",
  "aws_region": "us-east-1",
  "aws_account_id": "123456789012",
  "expires": "2020-01-01T12:00:00Z"
}

Peering Info

Stability: prototype

Peering Info gives you the information necessary to peer an AWS VPC to a Private Space.

Attributes

Name	Type	Description	Example
aws_account_id	string	The AWS account ID of your Private Space.	"123456789012"
aws_region	string	region name used by provider one of:"ap-south-1" or "eu-west-1" or "ap-southeast-1" or "ap-southeast-2" or "eu-central-1" or "eu-west-2" or "ap-northeast-2" or "ap-northeast-1" or "us-east-1" or "sa-east-1" or "us-west-1" or "us-west-2" or "ca-central-1"	"us-east-1"
dyno_cidr_blocks	array	The CIDR ranges that should be routed to the Private Space VPC.	["10.0.0.0/16"]
space_cidr_blocks	array	The CIDR ranges that should be routed to the Private Space VPC.	["10.0.0.0/16"]
unavailable_cidr_blocks	array	The CIDR ranges that you must not conflict with.	["10.0.0.0/16"]
vpc_cidr	string	The CIDR range of the Private Space VPC	"10.0.0.0/16"
vpc_id	string	The AWS VPC ID of the peer.	"vpc-1234567890"

Peering Info Info

Provides the necessary information to establish an AWS VPC Peering with your private space.

GET /spaces/{space_id_or_name}/peering-info

Curl Example

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

Response Example

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

{
  "aws_account_id": "123456789012",
  "aws_region": "us-east-1",
  "vpc_id": "vpc-1234567890",
  "vpc_cidr": "10.0.0.0/16",
  "dyno_cidr_blocks": [
    "10.0.0.0/16"
  ],
  "unavailable_cidr_blocks": [
    "10.0.0.0/16"
  ],
  "space_cidr_blocks": [
    "10.0.0.0/16"
  ]
}

Permission Entity

Stability: development

An owned entity including users’ permissions.

Attributes

Name	Type	Description	Example
id	uuid	ID of the entity.	"01234567-89ab-cdef-0123-456789abcdef"
name	string	Name of the entity.	"polar-lake-12345"
team_id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
type	string	The type of object the entity is referring to. one of:"app" or "space"	"app"
users/email	email	unique email address	"username@example.com"
users/id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
users/permissions	array	enterprise account permissions	[null]

Permission Entity List

List permission entities for a team.

GET /teams/{team_name_or_id}/permissions

Curl Example

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

Response Example

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

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "polar-lake-12345",
    "team_id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "app",
    "users": [
      {
        "email": "username@example.com",
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "permissions": [
          null
        ]
      }
    ]
  }
]

Pipeline

Stability: production

A pipeline allows grouping of apps into different stages.

Attributes

Name	Type	Description	Example
created_at	date-time	when pipeline was created	"2012-01-01T12:00:00Z"
generation:id	uuid	unique identifier of the generation of the Heroku platform for this pipeline	"01234567-89ab-cdef-0123-456789abcdef"
generation:name	string	unique name of the generation of the Heroku platform for this pipeline	"cedar"
id	uuid	unique identifier of pipeline	"01234567-89ab-cdef-0123-456789abcdef"
name	string	name of pipeline pattern: ^[a-z][a-z0-9-]{2,29}$	"example"
owner	nullable object	Owner of a pipeline.	null
owner:id	uuid	unique identifier of a pipeline owner	"01234567-89ab-cdef-0123-456789abcdef"
owner:type	string	type of pipeline owner pattern: (^team$|^user$)	"team"
updated_at	date-time	when pipeline was updated	"2012-01-01T12:00:00Z"

Pipeline Create

Create a new pipeline.

POST /pipelines

Required Parameters

Name	Type	Description	Example
name	string	name of pipeline pattern: ^[a-z][a-z0-9-]{2,29}$	"example"

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "team"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  }
}

Pipeline Info

Info for existing pipeline.

GET /pipelines/{pipeline_id_or_name}

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "team"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  }
}

Pipeline Delete

Delete an existing pipeline.

DELETE /pipelines/{pipeline_id}

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "team"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  }
}

Pipeline Update

Update an existing pipeline.

PATCH /pipelines/{pipeline_id}

Optional Parameters

Name	Type	Description	Example
name	string	name of pipeline pattern: ^[a-z][a-z0-9-]{2,29}$	"example"

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "team"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  }
}

Pipeline List

List existing pipelines.

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

GET /pipelines

Curl Example

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

Response Example

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

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "team"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "generation": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    }
  }
]

Pipeline Build

Stability: production

Information about the latest builds of apps in a pipeline. A build represents the process of transforming code into build artifacts.

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier of the app	"01234567-89ab-cdef-0123-456789abcdef"
buildpacks	nullable array	buildpacks executed for this build, in order (only applicable to Cedar-generation apps)	null
buildpacks/name	string	Buildpack Registry name of the buildpack for the app	"heroku/ruby"
buildpacks/url	string	the URL of the buildpack for the app	"https://github.com/heroku/heroku-buildpack-ruby"
created_at	date-time	when the build was created	"2012-01-01T12:00:00Z"
id	uuid	unique identifier of the build	"01234567-89ab-cdef-0123-456789abcdef"
output_stream_url	string	streaming URL of the build process output	"https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
release	nullable object	release resulting from the build	{"id":"01234567-89ab-cdef-0123-456789abcdef"}
release:id	uuid	unique identifier of the release	"01234567-89ab-cdef-0123-456789abcdef"
slug	nullable object	slug created by this build	null
slug:id	uuid	unique identifier of the slug	"01234567-89ab-cdef-0123-456789abcdef"
source_blob:checksum	nullable string	an optional checksum of the gzipped tarball for verifying its integrity	"SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
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"
source_blob:version_description	nullable string	version description of the gzipped tarball	"* Fake User: Change session key"
stack	string	stack of the build	"heroku-24"
status	string	status of the build one of:"failed" or "pending" or "succeeded"	"succeeded"
updated_at	date-time	when the build was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"

Pipeline Build List

List latest builds for each app in a pipeline

GET /pipelines/{pipeline_id}/latest-builds

Curl Example

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

Response Example

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

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

Pipeline Config Vars

Stability: production

Pipeline config vars in Heroku CI and review apps used to manage the configuration information for a pipeline.

Attributes

Name	Type	Description	Example
[“NAME”]: [“value”]	object	user-defined config var name and value	{"FOO":"bar"}

Pipeline Config Vars Info for App

Get config-vars for a pipeline stage.

GET /pipelines/{pipeline_id}/stage/{pipeline_coupling_stage}/config-vars

Curl Example

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

Response Example

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

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

Pipeline Config Vars Update

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

PATCH /pipelines/{pipeline_id}/stage/{pipeline_coupling_stage}/config-vars

Curl Example

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

Response Example

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

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

Pipeline Coupling

Stability: production

Information about an app’s coupling to a pipeline

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
created_at	date-time	when pipeline coupling was created	"2012-01-01T12:00:00Z"
id	uuid	unique identifier of pipeline coupling	"01234567-89ab-cdef-0123-456789abcdef"
pipeline:id	uuid	unique identifier of pipeline	"01234567-89ab-cdef-0123-456789abcdef"
stage	string	target pipeline stage one of:"test" or "review" or "development" or "staging" or "production"	"production"
updated_at	date-time	when pipeline coupling was updated	"2012-01-01T12:00:00Z"

Pipeline Coupling List By Pipeline

List couplings for a pipeline

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

GET /pipelines/{pipeline_id}/pipeline-couplings

Curl Example

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

Response Example

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

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "pipeline": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "stage": "production",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Pipeline Coupling List By Current User

List pipeline couplings for the current user.

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

GET /users/~/pipeline-couplings

Curl Example

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

Response Example

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

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "pipeline": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "stage": "production",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Pipeline Coupling List

List pipeline couplings.

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

GET /pipeline-couplings

Curl Example

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

Response Example

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

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "pipeline": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "stage": "production",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Pipeline Coupling List By Team

List pipeline couplings for a team.

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

GET /teams/{team_name_or_id}/pipeline-couplings

Curl Example

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

Response Example

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

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "pipeline": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "stage": "production",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Pipeline Coupling Create

Create a new pipeline coupling.

POST /pipeline-couplings

Required Parameters

Name	Type	Description	Example
app	string	unique identifier or name of app	"01234567-89ab-cdef-0123-456789abcdef" or "example"
pipeline	uuid	unique identifier of pipeline	"01234567-89ab-cdef-0123-456789abcdef"
stage	string	target pipeline stage one of:"test" or "review" or "development" or "staging" or "production"	"production"

Curl Example

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

Response Example

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

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "stage": "production",
  "updated_at": "2012-01-01T12:00:00Z"
}

Pipeline Coupling Info

Info for an existing pipeline coupling.

GET /pipeline-couplings/{pipeline_coupling_id}

Curl Example

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

Response Example

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

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "stage": "production",
  "updated_at": "2012-01-01T12:00:00Z"
}

Pipeline Coupling Delete

Delete an existing pipeline coupling.

DELETE /pipeline-couplings/{pipeline_coupling_id}

Curl Example

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

Response Example

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

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "stage": "production",
  "updated_at": "2012-01-01T12:00:00Z"
}

Pipeline Coupling Update

Update an existing pipeline coupling.

PATCH /pipeline-couplings/{pipeline_coupling_id}

Optional Parameters

Name	Type	Description	Example
stage	string	target pipeline stage one of:"test" or "review" or "development" or "staging" or "production"	"production"

Curl Example

$ curl -n -X PATCH https://api.heroku.com/pipeline-couplings/$PIPELINE_COUPLING_ID \
  -d '{
  "stage": "production"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "stage": "production",
  "updated_at": "2012-01-01T12:00:00Z"
}

Pipeline Coupling Info By App

Info for an existing pipeline coupling.

GET /apps/{app_id_or_name}/pipeline-couplings

Curl Example

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

Response Example

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

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "stage": "production",
  "updated_at": "2012-01-01T12:00:00Z"
}

Pipeline Deployment

Stability: production

Information about the latest deployment of each app in a pipeline. A deployment is the process of moving the build artifacts to a target environment.

Attributes

Name	Type	Description	Example
addon_plan_names	array	add-on plans installed on the app for this deployment	["heroku-postgresql:dev"]
app:id	uuid	unique identifier of the app	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	unique name of the app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
artifacts:id	string	unique identifier or identifier of the OCI image	"01234567-89ab-cdef-0123-456789abcdef" or "01234567-89ab-cdef-0123-456789abcdef"
artifacts:type	string	type of artifact	"slug"
created_at	date-time	when the deployment was created	"2012-01-01T12:00:00Z"
current	boolean	indicates if this deployment is the current one for the app	true
description	string	description of changes in this deployment	"Added new feature"
eligible_for_rollback	boolean	indicates if this deployment is eligible for rollback	true
id	uuid	unique identifier of the deployment	"01234567-89ab-cdef-0123-456789abcdef"
output_stream_url	nullable string	streaming URL for the release command output	"https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
slug	nullable object	slug running in this deployment	null
slug:id	uuid	unique identifier of the slug	"01234567-89ab-cdef-0123-456789abcdef"
status	string	current status of the deployment one of:"failed" or "pending" or "succeeded" or "expired"	"succeeded"
updated_at	date-time	when the deployment was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
version	integer	unique version assigned to the deployment	11

Pipeline Deployment List

List latest deployments for each app in a pipeline. A deployment is a release that changed your source slug, container image, or Heroku processes.

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

GET /pipelines/{pipeline_id}/latest-deployments

Curl Example

$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/latest-deployments \
  -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: 4500

[
  {
    "addon_plan_names": [
      "heroku-postgresql:dev"
    ],
    "artifacts": [
      {
        "type": "slug",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      }
    ],
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "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"
    },
    "status": "succeeded",
    "user": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com"
    },
    "version": 11,
    "current": true,
    "output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
    "eligible_for_rollback": true
  }
]

Stability: production

Promotions allow you to move code from an app in a pipeline to all targets

Attributes

Name	Type	Description	Example
created_at	date-time	when promotion was created	"2012-01-01T12:00:00Z"
id	uuid	unique identifier of promotion	"01234567-89ab-cdef-0123-456789abcdef"
pipeline:id	uuid	unique identifier of pipeline	"01234567-89ab-cdef-0123-456789abcdef"
source:app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
source:release:id	uuid	unique identifier of release	"01234567-89ab-cdef-0123-456789abcdef"
status	string	status of promotion one of:"pending" or "completed"	"pending"
updated_at	nullable date-time	when promotion was updated	"2012-01-01T12:00:00Z"

Pipeline Promotion Create

Create a new promotion.

POST /pipeline-promotions

Required Parameters

Name	Type	Description	Example
pipeline:id	uuid	unique identifier of pipeline	"01234567-89ab-cdef-0123-456789abcdef"
source:app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
source:release:id	uuid	unique identifier of release	"01234567-89ab-cdef-0123-456789abcdef"
targets/app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "source": {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "release": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  },
  "status": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

Pipeline Promotion Info

Info for existing pipeline promotion.

GET /pipeline-promotions/{pipeline_promotion_id}

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "source": {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "release": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  },
  "status": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

Stability: production

Promotion targets represent an individual app being promoted to

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
error_message	nullable string	an error message for why the promotion failed	"User does not have access to that app"
id	uuid	unique identifier of promotion target	"01234567-89ab-cdef-0123-456789abcdef"
pipeline_promotion:id	uuid	unique identifier of promotion	"01234567-89ab-cdef-0123-456789abcdef"
release	nullable object	the release which was created on the target app	null
release:id	uuid	unique identifier of release	"01234567-89ab-cdef-0123-456789abcdef"
status	string	status of promotion one of:"pending" or "succeeded" or "failed"	"pending"

Pipeline Promotion Target List

List promotion targets belonging to an existing promotion.

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

GET /pipeline-promotions/{pipeline_promotion_id}/promotion-targets

Curl Example

$ curl -n https://api.heroku.com/pipeline-promotions/$PIPELINE_PROMOTION_ID/promotion-targets \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "error_message": "User does not have access to that app",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "pipeline_promotion": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "release": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "status": "pending"
  }
]

Pipeline Release

Stability: production

Information about the latest release of each app in a pipeline. A release makes a deployment available to end-users.

Attributes

Name	Type	Description	Example
addon_plan_names	array	add-on plans installed on the app for this release	["heroku-postgresql:dev"]
app:id	uuid	unique identifier of the app	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	unique name of the app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
artifacts:id	string	unique identifier or identifier of the OCI image	"01234567-89ab-cdef-0123-456789abcdef" or "01234567-89ab-cdef-0123-456789abcdef"
artifacts:type	string	type of artifact	"slug"
created_at	date-time	when the release was created	"2012-01-01T12:00:00Z"
current	boolean	indicates if this release is the current one for the app	true
description	string	description of changes in this release	"Added new feature"
eligible_for_rollback	boolean	indicates if this release is eligible for rollback	true
id	uuid	unique identifier of the release	"01234567-89ab-cdef-0123-456789abcdef"
output_stream_url	nullable string	streaming URL of the build process output	"https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
slug	nullable object	slug running in the release	null
slug:id	uuid	unique identifier of the slug	"01234567-89ab-cdef-0123-456789abcdef"
status	string	current status of the release one of:"failed" or "pending" or "succeeded" or "expired"	"succeeded"
updated_at	date-time	when the release was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
version	integer	unique version assigned to the release	11

Pipeline Release List

List latest releases for each app in a pipeline

GET /pipelines/{pipeline_id}/latest-releases

Curl Example

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

Response Example

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

[
  {
    "addon_plan_names": [
      "heroku-postgresql:dev"
    ],
    "artifacts": [
      {
        "type": "slug",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      }
    ],
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "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"
    },
    "status": "succeeded",
    "user": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com"
    },
    "version": 11,
    "current": true,
    "output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
    "eligible_for_rollback": true
  }
]

Pipeline Stack

Stability: production

A pipeline’s stack is determined by the apps in the pipeline. This is used during creation of CI and Review Apps that have no stack defined in app.json

Attributes

Name	Type	Description	Example
stack	nullable object	identity of the stack that will be used for new builds without a stack defined in CI and Review Apps	null
stack:id	uuid	identifier of stack	"01234567-89ab-cdef-0123-456789abcdef"
stack:name	string	unique name	"heroku-18"

Pipeline Stack Default Stack

The stack for a given pipeline, used for CI and Review Apps that have no stack defined in app.json.

GET /pipelines/{pipeline_id}/pipeline-stack

Curl Example

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

Response Example

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

{
  "stack": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "heroku-18"
  }
}

Pipeline Transfer

Stability: production

A pipeline transfer is the process of changing pipeline ownership along with the contained apps.

Attributes

Name	Type	Description	Example
new_owner:id	uuid	unique identifier of a pipeline owner	"01234567-89ab-cdef-0123-456789abcdef"
new_owner:type	string	type of pipeline owner pattern: (^team$|^user$)	"team"
pipeline:id	uuid	unique identifier of pipeline	"01234567-89ab-cdef-0123-456789abcdef"
previous_owner:id	uuid	unique identifier of a pipeline owner	"01234567-89ab-cdef-0123-456789abcdef"
previous_owner:type	string	type of pipeline owner pattern: (^team$|^user$)	"team"

Pipeline Transfer Create

Create a new pipeline transfer.

POST /pipeline-transfers

Required Parameters

Name	Type	Description	Example
new_owner:id	uuid	unique identifier of a pipeline owner	"01234567-89ab-cdef-0123-456789abcdef"
new_owner:type	string	type of pipeline owner pattern: (^team$|^user$)	"team"
pipeline:id	uuid	unique identifier of pipeline	"01234567-89ab-cdef-0123-456789abcdef"

Curl Example

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

Response Example

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

{
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "previous_owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "team"
  },
  "new_owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "team"
  }
}

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
addon_service:id	uuid	unique identifier of this add-on-service	"01234567-89ab-cdef-0123-456789abcdef"
addon_service:name	string	unique name of this add-on-service	"heroku-postgresql"
compliance	nullable array	the compliance regimes applied to an add-on plan	["HIPAA"]
created_at	date-time	when plan was created	"2012-01-01T12:00:00Z"
default	boolean	whether this plan is the default for its add-on service	false
description	string	description of plan	"Heroku Postgres Dev"
human_name	string	human readable name of the add-on plan	"Dev"
id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
installable_inside_private_network	boolean	whether this plan is installable to a Private Spaces app	false
installable_outside_private_network	boolean	whether this plan is installable to a Common Runtime app	true
name	string	name of this plan	"heroku-postgresql:dev"
price:cents	integer	price in cents per unit of plan	0
price:contract	boolean	price is negotiated in a contract outside of monthly add-on billing	false
price:unit	string	unit of price for plan	"month"
space_default	boolean	whether this plan is the default for apps in Private Spaces	false
state	string	release status for plan	"public"
updated_at	date-time	when plan was updated	"2012-01-01T12:00:00Z"
visible	boolean	whether this plan is publicly visible	true

Plan Info

Info for existing plan.

GET /plans/{plan_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/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: 4500

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

Plan Info By Add-on

Info for existing plan by Add-on.

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

Curl Example

$ curl -n https://api.heroku.com/addon-services/$ADD_ON_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: 4500

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

Plan List By Add-on

List existing plans by Add-on.

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

GET /addon-services/{add_on_service_id_or_name}/plans

Curl Example

$ curl -n https://api.heroku.com/addon-services/$ADD_ON_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: 4500

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

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 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: 4500

{
  "remaining": 2399
}

Region

Stability: production

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

Attributes

Name	Type	Description	Example
country	string	country where the region exists	"United States"
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"
locale	string	area in the country where the region exists	"Virginia"
name	string	name of region	"us"
private_capable	boolean	whether or not region is available for creating a Private Space	false
provider:name	string	name of provider	"amazon-web-services"
provider:region	string	region name used by provider one of:"ap-south-1" or "eu-west-1" or "ap-southeast-1" or "ap-southeast-2" or "eu-central-1" or "eu-west-2" or "ap-northeast-2" or "ap-northeast-1" or "us-east-1" or "sa-east-1" or "us-west-1" or "us-west-2" or "ca-central-1"	"us-east-1"
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 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: 4500

{
  "country": "United States",
  "created_at": "2012-01-01T12:00:00Z",
  "description": "United States",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "locale": "Virginia",
  "name": "us",
  "private_capable": false,
  "provider": {
    "name": "amazon-web-services",
    "region": "us-east-1"
  },
  "updated_at": "2012-01-01T12:00:00Z"
}

Region List

List existing regions.

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

GET /regions

Curl Example

$ curl -n 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: 4500

[
  {
    "country": "United States",
    "created_at": "2012-01-01T12:00:00Z",
    "description": "United States",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "locale": "Virginia",
    "name": "us",
    "private_capable": false,
    "provider": {
      "name": "amazon-web-services",
      "region": "us-east-1"
    },
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

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
addon_plan_names	array	add-on plans installed on the app for this release	["heroku-postgresql:dev"]
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
artifacts	array	build artifacts for the release	[{"type":"slug","id":"01234567-89ab-cdef-0123-456789abcdef"}]
created_at	date-time	when release was created	"2012-01-01T12:00:00Z"
current	boolean	indicates this release as being the current one for the app	true
description	string	description of changes in this release	"Added new feature"
eligible_for_rollback	boolean	indicates if this release is eligible for rollback	true
id	uuid	unique identifier of release	"01234567-89ab-cdef-0123-456789abcdef"
output_stream_url	nullable string	Release command output will be available from this URL as a stream. The stream is available as either text/plain or text/event-stream. Clients should be prepared to handle disconnects and can resume the stream by sending a Range header (for text/plain) or a Last-Event-Id header (for text/event-stream).	"https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
slug	nullable object	slug running in this release	null
slug:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
status	string	current status of the release one of:"failed" or "pending" or "succeeded" or "expired"	"succeeded"
updated_at	date-time	when release was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:id	uuid	identifier of an account	"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 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: 4500

{
  "addon_plan_names": [
    "heroku-postgresql:dev"
  ],
  "artifacts": [
    {
      "type": "slug",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  ],
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "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"
  },
  "status": "succeeded",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com"
  },
  "version": 11,
  "current": true,
  "output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
  "eligible_for_rollback": true
}

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 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: 4500

[
  {
    "addon_plan_names": [
      "heroku-postgresql:dev"
    ],
    "artifacts": [
      {
        "type": "slug",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      }
    ],
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "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"
    },
    "status": "succeeded",
    "user": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "email": "username@example.com"
    },
    "version": 11,
    "current": true,
    "output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
    "eligible_for_rollback": true
  }
]

Release Create

Create new release.

POST /apps/{app_id_or_name}/releases

Required Parameters

Name	Type	Description	Example
slug	string	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"

Optional Parameters

Name	Type	Description	Example
description	string	description of changes in this release	"Added new feature"
oci_image	string	identifier or identifier representing the content of the OCI image	"01234567-89ab-cdef-0123-456789abcdef" or "sha256:dc14ae5fbc1e7230e0a782bf216fb46500e210631703bcc6bab8acf2c6a23f42"

Curl Example

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

Response Example

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

{
  "addon_plan_names": [
    "heroku-postgresql:dev"
  ],
  "artifacts": [
    {
      "type": "slug",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  ],
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "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"
  },
  "status": "succeeded",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com"
  },
  "version": 11,
  "current": true,
  "output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
  "eligible_for_rollback": true
}

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 \
  -d '{
  "release": "01234567-89ab-cdef-0123-456789abcdef"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "addon_plan_names": [
    "heroku-postgresql:dev"
  ],
  "artifacts": [
    {
      "type": "slug",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  ],
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "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"
  },
  "status": "succeeded",
  "user": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "email": "username@example.com"
  },
  "version": 11,
  "current": true,
  "output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
  "eligible_for_rollback": true
}

Review App

Stability: production

An ephemeral app to review a set of changes

Attributes

Name	Type	Description	Example
app	nullable object	the Heroku app associated to this review app	null
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app_setup	nullable object	the app setup for this review app	null
app_setup:id	uuid	unique identifier of app setup	"01234567-89ab-cdef-0123-456789abcdef"
branch	string	the branch of the repository which the review app is based on	"example"
created_at	date-time	when test run was created	"2015-01-01T12:00:00Z"
creator	object	The user who created the review app
error_status	nullable string	error message from creating the review app if any	null
fork_repo	nullable object		null
fork_repo:id	nullable integer	repository id of the fork the branch resides in	"123456"
id	uuid	unique identifier of the review app	"01234567-89ab-cdef-0123-456789abcdef"
message	nullable string	message from creating the review app if any	null
pipeline:id	uuid	unique identifier of pipeline	"01234567-89ab-cdef-0123-456789abcdef"
pr_number	nullable integer	pull request number the review app is built for	24
status	string	current state of the review app one of:"pending" or "creating" or "created" or "deleting" or "deleted" or "errored"	"pending"
updated_at	date-time	when review app was updated	"2015-01-01T12:00:00Z"
wait_for_ci	boolean	wait for ci before building the app	true

Review App Create

Create a new review app

POST /review-apps

Required Parameters

Name	Type	Description	Example
branch	string	the branch of the repository which the review app is based on	"example"
pipeline	uuid	unique identifier of pipeline	"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	The version number (or SHA) of the code to build.	"v1.2.0"

Optional Parameters

Name	Type	Description	Example
environment	nullable object	A set of key value pairs which will be put into the environment of the spawned review app process.	{"FOO":"bar","BAZ":"qux"}
fork_repo_id	nullable integer	repository id of the fork the branch resides in	"123456"
pr_number	nullable integer	pull request number the review app is built for	24

Curl Example

$ curl -n -X POST https://api.heroku.com/review-apps \
  -d '{
  "branch": "example",
  "pr_number": 24,
  "pipeline": "01234567-89ab-cdef-0123-456789abcdef",
  "source_blob": {
    "url": "https://example.com/source.tgz?token=xyz",
    "version": "v1.2.0"
  },
  "environment": {
    "FOO": "bar",
    "BAZ": "qux"
  },
  "fork_repo_id": "123456"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "app_setup": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "branch": "example",
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "status": "pending",
  "updated_at": "2015-01-01T12:00:00Z",
  "creator": null,
  "wait_for_ci": true,
  "error_status": "example",
  "message": "example",
  "fork_repo": {
    "id": "123456"
  },
  "pr_number": 24
}

Review App Get review app

Gets an existing review app

GET /review-apps/{review_app_id}

Curl Example

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

Response Example

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

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "app_setup": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "branch": "example",
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "status": "pending",
  "updated_at": "2015-01-01T12:00:00Z",
  "creator": null,
  "wait_for_ci": true,
  "error_status": "example",
  "message": "example",
  "fork_repo": {
    "id": "123456"
  },
  "pr_number": 24
}

Review App Delete

Delete an existing review app

DELETE /review-apps/{review_app_id}

Curl Example

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

Response Example

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

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "app_setup": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "branch": "example",
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "status": "pending",
  "updated_at": "2015-01-01T12:00:00Z",
  "creator": null,
  "wait_for_ci": true,
  "error_status": "example",
  "message": "example",
  "fork_repo": {
    "id": "123456"
  },
  "pr_number": 24
}

Review App Get review app by app_id

Get a review app using the associated app_id

GET /apps/{app_id_or_name}/review-app

Curl Example

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

Response Example

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

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "app_setup": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "branch": "example",
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "status": "pending",
  "updated_at": "2015-01-01T12:00:00Z",
  "creator": null,
  "wait_for_ci": true,
  "error_status": "example",
  "message": "example",
  "fork_repo": {
    "id": "123456"
  },
  "pr_number": 24
}

Review App List

List review apps for a pipeline

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

GET /pipelines/{pipeline_id}/review-apps

Curl Example

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

Response Example

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

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "app_setup": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "branch": "example",
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "pipeline": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "status": "pending",
    "updated_at": "2015-01-01T12:00:00Z",
    "creator": null,
    "wait_for_ci": true,
    "error_status": "example",
    "message": "example",
    "fork_repo": {
      "id": "123456"
    },
    "pr_number": 24
  }
]

Review App Configuration

Stability: production

Review apps can be configured for pipelines.

Attributes

Name	Type	Description	Example
automatic_review_apps	boolean	enable automatic review apps for pull requests	true
base_name	nullable string	A unique prefix that will be used to create review app names	"singular-app"
deploy_target	nullable object	the deploy target for the review apps of a pipeline	null
deploy_target:id	string	unique identifier of deploy target pattern: (^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$|^[a-z]{2}$)	"us"
deploy_target:type	string	type of deploy target pattern: (^space$|^region$)	"region"
destroy_stale_apps	boolean	automatically destroy review apps when they haven’t been deployed for a number of days	true
pipeline_id	uuid	unique identifier of pipeline	"01234567-89ab-cdef-0123-456789abcdef"
repo:id	integer	repository id	"123456"
stale_days	integer	number of days without a deployment after which to consider a review app stale	"5"
wait_for_ci	boolean	If true, review apps are created only when CI passes	true

Review App Configuration Enable

Enable review apps for a pipeline

POST /pipelines/{pipeline_id}/review-app-config

Required Parameters

Name	Type	Description	Example
repo	string	The full_name of the repository that you want enable review-apps from.	"heroku/homebrew-brew"

Optional Parameters

Name	Type	Description	Example
automatic_review_apps	boolean	If true, this will trigger the creation of review apps when pull-requests are opened in the repo.	true
base_name	nullable string	A unique prefix that will be used to create review app names	"singular-app"
deploy_target	nullable object	Provides a key/value pair to specify whether to use a common runtime or a private space	null
deploy_target:id	string	unique identifier of deploy target pattern: (^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$|^[a-z]{2}$)	"us"
deploy_target:type	string	type of deploy target pattern: (^space$|^region$)	"region"
destroy_stale_apps	boolean	If true, this will trigger automatic deletion of review apps when they’re stale	true
stale_days	integer	If destroy_stale_apps is true, then apps will be destroyed after this many days	"5"
wait_for_ci	boolean	If true, review apps will only be created when CI passes	true

Curl Example

$ curl -n -X POST https://api.heroku.com/pipelines/$PIPELINE_ID/review-app-config \
  -d '{
  "repo": "heroku/homebrew-brew",
  "automatic_review_apps": true,
  "destroy_stale_apps": true,
  "stale_days": "5",
  "deploy_target": {
    "id": "us",
    "type": "region"
  },
  "wait_for_ci": true,
  "base_name": "singular-app"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "repo": {
    "id": "123456"
  },
  "automatic_review_apps": true,
  "deploy_target": {
    "id": "us",
    "type": "region"
  },
  "destroy_stale_apps": true,
  "stale_days": "5",
  "pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
  "wait_for_ci": true,
  "base_name": "singular-app"
}

Review App Configuration Info

Get review apps configuration for a pipeline

GET /pipelines/{pipeline_id}/review-app-config

Curl Example

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

Response Example

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

{
  "repo": {
    "id": "123456"
  },
  "automatic_review_apps": true,
  "deploy_target": {
    "id": "us",
    "type": "region"
  },
  "destroy_stale_apps": true,
  "stale_days": "5",
  "pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
  "wait_for_ci": true,
  "base_name": "singular-app"
}

Review App Configuration Update

Update review app configuration for a pipeline

PATCH /pipelines/{pipeline_id}/review-app-config

Optional Parameters

Name	Type	Description	Example
automatic_review_apps	boolean	If true, this will trigger the creation of review apps when pull-requests are opened in the repo	true
base_name	nullable string	A unique prefix that will be used to create review app names	"singular-app"
deploy_target	nullable object	Provides a key/value pair to specify whether to use a common runtime or a private space	null
deploy_target:id	string	unique identifier of deploy target pattern: (^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$|^[a-z]{2}$)	"us"
deploy_target:type	string	type of deploy target pattern: (^space$|^region$)	"region"
destroy_stale_apps	boolean	If true, this will trigger automatic deletion of review apps when they’re stale	true
stale_days	integer	If destroy_stale_apps is true, then apps will be destroyed after this many days	"5"
wait_for_ci	boolean	If true, review apps will only be created when CI passes	true

Curl Example

$ curl -n -X PATCH https://api.heroku.com/pipelines/$PIPELINE_ID/review-app-config \
  -d '{
  "automatic_review_apps": true,
  "destroy_stale_apps": true,
  "stale_days": "5",
  "deploy_target": {
    "id": "us",
    "type": "region"
  },
  "wait_for_ci": true,
  "base_name": "singular-app"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "repo": {
    "id": "123456"
  },
  "automatic_review_apps": true,
  "deploy_target": {
    "id": "us",
    "type": "region"
  },
  "destroy_stale_apps": true,
  "stale_days": "5",
  "pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
  "wait_for_ci": true,
  "base_name": "singular-app"
}

Review App Configuration Delete

Disable review apps for a pipeline

DELETE /pipelines/{pipeline_id}/review-app-config

Curl Example

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

Response Example

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

{
  "repo": {
    "id": "123456"
  },
  "automatic_review_apps": true,
  "deploy_target": {
    "id": "us",
    "type": "region"
  },
  "destroy_stale_apps": true,
  "stale_days": "5",
  "pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
  "wait_for_ci": true,
  "base_name": "singular-app"
}

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"
checksum	nullable string	an optional checksum of the slug for verifying its integrity	"SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
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"
deleted_at	nullable date-time	when slug was deleted	"2012-01-01T12:00:00Z"
id	uuid	unique identifier	"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	identifier of stack	"01234567-89ab-cdef-0123-456789abcdef"
stack:name	string	unique name	"heroku-18"
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 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: 4500

{
  "blob": {
    "method": "GET",
    "url": "https://api.heroku.com/slugs/1234.tgz"
  },
  "buildpack_provided_description": "Ruby/Rack",
  "checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "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": "heroku-18"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "deleted_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"
checksum	nullable string	an optional checksum of the slug for verifying its integrity	"SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
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 name or identifier of stack	"heroku-18" or "01234567-89ab-cdef-0123-456789abcdef"

Curl Example

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

Response Example

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

{
  "blob": {
    "method": "PUT",
    "url": "https://api.heroku.com/slugs/1234.tgz"
  },
  "buildpack_provided_description": "Ruby/Rack",
  "checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "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": "heroku-18"
  },
  "updated_at": "2012-01-01T12:00:00Z"
}

SMS Number

Stability: production

SMS numbers are used for recovery on accounts with two-factor authentication enabled.

Attributes

Name	Type	Description	Example
sms_number	nullable string	SMS number of account	"+1 ***-***-1234"

SMS Number SMS Number

Recover an account using an SMS recovery code

GET /users/{account_email_or_id_or_self}/sms-number

Curl Example

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

Response Example

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

{
  "sms_number": "+1 ***-***-1234"
}

SMS Number Recover

Recover an account using an SMS recovery code

POST /users/{account_email_or_id_or_self}/sms-number/actions/recover

Curl Example

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

Response Example

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

{
  "sms_number": "+1 ***-***-1234"
}

SMS Number Confirm

Confirm an SMS number change with a confirmation code

POST /users/{account_email_or_id_or_self}/sms-number/actions/confirm

Curl Example

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

Response Example

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

{
  "sms_number": "+1 ***-***-1234"
}

SNI Endpoint

Stability: development

SNI Endpoint is a public address serving a custom SSL cert for HTTPS traffic, using the SNI TLS extension, to a Heroku app.

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
certificate_chain	string	raw contents of the public certificate chain (eg: .crt or .pem file)	"-----BEGIN CERTIFICATE----- ..."
created_at	date-time	when endpoint was created	"2012-01-01T12:00:00Z"
display_name	nullable string	unique name for SSL certificate pattern: ^[a-z][a-z0-9-]{2,29}$	"example"
domains	array	domains associated with this SSL certificate	["01234567-89ab-cdef-0123-456789abcdef"]
id	uuid	unique identifier of this SNI endpoint	"01234567-89ab-cdef-0123-456789abcdef"
name	string	unique name for SNI endpoint pattern: ^[a-z][a-z0-9-]{2,29}$	"example"
ssl_cert:ca_signed?	boolean		true
ssl_cert:cert_domains	array
ssl_cert:expires_at	date-time		"2015-01-01T12:00:00Z"
ssl_cert:id	uuid	unique identifier of this SSL certificate	"01234567-89ab-cdef-0123-456789abcdef"
ssl_cert:issuer	string		"example"
ssl_cert:self_signed?	boolean		true
ssl_cert:starts_at	date-time		"2015-01-01T12:00:00Z"
ssl_cert:subject	string		"example"
updated_at	date-time	when SNI endpoint was updated	"2012-01-01T12:00:00Z"

SNI Endpoint Create

Create a new SNI endpoint.

POST /apps/{app_id_or_name}/sni-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----- ..."

Curl Example

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

Response Example

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

{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z",
  "display_name": "example",
  "domains": [
    "01234567-89ab-cdef-0123-456789abcdef"
  ],
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "ssl_cert": {
    "ca_signed?": true,
    "cert_domains": null,
    "expires_at": "2015-01-01T12:00:00Z",
    "issuer": "example",
    "self_signed?": true,
    "starts_at": "2015-01-01T12:00:00Z",
    "subject": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

SNI Endpoint Delete

Delete existing SNI endpoint.

DELETE /apps/{app_id_or_name}/sni-endpoints/{sni_endpoint_id_or_name}

Curl Example

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

Response Example

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

{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z",
  "display_name": "example",
  "domains": [
    "01234567-89ab-cdef-0123-456789abcdef"
  ],
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "ssl_cert": {
    "ca_signed?": true,
    "cert_domains": null,
    "expires_at": "2015-01-01T12:00:00Z",
    "issuer": "example",
    "self_signed?": true,
    "starts_at": "2015-01-01T12:00:00Z",
    "subject": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

SNI Endpoint Info

Info for existing SNI endpoint.

GET /apps/{app_id_or_name}/sni-endpoints/{sni_endpoint_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/sni-endpoints/$SNI_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: 4500

{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z",
  "display_name": "example",
  "domains": [
    "01234567-89ab-cdef-0123-456789abcdef"
  ],
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "ssl_cert": {
    "ca_signed?": true,
    "cert_domains": null,
    "expires_at": "2015-01-01T12:00:00Z",
    "issuer": "example",
    "self_signed?": true,
    "starts_at": "2015-01-01T12:00:00Z",
    "subject": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

SNI Endpoint List

List existing SNI endpoints.

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

GET /apps/{app_id_or_name}/sni-endpoints

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/sni-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: 4500

[
  {
    "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "updated_at": "2012-01-01T12:00:00Z",
    "display_name": "example",
    "domains": [
      "01234567-89ab-cdef-0123-456789abcdef"
    ],
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "ssl_cert": {
      "ca_signed?": true,
      "cert_domains": null,
      "expires_at": "2015-01-01T12:00:00Z",
      "issuer": "example",
      "self_signed?": true,
      "starts_at": "2015-01-01T12:00:00Z",
      "subject": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
]

SNI Endpoint Update

Update an existing SNI endpoint.

PATCH /apps/{app_id_or_name}/sni-endpoints/{sni_endpoint_id_or_name}

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

Curl Example

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

Response Example

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

{
  "certificate_chain": "-----BEGIN CERTIFICATE----- ...",
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "updated_at": "2012-01-01T12:00:00Z",
  "display_name": "example",
  "domains": [
    "01234567-89ab-cdef-0123-456789abcdef"
  ],
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "ssl_cert": {
    "ca_signed?": true,
    "cert_domains": null,
    "expires_at": "2015-01-01T12:00:00Z",
    "issuer": "example",
    "self_signed?": true,
    "starts_at": "2015-01-01T12:00:00Z",
    "subject": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

Source

Stability: production

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/sources/1234.tgz"
source_blob:put_url	string	URL to upload the source	"https://api.heroku.com/sources/1234.tgz"

Source Create

Create URLs for uploading and downloading source.

POST /sources

Curl Example

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

Response Example

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

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

Source Create - Deprecated

Create URLs for uploading and downloading source. Deprecated in favor of POST /sources

POST /apps/{app_id_or_name}/sources

Curl Example

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

Response Example

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

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

Space

Stability: production

A space is an isolated, highly available, secure app execution environment.

Attributes

Name	Type	Description	Example
cidr	string	The RFC-1918 CIDR the Private Space will use. It must be a /16 in 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16 default: "10.0.0.0/16" pattern: ^((?:10|172.(?:1[6-9]|2[0-9]|3[01])|192.168)..*.+\/16)$	"172.20.20.30/16"
created_at	date-time	when space was created	"2012-01-01T12:00:00Z"
data_cidr	string	The RFC-1918 CIDR that the Private Space will use for the Heroku-managed peering connection that’s automatically created when using Heroku Data add-ons. It must be between a /16 and a /20	"10.2.0.0/16"
generation:id	uuid	unique identifier of the generation of the Heroku platform for this space	"01234567-89ab-cdef-0123-456789abcdef"
generation:name	string	unique name of the generation of the Heroku platform for this space	"cedar"
id	uuid	unique identifier of space	"01234567-89ab-cdef-0123-456789abcdef"
name	string	unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$	"nasa"
organization:name	string	unique name of team	"example"
region:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
region:name	string	name of region	"us"
shield	boolean	true if this space has shield enabled	true
state	string	availability of this space one of:"allocating" or "allocated" or "deleting"	"allocated"
team:id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
team:name	string	unique name of team	"example"
updated_at	date-time	when space was updated	"2012-01-01T12:00:00Z"

Space List

List existing spaces.

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

GET /spaces

Curl Example

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

Response Example

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

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa",
    "organization": {
      "name": "example"
    },
    "team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "region": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "us"
    },
    "shield": true,
    "state": "allocated",
    "updated_at": "2012-01-01T12:00:00Z",
    "cidr": "172.20.20.30/16",
    "data_cidr": "10.2.0.0/16",
    "generation": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    }
  }
]

Space Info

Info for existing space.

GET /spaces/{space_id_or_name}

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "nasa",
  "organization": {
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "shield": true,
  "state": "allocated",
  "updated_at": "2012-01-01T12:00:00Z",
  "cidr": "172.20.20.30/16",
  "data_cidr": "10.2.0.0/16",
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  }
}

Space Update

Update an existing space.

PATCH /spaces/{space_id_or_name}

Optional Parameters

Name	Type	Description	Example
name	string	unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$	"nasa"

Curl Example

$ curl -n -X PATCH https://api.heroku.com/spaces/$SPACE_ID_OR_NAME \
  -d '{
  "name": "nasa"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "nasa",
  "organization": {
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "shield": true,
  "state": "allocated",
  "updated_at": "2012-01-01T12:00:00Z",
  "cidr": "172.20.20.30/16",
  "data_cidr": "10.2.0.0/16",
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  }
}

Space Delete

Delete an existing space.

DELETE /spaces/{space_id_or_name}

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "nasa",
  "organization": {
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "shield": true,
  "state": "allocated",
  "updated_at": "2012-01-01T12:00:00Z",
  "cidr": "172.20.20.30/16",
  "data_cidr": "10.2.0.0/16",
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  }
}

Space Create

Create a new space.

POST /spaces

Required Parameters

Name	Type	Description	Example
name	string	unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$	"nasa"
team	string	unique name of team	"example"

Optional Parameters

Name	Type	Description	Example
cidr	string	The RFC-1918 CIDR the Private Space will use. It must be a /16 in 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16 default: "10.0.0.0/16" pattern: ^((?:10|172.(?:1[6-9]|2[0-9]|3[01])|192.168)..*.+\/16)$	"172.20.20.30/16"
data_cidr	string	The RFC-1918 CIDR that the Private Space will use for the Heroku-managed peering connection that’s automatically created when using Heroku Data add-ons. It must be between a /16 and a /20	"10.2.0.0/16"
generation	string	unique name of the generation of the Heroku platform for this space	"cedar"
log_drain_url	string	URL to which all apps will drain logs. Only settable during space creation and enables direct logging. Must use HTTPS.	"https://example.com/logs"
region	string	unique identifier or name of region	"01234567-89ab-cdef-0123-456789abcdef" or "us"
shield	boolean	true if this space has shield enabled	true

Curl Example

$ curl -n -X POST https://api.heroku.com/spaces \
  -d '{
  "name": "nasa",
  "team": "example",
  "region": "01234567-89ab-cdef-0123-456789abcdef",
  "shield": true,
  "cidr": "172.20.20.30/16",
  "data_cidr": "10.2.0.0/16",
  "log_drain_url": "https://example.com/logs",
  "generation": "cedar"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "nasa",
  "organization": {
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "shield": true,
  "state": "allocated",
  "updated_at": "2012-01-01T12:00:00Z",
  "cidr": "172.20.20.30/16",
  "data_cidr": "10.2.0.0/16",
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  }
}

Space Access

Stability: prototype

Space access represents the permissions a particular user has on a particular space.

Attributes

Name	Type	Description	Example
created_at	date-time	when space was created	"2012-01-01T12:00:00Z"
id	uuid	unique identifier of space	"01234567-89ab-cdef-0123-456789abcdef"
permissions/description	string		"example"
permissions/name	string		"example"
space:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
space:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
updated_at	date-time	when space was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"

Space Access Info

List permissions for a given user on a given space.

GET /spaces/{space_id_or_name}/members/{account_email_or_id_or_self}

Curl Example

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

Response Example

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

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

Space Access Update

Update an existing user’s set of permissions on a space.

PATCH /spaces/{space_id_or_name}/members/{account_email_or_id_or_self}

Required Parameters

Name	Type	Description	Example
permissions/name	string		"example"

Curl Example

$ curl -n -X PATCH https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/members/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
  -d '{
  "permissions": [
    {
      "name": "example"
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Space Access List

List all users and their permissions on a space.

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

GET /spaces/{space_id_or_name}/members

Curl Example

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

Response Example

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

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

Space Network Address Translation

Stability: prototype

Network address translation (NAT) for stable outbound IP addresses from a space

Attributes

Name	Type	Description	Example
created_at	date-time	when network address translation for a space was created	"2012-01-01T12:00:00Z"
sources	array	potential IPs from which outbound network traffic will originate	["123.123.123.123"]
state	string	availability of network address translation for a space one of:"disabled" or "updating" or "enabled"	"enabled"
updated_at	date-time	when network address translation for a space was updated	"2012-01-01T12:00:00Z"

Space Network Address Translation Info

Current state of network address translation for a space.

GET /spaces/{space_id_or_name}/nat

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "sources": [
    "123.123.123.123"
  ],
  "state": "enabled",
  "updated_at": "2012-01-01T12:00:00Z"
}

Space Topology

Stability: prototype

Space Topology provides you with a mechanism for viewing all the running dynos, formations and applications for a space. This is the same data thats used to power our DNS Service Discovery.

Attributes

Name	Type	Description	Example
apps/domains	array		["example.com","example.net"]
apps/formation	array	formations for application	[{"id":"01234567-89ab-cdef-0123-456789abcdef","process_type":"web","dynos":[{"id":"01234567-89ab-cdef-0123-456789abcdef","number":1,"private_ip":"10.0.134.42","hostname":"1.example-app-90210.app.localspace"}]}]
apps/id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
version	integer	version of the space topology payload	1

Space Topology Topology

Current space topology

GET /spaces/{space_id_or_name}/topology

Curl Example

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

Response Example

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

{
  "version": 1,
  "apps": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "domains": [
        "example.com",
        "example.net"
      ],
      "formation": [
        {
          "id": "01234567-89ab-cdef-0123-456789abcdef",
          "process_type": "web",
          "dynos": [
            {
              "id": "01234567-89ab-cdef-0123-456789abcdef",
              "number": 1,
              "private_ip": "10.0.134.42",
              "hostname": "1.example-app-90210.app.localspace"
            }
          ]
        }
      ]
    }
  ]
}

Space Transfer

Stability: development

Transfer spaces between enterprise teams with the same Enterprise Account.

Space Transfer transfer

Transfer space between enterprise teams

POST /spaces/{space_id_or_name}/transfer

Required Parameters

Name	Type	Description	Example
new_owner	string	unique name of team	"example"

Curl Example

$ curl -n -X POST https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/transfer \
  -d '{
  "new_owner": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "nasa",
  "organization": {
    "name": "example"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "region": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "us"
  },
  "shield": true,
  "state": "allocated",
  "updated_at": "2012-01-01T12:00:00Z",
  "cidr": "172.20.20.30/16",
  "data_cidr": "10.2.0.0/16",
  "generation": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "cedar"
  }
}

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"
default	boolean	indicates this stack is the default for new apps	true
id	uuid	identifier of stack	"01234567-89ab-cdef-0123-456789abcdef"
name	string	unique name	"heroku-18"
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 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: 4500

{
  "default": true,
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "heroku-18",
  "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 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: 4500

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

Stack List by App

List available app stacks for an app.

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

GET /apps/{app_id_or_name}/available-stacks

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/available-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: 4500

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

Team

Stability: development

Teams allow you to manage access to a shared group of applications and other resources.

Attributes

Name	Type	Description	Example
created_at	date-time	when the team was created	"2012-01-01T12:00:00Z"
credit_card_collections	boolean	whether charges incurred by the team are paid by credit card.	true
default	boolean	whether to use this team when none is specified	true
enterprise_account	nullable object		null
enterprise_account:id	uuid	unique identifier of the enterprise account	"01234567-89ab-cdef-0123-456789abcdef"
enterprise_account:name	string	unique name of the enterprise account	"example"
id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider	nullable object	Identity Provider associated with the Team	null
identity_provider:id	uuid	unique identifier of this identity provider	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:name	string	user-friendly unique identifier for this identity provider	"acme-sso"
identity_provider:owner:id	uuid	unique identifier of the owner	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:owner:name	string	name of the owner	"acme"
identity_provider:owner:type	string	type of the owner one of:"team" or "enterprise-account"	"team"
membership_limit	nullable number	upper limit of members allowed in a team.	25
name	string	unique name of team	"example"
provisioned_licenses	boolean	whether the team is provisioned licenses by salesforce.	true
role	nullable string	role in the team one of:"admin" or "collaborator" or "member" or "owner" or null	"admin"
type	string	type of team. one of:"enterprise" or "team"	"team"
updated_at	date-time	when the team was updated	"2012-01-01T12:00:00Z"

Team List

List teams in which you are a member.

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

GET /teams

Curl Example

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

Response Example

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

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "created_at": "2012-01-01T12:00:00Z",
    "credit_card_collections": true,
    "default": true,
    "enterprise_account": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "identity_provider": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-sso",
      "owner": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme",
        "type": "team"
      }
    },
    "membership_limit": 25,
    "name": "example",
    "provisioned_licenses": true,
    "role": "admin",
    "type": "team",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Team Info

Info for a team.

GET /teams/{team_name_or_id}

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_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: 4500

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "credit_card_collections": true,
  "default": true,
  "enterprise_account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-sso",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "membership_limit": 25,
  "name": "example",
  "provisioned_licenses": true,
  "role": "admin",
  "type": "team",
  "updated_at": "2012-01-01T12:00:00Z"
}

Team Update

Update team properties.

PATCH /teams/{team_name_or_id}

Optional Parameters

Name	Type	Description	Example
default	boolean	whether to use this team when none is specified	true
name	string	unique name of team	"example"

Curl Example

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

Response Example

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

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "credit_card_collections": true,
  "default": true,
  "enterprise_account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-sso",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "membership_limit": 25,
  "name": "example",
  "provisioned_licenses": true,
  "role": "admin",
  "type": "team",
  "updated_at": "2012-01-01T12:00:00Z"
}

Team Create

Create a new team.

POST /teams

Required Parameters

Name	Type	Description	Example
name	string	unique name of team	"example"

Optional Parameters

Name	Type	Description	Example
address_1	string	street address line 1	"40 Hickory Lane"
address_2	nullable string	street address line 2	"Suite 103"
card_number	nullable string	encrypted card number of payment method	"encrypted-card-number"
city	string	city	"San Francisco"
country	string	country	"US"
cvv	nullable string	card verification value	"123"
device_data	nullable string	Device data string generated by the client	"VGhpcyBpcyBhIGdvb2QgZGF5IHRvIGRpZQ=="
expiration_month	nullable string	expiration month	"11"
expiration_year	nullable string	expiration year	"2014"
first_name	string	the first name for payment method	"Jason"
last_name	string	the last name for payment method	"Walker"
nonce	nullable string	Nonce generated by Braintree hosted fields form	"VGhpcyBpcyBhIGdvb2QgZGF5IHRvIGRpZQ=="
other	nullable string	metadata	"Additional information for payment method"
postal_code	string	postal code	"90210"
state	string	state	"CA"

Curl Example

$ curl -n -X POST https://api.heroku.com/teams \
  -d '{
  "name": "example",
  "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",
  "nonce": "VGhpcyBpcyBhIGdvb2QgZGF5IHRvIGRpZQ==",
  "device_data": "VGhpcyBpcyBhIGdvb2QgZGF5IHRvIGRpZQ=="
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "credit_card_collections": true,
  "default": true,
  "enterprise_account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-sso",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "membership_limit": 25,
  "name": "example",
  "provisioned_licenses": true,
  "role": "admin",
  "type": "team",
  "updated_at": "2012-01-01T12:00:00Z"
}

Team Delete

Delete an existing team.

DELETE /teams/{team_name_or_id}

Curl Example

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

Response Example

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

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "credit_card_collections": true,
  "default": true,
  "enterprise_account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-sso",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "membership_limit": 25,
  "name": "example",
  "provisioned_licenses": true,
  "role": "admin",
  "type": "team",
  "updated_at": "2012-01-01T12:00:00Z"
}

Team List by Enterprise Account

List teams for an enterprise account.

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

GET /enterprise-accounts/{enterprise_account_id_or_name}/teams

Curl Example

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

Response Example

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

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "created_at": "2012-01-01T12:00:00Z",
    "credit_card_collections": true,
    "default": true,
    "enterprise_account": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "identity_provider": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-sso",
      "owner": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme",
        "type": "team"
      }
    },
    "membership_limit": 25,
    "name": "example",
    "provisioned_licenses": true,
    "role": "admin",
    "type": "team",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Team Create in Enterprise Account

Create a team in an enterprise account.

POST /enterprise-accounts/{enterprise_account_id_or_name}/teams

Required Parameters

Name	Type	Description	Example
name	string	unique name of team	"example"

Curl Example

$ curl -n -X POST https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/teams \
  -d '{
  "name": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2012-01-01T12:00:00Z",
  "credit_card_collections": true,
  "default": true,
  "enterprise_account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-sso",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "membership_limit": 25,
  "name": "example",
  "provisioned_licenses": true,
  "role": "admin",
  "type": "team",
  "updated_at": "2012-01-01T12:00:00Z"
}

Team Add-on

Stability: production

Team Add-on List For Team

List add-ons used across all Team apps

GET /teams/{team_name_or_id}/addons

Curl Example

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

Response Example

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

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

Team App

Stability: development

A team app encapsulates the team specific functionality of Heroku apps.

Attributes

Name	Type	Description	Example
archived_at	nullable date-time	when app was archived	"2012-01-01T12:00:00Z"
build_stack:id	uuid	identifier of stack	"01234567-89ab-cdef-0123-456789abcdef"
build_stack:name	string	unique name	"heroku-18"
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 pattern: ^https://git.heroku.com/[a-z][a-z0-9-]{2,29}.git$	"https://git.heroku.com/example.git"
id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
internal_routing	nullable boolean	describes whether a Private Spaces app is externally routable or not	false
joined	boolean	is the current member a collaborator on this app.	false
locked	boolean	are other team members forbidden from joining this app.	false
maintenance	boolean	maintenance status of app	false
name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
owner	nullable object	identity of app owner	null
owner:email	email	unique email address	"username@example.com"
owner:id	uuid	identifier of an account	"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
space	nullable object	identity of space	null
space:id	uuid	unique identifier of space	"01234567-89ab-cdef-0123-456789abcdef"
space:name	string	unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$	"nasa"
stack:id	uuid	identifier of stack	"01234567-89ab-cdef-0123-456789abcdef"
stack:name	string	unique name	"heroku-18"
team	nullable object	team that owns this app	null
team:name	string	unique name of team	"example"
updated_at	date-time	when app was updated	"2012-01-01T12:00:00Z"
web_url	nullable uri	web URL of app pattern: ^https?://[a-z][a-z0-9-]{3,43}.herokuapp.com/$	"https://example.herokuapp.com/"

Team App Create

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

POST /teams/apps

Optional Parameters

Name	Type	Description	Example
internal_routing	nullable boolean	describes whether a Private Spaces app is externally routable or not	false
locked	boolean	are other team members forbidden from joining this app.	false
name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"example"
personal	boolean	force creation of the app in the user account even if a default team is set.	false
region	string	name of region	"us"
space	string	unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$	"nasa"
stack	string	unique name	"heroku-18"
team	string	unique name of team	"example"

Curl Example

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

Response Example

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

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

Team App Info

Info for a team app.

GET /teams/apps/{team_app_name}

Curl Example

$ curl -n https://api.heroku.com/teams/apps/$TEAM_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: 4500

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

Team App Update Locked

Lock or unlock a team app.

PATCH /teams/apps/{team_app_name}

Required Parameters

Name	Type	Description	Example
locked	boolean	are other team members forbidden from joining this app.	false

Curl Example

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

Response Example

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

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

Team App Transfer to Account

Transfer an existing team app to another Heroku account.

PATCH /teams/apps/{team_app_name}

Required Parameters

Name	Type	Description	Example
owner	string	unique email address, identifier of an account or Implicit reference to currently authorized user	"username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" or "~"

Curl Example

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

Response Example

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

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

Team App Transfer to Team

Transfer an existing team app to another team.

PATCH /teams/apps/{team_app_name}

Required Parameters

Name	Type	Description	Example
owner	string	unique name of team	"example"

Curl Example

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

Response Example

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

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

Team App List By Team

List team apps.

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

GET /teams/{team_name_or_id}/apps

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/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: 4500

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

Team App Collaborator

Stability: development

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

Attributes

Name	Type	Description	Example
app:id	uuid	unique identifier	"01234567-89ab-cdef-0123-456789abcdef"
app:name	string	name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$	"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"
permissions	array	array of permissions for the collaborator (only applicable if the app is on a team)	[{"name":"view","description":"Can manage config, deploy, run commands and restart the app."}]
role	nullable string	role in the team one of:"admin" or "collaborator" or "member" or "owner" or null	"admin"
updated_at	date-time	when collaborator was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:federated	boolean	whether the user is federated and belongs to an Identity Provider	false
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"

Team App Collaborator Create

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

POST /teams/apps/{app_id_or_name}/collaborators

Required Parameters

Name	Type	Description	Example
user	string	unique email address, identifier of an account or Implicit reference to currently authorized user	"username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" or "~"

Optional Parameters

Name	Type	Description	Example
permissions	array	An array of permissions to give to the collaborator.	["view"]
silent	boolean	whether to suppress email invitation when creating collaborator	false

Curl Example

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

Response Example

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

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

Team App Collaborator Delete

Delete an existing collaborator from a team app.

DELETE /teams/apps/{team_app_name}/collaborators/{team_app_collaborator_email}

Curl Example

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

Response Example

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

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

Team App Collaborator Info

Info for a collaborator on a team app.

GET /teams/apps/{team_app_name}/collaborators/{team_app_collaborator_email}

Curl Example

$ curl -n https://api.heroku.com/teams/apps/$TEAM_APP_NAME/collaborators/$TEAM_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: 4500

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

Team App Collaborator Update

Update an existing collaborator from a team app.

PATCH /teams/apps/{team_app_name}/collaborators/{team_app_collaborator_email}

Required Parameters

Name	Type	Description	Example
permissions	array	An array of permissions to give to the collaborator.	["view"]

Curl Example

$ curl -n -X PATCH https://api.heroku.com/teams/apps/$TEAM_APP_NAME/collaborators/$TEAM_APP_COLLABORATOR_EMAIL \
  -d '{
  "permissions": [
    "view"
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

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

Team App Collaborator List

List collaborators on a team app.

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

GET /teams/apps/{team_app_name}/collaborators

Curl Example

$ curl -n https://api.heroku.com/teams/apps/$TEAM_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: 4500

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

Team App Permission

Stability: prototype

A team app permission is a behavior that is assigned to a user in a team app.

Attributes

Name	Type	Description	Example
description	string	A description of what the app permission allows.	"Can manage config, deploy, run commands and restart the app."
name	string	The name of the app permission.	"view"

Team App Permission List

Lists permissions available to teams.

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

GET /teams/permissions

Curl Example

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

Response Example

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

[
  {
    "name": "view",
    "description": "Can manage config, deploy, run commands and restart the app."
  }
]

Team Daily Usage

Stability: development

Usage for an enterprise team at a daily resolution.

Attributes

Name	Type	Description	Example
addons	number	total add-on credits used	250.0
apps	array	app usage in the team	[{"addons":250.0,"app_name":"example","data":34.89,"dynos":1.548,"partner":12.34}]
data	number	total add-on credits used for first party add-ons	34.89
date	date	date of the usage	"2019-01-01"
dynos	number	dynos used	1.548
id	uuid	team identifier	"01234567-89ab-cdef-0123-456789abcdef"
name	string	name of the team	"ops"
partner	number	total add-on credits used for third party add-ons	12.34
space	number	space credits used	1.548

Team Daily Usage Info

Retrieves usage for an enterprise team for a range of days. Start and end dates can be specified as query parameters using the date format YYYY-MM-DD. The team identifier can be found from the team list endpoint.

GET /teams/{team_id}/usage/daily

Required Parameters

Name	Type	Description	Example
start	string	range start date pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$	"2019-01-25"

Optional Parameters

Name	Type	Description	Example
end	string	range end date pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$	"2019-02-25"

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_ID/usage/daily \
 -G \
  -d start=2019-01-25 \
  -d end=2019-02-25 \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

[
  {
    "addons": 250.0,
    "apps": [
      {
        "addons": 250.0,
        "app_name": "example",
        "data": 34.89,
        "dynos": 1.548,
        "partner": 12.34
      }
    ],
    "data": 34.89,
    "date": "2019-01-01",
    "dynos": 1.548,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "ops",
    "partner": 12.34,
    "space": 1.548
  }
]

Team Delinquency

Stability: development

A Heroku team becomes delinquent due to non-payment. We suspend and delete delinquent teams if their invoices remain unpaid.

Attributes

Name	Type	Description	Example
scheduled_deletion_time	nullable date-time	scheduled time of when we will delete your team due to delinquency	"2024-01-01T12:00:00Z"
scheduled_suspension_time	nullable date-time	scheduled time of when we will suspend your team due to delinquency	"2024-01-01T12:00:00Z"

Team Delinquency Info

Team delinquency information.

GET /teams/{team_name_or_id}/delinquency

Curl Example

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

Response Example

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

{
  "scheduled_suspension_time": "2024-01-01T12:00:00Z",
  "scheduled_deletion_time": "2024-01-01T12:00:00Z"
}

Team Feature

Stability: development

A team feature represents a feature enabled on a team account.

Attributes

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

Team Feature Info

Info for an existing team feature.

GET /teams/{team_name_or_id}/features/{team_feature_id_or_name}

Curl Example

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

Response Example

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

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

Team Feature List

List existing team features.

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

GET /teams/{team_name_or_id}/features

Curl Example

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

Response Example

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

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

Team Invitation

Stability: development

A team invitation represents an invite to a team.

Attributes

Name	Type	Description	Example
created_at	date-time	when invitation was created	"2012-01-01T12:00:00Z"
id	uuid	unique identifier of an invitation	"01234567-89ab-cdef-0123-456789abcdef"
invited_by:email	email	unique email address	"username@example.com"
invited_by:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
invited_by:name	nullable string	full name of the account owner	"Tina Edmonds"
role	nullable string	role in the team one of:"admin" or "collaborator" or "member" or "owner" or null	"admin"
team:id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
team:name	string	unique name of team	"example"
updated_at	date-time	when invitation was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
user:name	nullable string	full name of the account owner	"Tina Edmonds"

Team Invitation List

Get a list of a team’s Identity Providers

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

GET /teams/{team_name}/invitations

Curl Example

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

Response Example

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

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

Team Invitation Create

Create Team Invitation

PUT /teams/{team_name_or_id}/invitations

Required Parameters

Name	Type	Description	Example
email	email	unique email address	"username@example.com"
role	nullable string	role in the team one of:"admin" or "collaborator" or "member" or "owner" or null	"admin"

Curl Example

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

Response Example

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

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

Team Invitation Revoke

Revoke a team invitation.

DELETE /teams/{team_name_or_id}/invitations/{team_invitation_id}

Curl Example

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

Response Example

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

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

Team Invitation Get

Get an invitation by its token

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

GET /teams/invitations/{team_invitation_token}

Curl Example

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

Response Example

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

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

Team Invitation Accept

Accept Team Invitation

POST /teams/invitations/{team_invitation_token}/accept

Curl Example

$ curl -n -X POST https://api.heroku.com/teams/invitations/$TEAM_INVITATION_TOKEN/accept \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "email": "someone@example.org",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "redacted": false,
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "role": "admin",
  "two_factor_authentication": true,
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  }
}

Team Invoice

Stability: development

A Team Invoice is an itemized bill of goods for a team which includes pricing and charges.

Attributes

Name	Type	Description	Example
addons_total	integer	total add-ons charges in on this invoice	25000
charges_total	integer	total charges on this invoice	0
created_at	date-time	when invoice was created	"2012-01-01T12:00:00Z"
credits_total	integer	total credits on this invoice	100000
database_total	integer	total database charges on this invoice	25000
dyno_units	number	total amount of dyno units consumed across dyno types.	1.92
id	uuid	unique identifier of this invoice	"01234567-89ab-cdef-0123-456789abcdef"
number	integer	human readable invoice number	9403943
payment_status	string	status of the invoice payment	"Paid"
period_end	string	the ending date that the invoice covers	"01/31/2014"
period_start	string	the starting date that this invoice covers	"01/01/2014"
platform_total	integer	total platform charges on this invoice	50000
state	integer	payment status for this invoice (pending, successful, failed)	1
total	integer	combined total of charges and credits on this invoice	100000
updated_at	date-time	when invoice was updated	"2012-01-01T12:00:00Z"
weighted_dyno_hours	number	The total amount of hours consumed across dyno types.	1488

Team Invoice Info

Info for existing invoice.

GET /teams/{team_name_or_id}/invoices/{team_invoice_number}

Curl Example

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

Response Example

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

{
  "addons_total": 25000,
  "database_total": 25000,
  "charges_total": 0,
  "created_at": "2012-01-01T12:00:00Z",
  "credits_total": 100000,
  "dyno_units": 1.92,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "number": 9403943,
  "payment_status": "Paid",
  "period_end": "01/31/2014",
  "period_start": "01/01/2014",
  "platform_total": 50000,
  "state": 1,
  "total": 100000,
  "updated_at": "2012-01-01T12:00:00Z",
  "weighted_dyno_hours": 1488
}

Team Invoice List

List existing invoices.

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

GET /teams/{team_name_or_id}/invoices

Curl Example

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

Response Example

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

[
  {
    "addons_total": 25000,
    "database_total": 25000,
    "charges_total": 0,
    "created_at": "2012-01-01T12:00:00Z",
    "credits_total": 100000,
    "dyno_units": 1.92,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "number": 9403943,
    "payment_status": "Paid",
    "period_end": "01/31/2014",
    "period_start": "01/01/2014",
    "platform_total": 50000,
    "state": 1,
    "total": 100000,
    "updated_at": "2012-01-01T12:00:00Z",
    "weighted_dyno_hours": 1488
  }
]

Team Member

Stability: development

A team member is an individual with access to a team.

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 team member	"someone@example.org"
federated	boolean	whether the user is federated and belongs to an Identity Provider	false
id	uuid	unique identifier of the team member	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider	nullable object	Identity Provider information the member is federated with	null
identity_provider:id	uuid	unique identifier of this identity provider	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:name	string	name of the identity provider	"acme"
identity_provider:owner:id	uuid	unique identifier of the owner	"01234567-89ab-cdef-0123-456789abcdef"
identity_provider:owner:name	string	name of the owner	"acme"
identity_provider:owner:type	string	type of the owner one of:"team" or "enterprise-account"	"team"
identity_provider:redacted	boolean	whether the identity_provider information is redacted or not	false
role	nullable string	role in the team one of:"admin" or "collaborator" or "member" or "owner" or null	"admin"
two_factor_authentication	boolean	whether the team member has two factor authentication enabled	true
updated_at	date-time	when the membership record was updated	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
user:name	nullable string	full name of the account owner	"Tina Edmonds"

Team Member Create or Update

Create a new team member, or update their role.

PUT /teams/{team_name_or_id}/members

Required Parameters

Name	Type	Description	Example
email	string	email address of the team member	"someone@example.org"
role	string	role in the team one of:"admin" or "viewer" or "member"	"admin"

Optional Parameters

Name	Type	Description	Example
federated	boolean	whether the user is federated and belongs to an Identity Provider	false

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "email": "someone@example.org",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "redacted": false,
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "role": "admin",
  "two_factor_authentication": true,
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  }
}

Team Member Create

Create a new team member.

POST /teams/{team_name_or_id}/members

Required Parameters

Name	Type	Description	Example
email	string	email address of the team member	"someone@example.org"
role	string	role in the team one of:"admin" or "viewer" or "member"	"admin"

Optional Parameters

Name	Type	Description	Example
federated	boolean	whether the user is federated and belongs to an Identity Provider	false

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "email": "someone@example.org",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "redacted": false,
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "role": "admin",
  "two_factor_authentication": true,
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  }
}

Team Member Update

Update a team member.

PATCH /teams/{team_name_or_id}/members

Required Parameters

Name	Type	Description	Example
email	string	email address of the team member	"someone@example.org"
role	string	role in the team one of:"admin" or "viewer" or "member"	"admin"

Optional Parameters

Name	Type	Description	Example
federated	boolean	whether the user is federated and belongs to an Identity Provider	false

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "email": "someone@example.org",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "redacted": false,
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "role": "admin",
  "two_factor_authentication": true,
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  }
}

Team Member Delete

Remove a member from the team.

DELETE /teams/{team_name_or_id}/members/{team_member_email_or_id}

Curl Example

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

Response Example

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

{
  "created_at": "2012-01-01T12:00:00Z",
  "email": "someone@example.org",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "identity_provider": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme",
    "redacted": false,
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "type": "team"
    }
  },
  "role": "admin",
  "two_factor_authentication": true,
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  }
}

Team Member List

List members of the team.

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

GET /teams/{team_name_or_id}/members

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/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: 4500

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "email": "someone@example.org",
    "federated": false,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "identity_provider": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme",
      "redacted": false,
      "owner": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme",
        "type": "team"
      }
    },
    "role": "admin",
    "two_factor_authentication": true,
    "updated_at": "2012-01-01T12:00:00Z",
    "user": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Tina Edmonds"
    }
  }
]

Team Member List By Member

List the apps of a team member.

Acceptable order values for the Range header are email or id.

GET /teams/{team_name_or_id}/members/{team_member_email_or_id}/apps

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/members/$TEAM_MEMBER_EMAIL_OR_ID/apps \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: email, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "archived_at": "2012-01-01T12:00:00Z",
    "buildpack_provided_description": "Ruby/Rack",
    "build_stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-18"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "git_url": "https://git.heroku.com/example.git",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "internal_routing": false,
    "joined": false,
    "locked": false,
    "maintenance": false,
    "name": "example",
    "team": {
      "name": "example"
    },
    "owner": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "region": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "us"
    },
    "released_at": "2012-01-01T12:00:00Z",
    "repo_size": 0,
    "slug_size": 0,
    "space": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "nasa"
    },
    "stack": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "heroku-18"
    },
    "updated_at": "2012-01-01T12:00:00Z",
    "web_url": "https://example.herokuapp.com/"
  }
]

Team Monthly Usage

Stability: development

Usage for an enterprise team at a monthly resolution.

Attributes

Name	Type	Description	Example
addons	number	total add-on credits used	250.0
apps	array	app usage in the team	[{"addons":250.0,"app_name":"example","data":34.89,"dynos":1.548,"partner":12.34}]
connect	number	max connect rows synced	15000
data	number	total add-on credits used for first party add-ons	34.89
dynos	number	dynos used	1.548
id	uuid	team identifier	"01234567-89ab-cdef-0123-456789abcdef"
month	string	year and month of the usage pattern: ^[0-9]{4}-[0-9]{2}$	"2019-01"
name	string	name of the team	"ops"
partner	number	total add-on credits used for third party add-ons	12.34
space	number	space credits used	1.548

Team Monthly Usage Info

Retrieves usage for an enterprise team for a range of months. Start and end dates can be specified as query parameters using the date, YYYY-MM. If no end date is specified, one month of usage is returned. The team identifier can be found from the team list endpoint.

GET /teams/{team_id}/usage/monthly

Required Parameters

Name	Type	Description	Example
start	string	range start date pattern: ^[0-9]{4}-[0-9]{2}$	"2019-01"

Optional Parameters

Name	Type	Description	Example
end	string	range end date pattern: ^[0-9]{4}-[0-9]{2}$	"2019-02"

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_ID/usage/monthly \
 -G \
  -d start=2019-01 \
  -d end=2019-02 \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "addons": 250.0,
    "apps": [
      {
        "addons": 250.0,
        "app_name": "example",
        "data": 34.89,
        "dynos": 1.548,
        "partner": 12.34
      }
    ],
    "connect": 15000,
    "data": 34.89,
    "dynos": 1.548,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "month": "2019-01",
    "name": "ops",
    "partner": 12.34,
    "space": 1.548
  }
]

Team Preferences

Stability: development

Tracks a Team’s Preferences

Attributes

Name	Type	Description	Example
addons-controls	nullable boolean	Whether add-on service rules should be applied to add-on installations	true
default-permission	nullable string	The default permission used when adding new members to the team one of:"admin" or "member" or "viewer" or null	"member"

Team Preferences List

Retrieve Team Preferences

GET /teams/{team_preferences_name_or_id}/preferences

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_PREFERENCES_NAME_OR_ID/preferences \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "default-permission": "member",
  "addons-controls": true
}

Team Preferences Update

Update Team Preferences

PATCH /teams/{team_preferences_name_or_id}/preferences

Optional Parameters

Name	Type	Description	Example
addons-controls	nullable boolean	Whether add-on service rules should be applied to add-on installations	true

Curl Example

$ curl -n -X PATCH https://api.heroku.com/teams/$TEAM_PREFERENCES_NAME_OR_ID/preferences \
  -d '{
  "addons-controls": true
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "default-permission": "member",
  "addons-controls": true
}

Team Space

Stability: prototype

A space is an isolated, highly available, secure app execution environment.

Team Space List

List spaces owned by the team

GET /teams/{team_name_or_id}/spaces

Curl Example

$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/spaces \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "nasa",
    "organization": {
      "name": "example"
    },
    "team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "region": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "us"
    },
    "shield": true,
    "state": "allocated",
    "updated_at": "2012-01-01T12:00:00Z",
    "cidr": "172.20.20.30/16",
    "data_cidr": "10.2.0.0/16",
    "generation": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "cedar"
    }
  }
]

Telemetry Drain

Stability: prototype

A telemetry drain forwards OpenTelemetry traces, metrics, and logs to your own consumer. For Fir-generation apps only.

Attributes

Name	Type	Description	Example
created_at	date-time	when the telemetry drain was created	"2024-12-01T12:00:00Z"
exporter:endpoint	string	URI of your OpenTelemetry consumer Length: 0..1000	"https://api.otelproduct.example/consumer"
exporter:headers	object	JSON headers to send to your OpenTelemetry consumer default: {}	{"API-Key":"example_api_key_012345","Environment":"production"}
exporter:type	string	the transport type to be used for your OpenTelemetry consumer one of:"otlphttp" or "otlp"	"otlphttp"
id	uuid	unique identifier of telemetry drain	"01234567-89ab-cdef-0123-456789abcdef"
owner:id	uuid	unique identifier of owner	"01234567-89ab-cdef-0123-456789abcdef"
owner:type	string	type of owner one of:"app" or "space"	"app"
signals	array	OpenTelemetry signals to send to telemetry drain	["traces","metrics"]
updated_at	date-time	when telemetry drain was last updated	"2012-01-01T12:00:00Z"

Telemetry Drain Create

Create a telemetry drain.

POST /telemetry-drains

Required Parameters

Name	Type	Description	Example
exporter:endpoint	string	URI of your OpenTelemetry consumer Length: 0..1000	"https://api.otelproduct.example/consumer"
exporter:headers	object	JSON headers to send to your OpenTelemetry consumer default: {}	{"API-Key":"example_api_key_012345","Environment":"production"}
exporter:type	string	the transport type to be used for your OpenTelemetry consumer one of:"otlphttp" or "otlp"	"otlphttp"
owner:id	uuid	unique identifier of owner	"01234567-89ab-cdef-0123-456789abcdef"
owner:type	string	type of owner one of:"app" or "space"	"app"
signals	array	OpenTelemetry signals to send to telemetry drain	["traces","metrics"]

Curl Example

$ curl -n -X POST https://api.heroku.com/telemetry-drains \
  -d '{
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "app"
  },
  "signals": [
    "traces",
    "metrics"
  ],
  "exporter": {
    "type": "otlphttp",
    "endpoint": "https://api.otelproduct.example/consumer",
    "headers": {
      "API-Key": "example_api_key_012345",
      "Environment": "production"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2024-12-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "app"
  },
  "signals": [
    "traces",
    "metrics"
  ],
  "exporter": {
    "type": "otlphttp",
    "endpoint": "https://api.otelproduct.example/consumer",
    "headers": {
      "API-Key": "example_api_key_012345",
      "Environment": "production"
    }
  },
  "updated_at": "2012-01-01T12:00:00Z"
}

Telemetry Drain List by App

List telemetry drains for an app.

The only acceptable order value for the Range header is id.

GET /apps/{app_id_or_name}/telemetry-drains

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/telemetry-drains \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2024-12-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "app"
    },
    "signals": [
      "traces",
      "metrics"
    ],
    "exporter": {
      "type": "otlphttp",
      "endpoint": "https://api.otelproduct.example/consumer",
      "headers": {
        "API-Key": "example_api_key_012345",
        "Environment": "production"
      }
    },
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Telemetry Drain List by Space

List telemetry drains for a space.

The only acceptable order value for the Range header is id.

GET /spaces/{space_id_or_name}/telemetry-drains

Curl Example

$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/telemetry-drains \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2024-12-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "owner": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "app"
    },
    "signals": [
      "traces",
      "metrics"
    ],
    "exporter": {
      "type": "otlphttp",
      "endpoint": "https://api.otelproduct.example/consumer",
      "headers": {
        "API-Key": "example_api_key_012345",
        "Environment": "production"
      }
    },
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Telemetry Drain Update

Update a telemetry drain.

PATCH /telemetry-drains/{telemetry_drain_id}

Optional Parameters

Name	Type	Description	Example
exporter:endpoint	string	URI of your OpenTelemetry consumer Length: 0..1000	"https://api.otelproduct.example/consumer"
exporter:headers	object	JSON headers to send to your OpenTelemetry consumer default: {}	{"API-Key":"example_api_key_012345","Environment":"production"}
exporter:type	string	the transport type to be used for your OpenTelemetry consumer one of:"otlphttp" or "otlp"	"otlphttp"
signals	array	OpenTelemetry signals to send to telemetry drain	["traces","metrics"]

Curl Example

$ curl -n -X PATCH https://api.heroku.com/telemetry-drains/$TELEMETRY_DRAIN_ID \
  -d '{
  "signals": [
    "traces",
    "metrics"
  ],
  "exporter": {
    "type": "otlphttp",
    "endpoint": "https://api.otelproduct.example/consumer",
    "headers": {
      "API-Key": "example_api_key_012345",
      "Environment": "production"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2024-12-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "app"
  },
  "signals": [
    "traces",
    "metrics"
  ],
  "exporter": {
    "type": "otlphttp",
    "endpoint": "https://api.otelproduct.example/consumer",
    "headers": {
      "API-Key": "example_api_key_012345",
      "Environment": "production"
    }
  },
  "updated_at": "2012-01-01T12:00:00Z"
}

Telemetry Drain Delete

Delete a telemetry drain.

DELETE /telemetry-drains/{telemetry_drain_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/telemetry-drains/$TELEMETRY_DRAIN_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2024-12-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "app"
  },
  "signals": [
    "traces",
    "metrics"
  ],
  "exporter": {
    "type": "otlphttp",
    "endpoint": "https://api.otelproduct.example/consumer",
    "headers": {
      "API-Key": "example_api_key_012345",
      "Environment": "production"
    }
  },
  "updated_at": "2012-01-01T12:00:00Z"
}

Telemetry Drain Info

Info for a telemetry drain.

GET /telemetry-drains/{telemetry_drain_id}

Curl Example

$ curl -n https://api.heroku.com/telemetry-drains/$TELEMETRY_DRAIN_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "created_at": "2024-12-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "app"
  },
  "signals": [
    "traces",
    "metrics"
  ],
  "exporter": {
    "type": "otlphttp",
    "endpoint": "https://api.otelproduct.example/consumer",
    "headers": {
      "API-Key": "example_api_key_012345",
      "Environment": "production"
    }
  },
  "updated_at": "2012-01-01T12:00:00Z"
}

Test Case

Stability: prototype

A single test case belonging to a test run

Attributes

Name	Type	Description	Example
created_at	date-time	when test case was created	"2015-01-01T12:00:00Z"
description	string	description of the test case	"example"
diagnostic	string	meta information about the test case	"example"
directive	string	special note about the test case e.g. skipped, todo	"example"
id	uuid	unique identifier of a test case	"01234567-89ab-cdef-0123-456789abcdef"
number	integer	the test number	42
passed	boolean	whether the test case was successful	true
test_node:id	string	unique identifier of a test node	"01234567-89ab-cdef-0123-456789abcdef"
test_run:id	string	unique identifier of a test run
updated_at	date-time	when test case was updated	"2015-01-01T12:00:00Z"

Test Case List

List test cases

The only acceptable order value for the Range header is id.

GET /test-runs/{test_run_id}/test-cases

Curl Example

$ curl -n https://api.heroku.com/test-runs/$TEST_RUN_ID/test-cases \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "created_at": "2015-01-01T12:00:00Z",
    "updated_at": "2015-01-01T12:00:00Z",
    "description": "example",
    "diagnostic": "example",
    "directive": "example",
    "passed": true,
    "number": 42,
    "test_node": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "test_run": {
      "id": null
    }
  }
]

Test Node

Stability: prototype

A single test node belonging to a test run

Attributes

Name	Type	Description	Example
created_at	date-time	when test node was created	"2015-01-01T12:00:00Z"
dyno	nullable object	the dyno which belongs to this test node	null
dyno:attach_url	nullable string	a URL to stream output from for debug runs or null for non-debug runs	"rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}"
dyno:id	string	unique identifier or the name of this process on this dyno	"01234567-89ab-cdef-0123-456789abcdef" or "run.1"
error_status	nullable string	the status of the test run when the error occured	null
exit_code	nullable integer	the exit code of the test script	null
id	string	unique identifier of a test node	"01234567-89ab-cdef-0123-456789abcdef"
index	integer	The index of the test node	42
message	nullable string	human friendly message indicating reason for an error	null
output_stream_url	string	the streaming output for the test node	"https://example.com/output.log"
pipeline:id	string	unique identifier or name of pipeline	"01234567-89ab-cdef-0123-456789abcdef" or "example"
setup_stream_url	string	the streaming test setup output for the test node	"https://example.com/test-setup.log"
status	string	current state of the test run one of:"pending" or "cancelled" or "creating" or "building" or "running" or "succeeded" or "failed" or "errored" or "debugging"	"pending"
test_run:id	string	unique identifier of a test run
updated_at	date-time	when test node was updated	"2015-01-01T12:00:00Z"

Test Node List

List test nodes

The only acceptable order value for the Range header is id.

GET /test-runs/{test_run_id}/test-nodes

Curl Example

$ curl -n https://api.heroku.com/test-runs/$TEST_RUN_ID/test-nodes \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "dyno": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}"
    },
    "error_status": "example",
    "exit_code": 42,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "index": 42,
    "message": "example",
    "output_stream_url": "https://example.com/output.log",
    "pipeline": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "setup_stream_url": "https://example.com/test-setup.log",
    "status": "pending",
    "updated_at": "2015-01-01T12:00:00Z",
    "test_run": {
      "id": null
    }
  }
]

Test Run

Stability: prototype

An execution or trial of one or more tests

Attributes

Name	Type	Description	Example
actor_email	email	the email of the actor triggering the test run	"username@example.com"
app_setup	nullable object	the app setup for the test run	null
clear_cache	nullable boolean	whether the test was run with an empty cache	null
commit_branch	string	the branch of the repository that the test run concerns	"example"
commit_message	string	the message for the commit under test	"example"
commit_sha	string	the SHA hash of the commit under test	"example"
created_at	date-time	when test run was created	"2015-01-01T12:00:00Z"
debug	boolean	whether the test run was started for interactive debugging	true
dyno	nullable object	the type of dynos used for this test-run	null
dyno:size	string	dyno size	"standard-1X"
id	uuid	unique identifier of a test run	"01234567-89ab-cdef-0123-456789abcdef"
message	nullable string	human friendly message indicating reason for an error	null
number	integer	the auto incrementing test run number	42
organization	nullable object	the team that owns this test-run	null
organization:name	string	unique name of team	"example"
pipeline:id	string	unique identifier or name of pipeline	"01234567-89ab-cdef-0123-456789abcdef" or "example"
source_blob_url	string	The download location for the source code to be tested	"example"
status	string	current state of the test run one of:"pending" or "cancelled" or "creating" or "building" or "running" or "succeeded" or "failed" or "errored" or "debugging"	"pending"
updated_at	date-time	when test-run was updated	"2015-01-01T12:00:00Z"
user:allow_tracking	boolean	whether to allow third party web activity tracking default: true	true
user:beta	boolean	whether allowed to utilize beta Heroku features	false
user:country_of_residence	nullable string	country where account owner resides	"United States"
user:created_at	date-time	when account was created	"2012-01-01T12:00:00Z"
user:default_organization	nullable object	team selected by default	null
user:default_organization:id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
user:default_organization:name	string	unique name of team	"example"
user:default_team	nullable object	team selected by default	null
user:default_team:id	uuid	unique identifier of team	"01234567-89ab-cdef-0123-456789abcdef"
user:default_team:name	string	unique name of team	"example"
user:delinquent_at	nullable date-time	when account became delinquent	"2012-01-01T12:00:00Z"
user:email	email	unique email address	"username@example.com"
user:federated	boolean	whether the user is federated and belongs to an Identity Provider	false
user:id	uuid	identifier of an account	"01234567-89ab-cdef-0123-456789abcdef"
user:identity_provider	nullable object	Identity Provider details for federated users.	null
user:identity_provider:id	uuid	unique identifier of this identity provider	"01234567-89ab-cdef-0123-456789abcdef"
user:identity_provider:name	string	user-friendly unique identifier for this identity provider	"acme-sso"
user:identity_provider:organization:name	string	unique name of team	"example"
user:identity_provider:owner:id	uuid	unique identifier of the owner	"01234567-89ab-cdef-0123-456789abcdef"
user:identity_provider:owner:name	string	name of the owner	"acme"
user:identity_provider:owner:type	string	type of the owner one of:"team" or "enterprise-account"	"team"
user:identity_provider:team:name	string	unique name of team	"example"
user:last_login	nullable date-time	when account last authorized with Heroku	"2012-01-01T12:00:00Z"
user:name	nullable string	full name of the account owner	"Tina Edmonds"
user:sms_number	nullable string	SMS number of account	"+1 ***-***-1234"
user:suspended_at	nullable date-time	when account was suspended	"2012-01-01T12:00:00Z"
user:two_factor_authentication	boolean	whether two-factor auth is enabled on the account	false
user:updated_at	date-time	when account was updated	"2012-01-01T12:00:00Z"
user:verified	boolean	whether account has been verified with billing information	false
warning_message	nullable string	human friently warning emitted during the test run	null

Test Run Create

Create a new test-run.

POST /test-runs

Required Parameters

Name	Type	Description	Example
commit_branch	string	the branch of the repository that the test run concerns	"example"
commit_message	string	the message for the commit under test	"example"
commit_sha	string	the SHA hash of the commit under test	"example"
pipeline	string	unique identifier or name of pipeline	"01234567-89ab-cdef-0123-456789abcdef" or "example"
source_blob_url	string	The download location for the source code to be tested	"example"

Optional Parameters

Name	Type	Description	Example
debug	boolean	whether the test run was started for interactive debugging	true
organization	string	unique name or identifier of team	"example" or "01234567-89ab-cdef-0123-456789abcdef"

Curl Example

$ curl -n -X POST https://api.heroku.com/test-runs \
  -d '{
  "commit_branch": "example",
  "commit_message": "example",
  "commit_sha": "example",
  "debug": true,
  "organization": "01234567-89ab-cdef-0123-456789abcdef",
  "pipeline": "01234567-89ab-cdef-0123-456789abcdef",
  "source_blob_url": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actor_email": "username@example.com",
  "clear_cache": true,
  "commit_branch": "example",
  "commit_message": "example",
  "commit_sha": "example",
  "debug": true,
  "app_setup": null,
  "created_at": "2015-01-01T12:00:00Z",
  "dyno": {
    "size": "standard-1X"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "message": "example",
  "number": 42,
  "organization": {
    "name": "example"
  },
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "status": "pending",
  "source_blob_url": "example",
  "updated_at": "2015-01-01T12:00:00Z",
  "user": {
    "allow_tracking": true,
    "beta": false,
    "created_at": "2012-01-01T12:00:00Z",
    "email": "username@example.com",
    "federated": false,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "identity_provider": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-sso",
      "team": {
        "name": "example"
      },
      "organization": {
        "name": "example"
      },
      "owner": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme",
        "type": "team"
      }
    },
    "last_login": "2012-01-01T12:00:00Z",
    "name": "Tina Edmonds",
    "sms_number": "+1 ***-***-1234",
    "suspended_at": "2012-01-01T12:00:00Z",
    "delinquent_at": "2012-01-01T12:00:00Z",
    "two_factor_authentication": false,
    "updated_at": "2012-01-01T12:00:00Z",
    "verified": false,
    "country_of_residence": "United States",
    "default_organization": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "default_team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "warning_message": "example"
}

Test Run Info

Info for existing test-run.

GET /test-runs/{test_run_id}

Curl Example

$ curl -n https://api.heroku.com/test-runs/$TEST_RUN_ID \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actor_email": "username@example.com",
  "clear_cache": true,
  "commit_branch": "example",
  "commit_message": "example",
  "commit_sha": "example",
  "debug": true,
  "app_setup": null,
  "created_at": "2015-01-01T12:00:00Z",
  "dyno": {
    "size": "standard-1X"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "message": "example",
  "number": 42,
  "organization": {
    "name": "example"
  },
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "status": "pending",
  "source_blob_url": "example",
  "updated_at": "2015-01-01T12:00:00Z",
  "user": {
    "allow_tracking": true,
    "beta": false,
    "created_at": "2012-01-01T12:00:00Z",
    "email": "username@example.com",
    "federated": false,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "identity_provider": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-sso",
      "team": {
        "name": "example"
      },
      "organization": {
        "name": "example"
      },
      "owner": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme",
        "type": "team"
      }
    },
    "last_login": "2012-01-01T12:00:00Z",
    "name": "Tina Edmonds",
    "sms_number": "+1 ***-***-1234",
    "suspended_at": "2012-01-01T12:00:00Z",
    "delinquent_at": "2012-01-01T12:00:00Z",
    "two_factor_authentication": false,
    "updated_at": "2012-01-01T12:00:00Z",
    "verified": false,
    "country_of_residence": "United States",
    "default_organization": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "default_team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "warning_message": "example"
}

Test Run List

List existing test-runs for a pipeline.

The only acceptable order value for the Range header is id.

GET /pipelines/{pipeline_id}/test-runs

Curl Example

$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/test-runs \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "actor_email": "username@example.com",
    "clear_cache": true,
    "commit_branch": "example",
    "commit_message": "example",
    "commit_sha": "example",
    "debug": true,
    "app_setup": null,
    "created_at": "2015-01-01T12:00:00Z",
    "dyno": {
      "size": "standard-1X"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "message": "example",
    "number": 42,
    "organization": {
      "name": "example"
    },
    "pipeline": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "status": "pending",
    "source_blob_url": "example",
    "updated_at": "2015-01-01T12:00:00Z",
    "user": {
      "allow_tracking": true,
      "beta": false,
      "created_at": "2012-01-01T12:00:00Z",
      "email": "username@example.com",
      "federated": false,
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "identity_provider": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme-sso",
        "team": {
          "name": "example"
        },
        "organization": {
          "name": "example"
        },
        "owner": {
          "id": "01234567-89ab-cdef-0123-456789abcdef",
          "name": "acme",
          "type": "team"
        }
      },
      "last_login": "2012-01-01T12:00:00Z",
      "name": "Tina Edmonds",
      "sms_number": "+1 ***-***-1234",
      "suspended_at": "2012-01-01T12:00:00Z",
      "delinquent_at": "2012-01-01T12:00:00Z",
      "two_factor_authentication": false,
      "updated_at": "2012-01-01T12:00:00Z",
      "verified": false,
      "country_of_residence": "United States",
      "default_organization": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      },
      "default_team": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "example"
      }
    },
    "warning_message": "example"
  }
]

Test Run Info By Pipeline

Info for existing test-run by Pipeline

GET /pipelines/{pipeline_id}/test-runs/{test_run_number}

Curl Example

$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/test-runs/$TEST_RUN_NUMBER \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actor_email": "username@example.com",
  "clear_cache": true,
  "commit_branch": "example",
  "commit_message": "example",
  "commit_sha": "example",
  "debug": true,
  "app_setup": null,
  "created_at": "2015-01-01T12:00:00Z",
  "dyno": {
    "size": "standard-1X"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "message": "example",
  "number": 42,
  "organization": {
    "name": "example"
  },
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "status": "pending",
  "source_blob_url": "example",
  "updated_at": "2015-01-01T12:00:00Z",
  "user": {
    "allow_tracking": true,
    "beta": false,
    "created_at": "2012-01-01T12:00:00Z",
    "email": "username@example.com",
    "federated": false,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "identity_provider": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-sso",
      "team": {
        "name": "example"
      },
      "organization": {
        "name": "example"
      },
      "owner": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme",
        "type": "team"
      }
    },
    "last_login": "2012-01-01T12:00:00Z",
    "name": "Tina Edmonds",
    "sms_number": "+1 ***-***-1234",
    "suspended_at": "2012-01-01T12:00:00Z",
    "delinquent_at": "2012-01-01T12:00:00Z",
    "two_factor_authentication": false,
    "updated_at": "2012-01-01T12:00:00Z",
    "verified": false,
    "country_of_residence": "United States",
    "default_organization": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "default_team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "warning_message": "example"
}

Test Run Update

Update a test-run’s status.

PATCH /test-runs/{test_run_number}

Required Parameters

Name	Type	Description	Example
message	nullable string	human friendly message indicating reason for an error	null
status	string	current state of the test run one of:"pending" or "cancelled" or "creating" or "building" or "running" or "succeeded" or "failed" or "errored" or "debugging"	"pending"

Curl Example

$ curl -n -X PATCH https://api.heroku.com/test-runs/$TEST_RUN_NUMBER \
  -d '{
  "status": "pending",
  "message": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "actor_email": "username@example.com",
  "clear_cache": true,
  "commit_branch": "example",
  "commit_message": "example",
  "commit_sha": "example",
  "debug": true,
  "app_setup": null,
  "created_at": "2015-01-01T12:00:00Z",
  "dyno": {
    "size": "standard-1X"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "message": "example",
  "number": 42,
  "organization": {
    "name": "example"
  },
  "pipeline": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "status": "pending",
  "source_blob_url": "example",
  "updated_at": "2015-01-01T12:00:00Z",
  "user": {
    "allow_tracking": true,
    "beta": false,
    "created_at": "2012-01-01T12:00:00Z",
    "email": "username@example.com",
    "federated": false,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "identity_provider": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-sso",
      "team": {
        "name": "example"
      },
      "organization": {
        "name": "example"
      },
      "owner": {
        "id": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "acme",
        "type": "team"
      }
    },
    "last_login": "2012-01-01T12:00:00Z",
    "name": "Tina Edmonds",
    "sms_number": "+1 ***-***-1234",
    "suspended_at": "2012-01-01T12:00:00Z",
    "delinquent_at": "2012-01-01T12:00:00Z",
    "two_factor_authentication": false,
    "updated_at": "2012-01-01T12:00:00Z",
    "verified": false,
    "country_of_residence": "United States",
    "default_organization": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "default_team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    }
  },
  "warning_message": "example"
}

User Preferences

Stability: production

Tracks a user’s preferences and message dismissals

Attributes

Name	Type	Description	Example
default-organization	nullable string	User’s default team	"sushi-inc"
dismissed-getting-started	nullable boolean	Whether the user has dismissed the getting started banner	true
dismissed-github-banner	nullable boolean	Whether the user has dismissed the GitHub link banner	true
dismissed-org-access-controls	nullable boolean	Whether the user has dismissed the Organization Access Controls banner	true
dismissed-org-wizard-notification	nullable boolean	Whether the user has dismissed the Organization Wizard	true
dismissed-pipelines-banner	nullable boolean	Whether the user has dismissed the Pipelines banner	true
dismissed-pipelines-github-banner	nullable boolean	Whether the user has dismissed the GitHub banner on a pipeline overview	true
dismissed-pipelines-github-banners	nullable array	Which pipeline uuids the user has dismissed the GitHub banner for	["96c68759-f310-4910-9867-e0b062064098"]
dismissed-sms-banner	nullable boolean	Whether the user has dismissed the 2FA SMS banner	true
timezone	nullable string	User’s default timezone	"UTC"

User Preferences List

Retrieve User Preferences

GET /users/{user_preferences_self}/preferences

Curl Example

$ curl -n https://api.heroku.com/users/$USER_PREFERENCES_SELF/preferences \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "timezone": "UTC",
  "default-organization": "sushi-inc",
  "dismissed-github-banner": true,
  "dismissed-getting-started": true,
  "dismissed-org-access-controls": true,
  "dismissed-org-wizard-notification": true,
  "dismissed-pipelines-banner": true,
  "dismissed-pipelines-github-banner": true,
  "dismissed-pipelines-github-banners": [
    "96c68759-f310-4910-9867-e0b062064098"
  ],
  "dismissed-sms-banner": true
}

User Preferences Update

Update User Preferences

PATCH /users/{user_preferences_self}/preferences

Optional Parameters

Name	Type	Description	Example
default-organization	nullable string	User’s default team	"sushi-inc"
dismissed-getting-started	nullable boolean	Whether the user has dismissed the getting started banner	true
dismissed-github-banner	nullable boolean	Whether the user has dismissed the GitHub link banner	true
dismissed-org-access-controls	nullable boolean	Whether the user has dismissed the Organization Access Controls banner	true
dismissed-org-wizard-notification	nullable boolean	Whether the user has dismissed the Organization Wizard	true
dismissed-pipelines-banner	nullable boolean	Whether the user has dismissed the Pipelines banner	true
dismissed-pipelines-github-banner	nullable boolean	Whether the user has dismissed the GitHub banner on a pipeline overview	true
dismissed-pipelines-github-banners	nullable array	Which pipeline uuids the user has dismissed the GitHub banner for	["96c68759-f310-4910-9867-e0b062064098"]
dismissed-sms-banner	nullable boolean	Whether the user has dismissed the 2FA SMS banner	true
timezone	nullable string	User’s default timezone	"UTC"

Curl Example

$ curl -n -X PATCH https://api.heroku.com/users/$USER_PREFERENCES_SELF/preferences \
  -d '{
  "timezone": "UTC",
  "default-organization": "sushi-inc",
  "dismissed-github-banner": true,
  "dismissed-getting-started": true,
  "dismissed-org-access-controls": true,
  "dismissed-org-wizard-notification": true,
  "dismissed-pipelines-banner": true,
  "dismissed-pipelines-github-banner": true,
  "dismissed-pipelines-github-banners": [
    "96c68759-f310-4910-9867-e0b062064098"
  ],
  "dismissed-sms-banner": true
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "timezone": "UTC",
  "default-organization": "sushi-inc",
  "dismissed-github-banner": true,
  "dismissed-getting-started": true,
  "dismissed-org-access-controls": true,
  "dismissed-org-wizard-notification": true,
  "dismissed-pipelines-banner": true,
  "dismissed-pipelines-github-banner": true,
  "dismissed-pipelines-github-banners": [
    "96c68759-f310-4910-9867-e0b062064098"
  ],
  "dismissed-sms-banner": true
}

Private Spaces VPN

Stability: production

VPN provides a way to connect your Private Spaces to your network via VPN.

Attributes

Name	Type	Description	Example
id	string	VPN ID	"123456789012"
ike_version	integer	IKE Version	1
name	string	VPN Name	"office"
public_ip	string	Public IP of VPN customer gateway	"35.161.69.30"
routable_cidrs	array	Routable CIDRs of VPN	["172.16.0.0/16"]
space_cidr_block	string	CIDR Block of the Private Space	"10.0.0.0/16"
status	string	Status of the VPN one of:"pending" or "provisioning" or "active" or "deprovisioning" or "failed"	"active"
status_message	string	Details of the status	"supplied CIDR block already in use"
tunnels	array		[{"last_status_change":"2016-10-25T22:09:05Z","ip":"52.44.146.197","customer_ip":"52.44.146.197","pre_shared_key":"secret","status":"UP","status_message":"status message"}]

Private Spaces VPN Create

Create a new VPN connection in a private space.

POST /spaces/{space_id_or_name}/vpn-connections

Required Parameters

Name	Type	Description	Example
name	string	VPN Name	"office"
public_ip	string	Public IP of VPN customer gateway	"35.161.69.30"
routable_cidrs	array	Routable CIDRs of VPN	["172.16.0.0/16"]

Curl Example

$ curl -n -X POST https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections \
  -d '{
  "name": "office",
  "public_ip": "35.161.69.30",
  "routable_cidrs": [
    "172.16.0.0/16"
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "id": "123456789012",
  "name": "office",
  "public_ip": "35.161.69.30",
  "routable_cidrs": [
    "172.16.0.0/16"
  ],
  "space_cidr_block": "10.0.0.0/16",
  "tunnels": [
    {
      "last_status_change": "2016-10-25T22:09:05Z",
      "ip": "52.44.146.197",
      "customer_ip": "52.44.146.197",
      "pre_shared_key": "secret",
      "status": "UP",
      "status_message": "status message"
    }
  ],
  "ike_version": 1,
  "status": "active",
  "status_message": "supplied CIDR block already in use"
}

Private Spaces VPN Destroy

Destroy existing VPN Connection

DELETE /spaces/{space_id_or_name}/vpn-connections/{vpn_connection_id_or_name}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections/$VPN_CONNECTION_ID_OR_NAME \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

Private Spaces VPN List

List VPN connections for a space.

Acceptable order values for the Range header are id or name.

GET /spaces/{space_id_or_name}/vpn-connections

Curl Example

$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

[
  {
    "id": "123456789012",
    "name": "office",
    "public_ip": "35.161.69.30",
    "routable_cidrs": [
      "172.16.0.0/16"
    ],
    "space_cidr_block": "10.0.0.0/16",
    "tunnels": [
      {
        "last_status_change": "2016-10-25T22:09:05Z",
        "ip": "52.44.146.197",
        "customer_ip": "52.44.146.197",
        "pre_shared_key": "secret",
        "status": "UP",
        "status_message": "status message"
      }
    ],
    "ike_version": 1,
    "status": "active",
    "status_message": "supplied CIDR block already in use"
  }
]

Private Spaces VPN Info

Info for an existing vpn-connection.

GET /spaces/{space_id_or_name}/vpn-connections/{vpn_connection_id_or_name}

Curl Example

$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections/$VPN_CONNECTION_ID_OR_NAME \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "id": "123456789012",
  "name": "office",
  "public_ip": "35.161.69.30",
  "routable_cidrs": [
    "172.16.0.0/16"
  ],
  "space_cidr_block": "10.0.0.0/16",
  "tunnels": [
    {
      "last_status_change": "2016-10-25T22:09:05Z",
      "ip": "52.44.146.197",
      "customer_ip": "52.44.146.197",
      "pre_shared_key": "secret",
      "status": "UP",
      "status_message": "status message"
    }
  ],
  "ike_version": 1,
  "status": "active",
  "status_message": "supplied CIDR block already in use"
}

Private Spaces VPN Update

Update a VPN connection in a private space.

PATCH /spaces/{space_id_or_name}/vpn-connections/{vpn_connection_id_or_name}

Required Parameters

Name	Type	Description	Example
routable_cidrs	array	Routable CIDRs of VPN	["172.16.0.0/16"]

Curl Example

$ curl -n -X PATCH https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections/$VPN_CONNECTION_ID_OR_NAME \
  -d '{
  "routable_cidrs": [
    "172.16.0.0/16"
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500

{
  "id": "123456789012",
  "name": "office",
  "public_ip": "35.161.69.30",
  "routable_cidrs": [
    "172.16.0.0/16"
  ],
  "space_cidr_block": "10.0.0.0/16",
  "tunnels": [
    {
      "last_status_change": "2016-10-25T22:09:05Z",
      "ip": "52.44.146.197",
      "customer_ip": "52.44.146.197",
      "pre_shared_key": "secret",
      "status": "UP",
      "status_message": "status message"
    }
  ],
  "ike_version": 1,
  "status": "active",
  "status_message": "supplied CIDR block already in use"
}