Platform API Reference
Table of Contents
The Platform API is a beta feature. Functionality may change prior to general availability.
Overview
The platform API empowers developers to automate, extend and combine Heroku with other services. You can use the platform API to programmatically create apps, provision add-ons and perform other tasks that could previously only be accomplished with Heroku toolbelt or dashboard. For details on getting started, see Getting Started with the Platform API.
Authentication
OAuth should be used to authorize and revoke access to your account to yourself and third parties. Details can be found in the OAuth article.
For personal scripts you may also use HTTP basic authentication, but OAuth is recommended for any third party services. HTTP basic authentication must be constructed from email address and api token as {email-address}:{token}, base64 encoded and passed as the Authorization header for each request, for example Authorization: Basic 0123456789ABCDEF=.
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.
Schema
The API has a machine-readable JSON schema that describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. You can access the schema using cURL:
$ curl https://api.heroku.com/schema -H "Accept: application/vnd.heroku+json; version=3" { "description": "The platform API empowers developers to automate, extend and combine Heroku with other services.", "definitions": { ... } }
cURL Examples
cURL examples are provided to facilitate experimentation. Variable values are represented as $SOMETHING so that you can manipulate them using environment variables. Examples use the -n option to fetch credentials from a ~/.netrc file, which should include an entry for api.heroku.com similar to the following:
machine api.heroku.com
login {your-email}
password {your-api-token}
Because Heroku’s V3 API is only accessible through HTTP Accept header, it may also be convenient to create a cURL alias for easy access:
alias c3='curl -n -H "Accept: application/vnd.heroku+json; version=3"'
Custom Types
| Name | JSON Type | Description |
|---|---|---|
| date-time | string | timestamp in iso8601 format |
| uuid | string | uuid in 8-4-4-4-12 format |
Data Integrity
Both unique id and more human-friendly attributes can be used reference resources. For example you can use name or id to refer to an app. Though the human-friendly version may be more convenient, id should be preferred to avoid ambiguity.
You may pass the If-Match header with an ETag value from a previous response to ensure a resource has not changed since you last received it. If the resource has changed, you will receive a 412 Precondition Failed response. If the resource has not changed, the request will proceed normally.
Errors
Failing responses will have an appropriate status and a JSON body containing more details about a particular error. See error responses for more example ids.
Error Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| id | string | id of error raised | "rate_limit" |
| message | string | end user message of error raised | "Your account reached the API limit. Please wait a few minutes before making new requests" |
| url | string | reference url with more information about the error | https://devcenter.heroku.com/articles/platform-api-reference#rate-limits |
Note that the url is included only when relevant and may not be present in the response.
Error Response
HTTP/1.1 429 Too Many Requests
{
"id": "rate_limit",
"message": "Your account reached the API rate limit\nPlease wait a few minutes before making new requests",
"url": "https://devcenter.heroku.com/articles/platform-api-reference#rate-limits"
}
Legacy API
Those utilizing the legacy, v2 API should instead consult legacy-api-docs.heroku.com
Methods
| Method | Usage |
|---|---|
| DELETE | used for destroying existing objects |
| GET | used for retrieving lists and individual objects |
| HEAD | used for retrieving metadata about existing objects |
| PATCH | used for updating existing objects |
| PUT | used for replacing 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 one or both of Next-Range and Prev-Range headers if there are next and previous ranges respectively. To retrieve the next or previous range, repeat the request with the Range header set to either the Next-Range or Prev-Range value from the previous request.
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 and Prev-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 1200 tokens. Each API call removes one token from the pool. Tokens are added to the account pool at a rate of 1200 per hour, up to a maximum of 1200. If no tokens remain, further calls will return 429 Too Many Requests until more tokens become available.
You can use the RateLimit-Remaining response header to check your current token count. You can also query the rate limit endpoint to get your token count. Requests to the rate limit endpoint do not count toward the limit. If you find your account is being rate limited but don’t know the cause, consider cycling your API key on the account page on Heroku dashboard.
Request Id
Each API response contains a unique request id in the Request-Id header to facilitate tracking. When reporting issues, providing this value makes it easier to pinpoint problems and provide solutions more quickly.
Responses
Values returned by the API are split into a section with example status code and relevant headers (with common http headers omitted) and a section with an example JSON body (if any).
Response Headers
| Header | Description |
|---|---|
| RateLimit-Remaining | allowed requests remaining in current interval |
Stability
Each resource in the Heroku Platform API Schema is annotated with a stability attribute, which will be set to one of three values, prototype, development, or production.
This attribute reflects the change management policy in place for the resource. For a full explanation of these policies, please see the devcenter documentation.
Statuses
The result of responses can be determined by returned status.
Successful Responses
| Status | Description |
|---|---|
| 200 OK | request succeeded |
| 201 Created | resource created, for example a new app was created or an add-on was provisioned |
| 202 Accepted | request accepted, but the processing has not been completed |
| 206 Partial Content | request succeeded, but this is only a partial response, see ranges |
Error Responses
Error responses can be divided in to two classes. Client errors result from malformed requests and should be addressed by the client. Heroku errors result from problems on the server side and must be addressed internally.
Client Error Responses
| Status | Error ID | Description |
|---|---|---|
| 400 Bad Request | bad_request |
request invalid, validate usage and try again |
| 401 Unauthorized | unauthorized |
request not authenticated, API token is missing, invalid or expired |
| 402 Payment Required | delinquent |
either the account has become delinquent as a result of non-payment, or the account’s payment method must be confirmed to continue |
| 403 Forbidden | forbidden |
request not authorized, provided credentials do not provide access to specified resource |
| 403 Forbidden | suspended |
request not authorized, account or application was suspended. |
| 404 Not Found | not_found |
request failed, the specified resource does not exist |
| 406 Not Acceptable | not_acceptable |
request failed, set Accept: application/vnd.heroku+json; version=3 header and try again |
| 416 Requested Range Not Satisfiable | requested_range_not_satisfiable |
request failed, validate Content-Range header and try again |
| 422 Unprocessable Entity | invalid_params |
request failed, validate parameters try again |
| 422 Unprocessable Entity | verification_needed |
request failed, enter billing information in the Heroku Dashboard before utilizing resources. |
| 429 Too Many Requests | rate_limit |
request failed, wait for rate limits to reset and try again, see rate limits |
Heroku Error Responses
| Status | Description |
|---|---|
| 500 Internal Server Error | error occurred, we are notified, but contact support if the issue persists |
| 503 Service Unavailable | API is unavailable, check response body or Heroku status for details |
Versioning
The beta and release of the api will all occur within version 3. We will provide warning and migration strategies for any backwards incompatible changes we might make during the beta and will commit to no backwards incompatible changes to version 3 after the release.
Warnings
Responses with warnings will have add headers describing the warning.
Warning Headers
| Header | Description | Example |
|---|---|---|
| id | id of warning | "stack_deprecated" |
Account Feature
Stability: development
An account feature represents a Heroku labs capability that can be enabled or disabled for an account on Heroku.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when account feature was created | "2012-01-01T12:00:00Z" |
| description | string | description of account feature | "Causes account to example." |
| doc_url | string | documentation URL of account feature | "http://devcenter.heroku.com/articles/example" |
| enabled | boolean | whether or not account feature has been enabled | true |
| id | uuid | unique identifier of account feature | "01234567-89ab-cdef-0123-456789abcdef" |
| name | string | unique name of account feature | "name" |
| state | string | state of account feature | "public" |
| updated_at | date-time | when account feature was updated | "2012-01-01T12:00:00Z" |
Account Feature Info
Info for an existing account feature.
GET /account/features/{account_feature_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/account/features/$ACCOUNT_FEATURE_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
Account Feature List
List existing account features.
Acceptable order values for the Range header are id or name.
GET /account/features
Curl Example
$ curl -n -X GET https://api.heroku.com/account/features \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Account Feature Update
Update an existing account feature.
PATCH /account/features/{account_feature_id_or_name}
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| enabled | boolean | whether or not account feature has been enabled | true |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/account/features/$ACCOUNT_FEATURE_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"enabled":true}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
Account
Stability: production
An account represents an individual signed up to use the Heroku platform.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| allow_tracking | boolean | whether to allow third party web activity tracking | true |
| beta | boolean | whether allowed to utilize beta Heroku features | false |
| created_at | date-time | when account was created | "2012-01-01T12:00:00Z" |
| unique email address of account | "username@example.com" |
||
| id | uuid | unique identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
| last_login | date-time | when account last authorized with Heroku | "2012-01-01T12:00:00Z" |
| updated_at | date-time | when account was updated | "2012-01-01T12:00:00Z" |
| verified | boolean | whether account has been verified with billing information | false |
Account Info
Info for account.
GET /account
Curl Example
$ curl -n -X GET https://api.heroku.com/account \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"last_login": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T12:00:00Z",
"verified": false
}
Account Update
Update account.
PATCH /account
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| password | string | current password on the account | "currentpassword" |
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| allow_tracking | boolean | whether to allow third party web activity tracking | true |
| beta | boolean | whether allowed to utilize beta Heroku features | false |
| name | string | full name of the account owner | "Tina Edmonds" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/account \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"allow_tracking":true,"beta":false,"name":"Tina Edmonds","password":"currentpassword"}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"last_login": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T12:00:00Z",
"verified": false
}
Account Change Email
Change Email for account.
PATCH /account
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| unique email address of account | "username@example.com" |
||
| password | string | current password on the account | "currentpassword" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/account \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"email":"username@example.com","password":"currentpassword"}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"last_login": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T12:00:00Z",
"verified": false
}
Account Change Password
Change Password for account.
PATCH /account
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| new_password | string | the new password for the account when changing the password | "newpassword" |
| password | string | current password on the account | "currentpassword" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/account \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"new_password":"newpassword","password":"currentpassword"}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"last_login": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T12:00:00Z",
"verified": false
}
Add-on Service
Stability: development
Add-on services represent add-ons that may be provisioned for apps.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when addon-service was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of this addon-service | "01234567-89ab-cdef-0123-456789abcdef" |
| name | string | unique name of this addon-service | "heroku-postgresql" |
| updated_at | date-time | when addon-service was updated | "2012-01-01T12:00:00Z" |
Add-on Service Info
Info for existing addon-service.
GET /addon-services/{addon_service_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/addon-services/$ADDON_SERVICE_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"updated_at": "2012-01-01T12:00:00Z"
}
Add-on Service List
List existing addon-services.
Acceptable order values for the Range header are id or name.
GET /addon-services
Curl Example
$ curl -n -X GET https://api.heroku.com/addon-services \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Add-on
Stability: production
Add-ons represent add-ons that have been provisioned for an app.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| config_vars | array | config vars associated with this application | ["FOO","BAZ"] |
| created_at | date-time | when add-on was updated | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of add-on | "01234567-89ab-cdef-0123-456789abcdef" |
| name | string | name of the add-on unique within its app | "heroku-postgresql-teal" |
| plan:id | uuid | unique identifier of this plan | "01234567-89ab-cdef-0123-456789abcdef" |
| plan:name | string | unique name of this plan | "heroku-postgresql:dev" |
| provider_id | string | id of this add-on with its provider | "app123@heroku.com" |
| updated_at | date-time | when add-on was updated | "2012-01-01T12:00:00Z" |
Add-on Create
Create a new add-on.
POST /apps/{app_id_or_name}/addons
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| plan | string | unique identifier or name of this plan |
"01234567-89ab-cdef-0123-456789abcdef" or "heroku-postgresql:dev"
|
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| config | object | custom add-on provisioning options | {"db-version":"1.2.3"} |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/addons \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"config":{"db-version":"1.2.3"},"plan":"01234567-89ab-cdef-0123-456789abcdef"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql-teal",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "app123@heroku.com",
"updated_at": "2012-01-01T12:00:00Z"
}
Add-on Delete
Delete an existing add-on.
DELETE /apps/{app_id_or_name}/addons/{addon_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADDON_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql-teal",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "app123@heroku.com",
"updated_at": "2012-01-01T12:00:00Z"
}
Add-on Info
Info for an existing add-on.
GET /apps/{app_id_or_name}/addons/{addon_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADDON_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql-teal",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "app123@heroku.com",
"updated_at": "2012-01-01T12:00:00Z"
}
Add-on List
List existing add-ons.
Acceptable order values for the Range header are id or name.
GET /apps/{app_id_or_name}/addons
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/addons \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql-teal",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "app123@heroku.com",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Add-on Update
Update an existing add-on.
PATCH /apps/{app_id_or_name}/addons/{addon_id_or_name}
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| plan | string | unique identifier or name of this plan |
"01234567-89ab-cdef-0123-456789abcdef" or "heroku-postgresql:dev"
|
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADDON_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"plan":"01234567-89ab-cdef-0123-456789abcdef"}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql-teal",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "app123@heroku.com",
"updated_at": "2012-01-01T12:00:00Z"
}
App Feature
Stability: development
An app feature represents a Heroku labs capability that can be enabled or disabled for an app on Heroku.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when app feature was created | "2012-01-01T12:00:00Z" |
| description | string | description of app feature | "Causes app to example." |
| doc_url | string | documentation URL of app feature | "http://devcenter.heroku.com/articles/example" |
| enabled | boolean | whether or not app feature has been enabled | true |
| id | uuid | unique identifier of app feature | "01234567-89ab-cdef-0123-456789abcdef" |
| name | string | unique name of app feature | "name" |
| state | string | state of app feature | "public" |
| updated_at | date-time | when app feature was updated | "2012-01-01T12:00:00Z" |
App Feature Info
Info for an existing app feature.
GET /apps/{app_id_or_name}/features/{app_feature_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/features/$APP_FEATURE_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes app to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
App Feature List
List existing app features.
Acceptable order values for the Range header are id or name.
GET /apps/{app_id_or_name}/features
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/features \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes app to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
]
App Feature Update
Update an existing app feature.
PATCH /apps/{app_id_or_name}/features/{app_feature_id_or_name}
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| enabled | boolean | whether or not app feature has been enabled | true |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/features/$APP_FEATURE_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"enabled":true}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes app to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
App Transfer
Stability: production
An app transfer represents a two party interaction for transferring ownership of an app.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| app:id | uuid | unique identifier of app | "01234567-89ab-cdef-0123-456789abcdef" |
| app:name | string | unique name of app | "example" |
| created_at | date-time | when app transfer was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of app transfer | "01234567-89ab-cdef-0123-456789abcdef" |
| owner:email | unique email address of account | "username@example.com" |
|
| owner:id | uuid | unique identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
| recipient: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 | "pending" |
| updated_at | date-time | when app transfer was updated | "2012-01-01T12:00:00Z" |
App Transfer Create
Create a new app transfer.
POST /account/app-transfers
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| app | string | unique identifier or name of app |
"01234567-89ab-cdef-0123-456789abcdef" or "example"
|
| recipient | string | unique identifier or email address of account |
"01234567-89ab-cdef-0123-456789abcdef" or "username@example.com"
|
Curl Example
$ curl -n -X POST https://api.heroku.com/account/app-transfers \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"app":"01234567-89ab-cdef-0123-456789abcdef","recipient":"01234567-89ab-cdef-0123-456789abcdef"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"recipient": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"state": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
App Transfer Delete
Delete an existing app transfer
DELETE /account/app-transfers/{app_transfer_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/account/app-transfers/$APP_TRANSFER_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"recipient": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"state": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
App Transfer Info
Info for existing app transfer.
GET /account/app-transfers/{app_transfer_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/account/app-transfers/$APP_TRANSFER_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"recipient": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"state": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
App Transfer List
List existing apps transfers.
Acceptable order values for the Range header are id or name.
GET /account/app-transfers
Curl Example
$ curl -n -X GET https://api.heroku.com/account/app-transfers \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"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 | "pending" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/account/app-transfers/$APP_TRANSFER_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"state":"pending"}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"recipient": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"state": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
App
Stability: production
An app represents the program that you would like to deploy and run on Heroku.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| archived_at | nullable date-time | when app was archived | "2012-01-01T12:00:00Z" |
| 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 | uri | git repo URL of app | "git@heroku.com/example.git" |
| id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
| maintenance | boolean | maintenance status of app | false |
| name | string | name of app | "example" |
| owner:email | email address of account | "username@example.com" |
|
| owner:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
| region:id | uuid | unique identifier of region | "01234567-89ab-cdef-0123-456789abcdef" |
| region:name | string | unique name of region | "us" |
| released_at | nullable date-time | when app was released | "2012-01-01T12:00:00Z" |
| repo_size | nullable integer | git repo size in bytes of app | 0 |
| slug_size | nullable integer | slug size in bytes of app | 0 |
| stack:id | uuid | unique identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
| stack:name | string | unique name of stack | "cedar" |
| updated_at | date-time | when app was updated | "2012-01-01T12:00:00Z" |
| web_url | uri | web URL of app | "http://example.herokuapp.com" |
App Create
Create a new app.
POST /apps
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| name | string | name of app | "example" |
| region | string | unique identifier or name of region |
"01234567-89ab-cdef-0123-456789abcdef" or "us"
|
| stack | string | unique identifier or name of stack |
"01234567-89ab-cdef-0123-456789abcdef" or "cedar"
|
Curl Example
$ curl -n -X POST https://api.heroku.com/apps \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"name":"example","region":"01234567-89ab-cdef-0123-456789abcdef","stack":"01234567-89ab-cdef-0123-456789abcdef"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"created_at": "2012-01-01T12:00:00Z",
"git_url": "git@heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "http://example.herokuapp.com"
}
App Delete
Delete an existing app.
DELETE /apps/{app_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"created_at": "2012-01-01T12:00:00Z",
"git_url": "git@heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "http://example.herokuapp.com"
}
App Info
Info for existing app.
GET /apps/{app_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"created_at": "2012-01-01T12:00:00Z",
"git_url": "git@heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "http://example.herokuapp.com"
}
App List
List existing apps.
Acceptable order values for the Range header are id or name.
GET /apps
Curl Example
$ curl -n -X GET https://api.heroku.com/apps \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"created_at": "2012-01-01T12:00:00Z",
"git_url": "git@heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "http://example.herokuapp.com"
}
]
App Update
Update an existing app.
PATCH /apps/{app_id_or_name}
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| maintenance | boolean | maintenance status of app | false |
| name | string | name of app | "example" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"maintenance":false,"name":"example"}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"created_at": "2012-01-01T12:00:00Z",
"git_url": "git@heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "http://example.herokuapp.com"
}
Collaborator
Stability: production
A collaborator represents an account that has been given access to an app on Heroku.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when collaborator was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of collaborator | "01234567-89ab-cdef-0123-456789abcdef" |
| updated_at | date-time | when collaborator was updated | "2012-01-01T12:00:00Z" |
| user:email | email address of account | "username@example.com" |
|
| user:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
Collaborator Create
Create a new collaborator.
POST /apps/{app_id_or_name}/collaborators
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| user | string | unique identifier or email address of account |
"01234567-89ab-cdef-0123-456789abcdef" or "username@example.com"
|
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| silent | boolean | whether to suppress email invitation when creating collaborator | false |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"silent":false,"user":"01234567-89ab-cdef-0123-456789abcdef"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Collaborator Delete
Delete an existing collaborator.
DELETE /apps/{app_id_or_name}/collaborators/{collaborator_email_or_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators/$COLLABORATOR_EMAIL_OR_ID \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Collaborator Info
Info for existing collaborator.
GET /apps/{app_id_or_name}/collaborators/{collaborator_email_or_id}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators/$COLLABORATOR_EMAIL_OR_ID \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Collaborator List
List existing collaborators.
Acceptable order values for the Range header are email or id.
GET /apps/{app_id_or_name}/collaborators
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
]
Config Vars
Stability: development
Config Vars allow you to manage the configuration information provided to an app on Heroku.
Config Vars Info
Get config-vars for app.
GET /apps/{app_id_or_name}/config-vars
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/config-vars \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"FOO": "bar",
"BAZ": "qux"
}
Config Vars Update
Update config-vars for app. You can update existing config-vars by setting them again, and remove by setting it to NULL.
PATCH /apps/{app_id_or_name}/config-vars
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/config-vars \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"FOO":null,"BAZ":"grault"}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"FOO": "bar",
"BAZ": "qux"
}
Domain
Stability: production
Domains define what web routes should be routed to an app on Heroku.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when domain was created | "2012-01-01T12:00:00Z" |
| hostname | string | full hostname | "subdomain.example.com" |
| id | uuid | unique identifier of this domain | "01234567-89ab-cdef-0123-456789abcdef" |
| updated_at | date-time | when domain was updated | "2012-01-01T12:00:00Z" |
Domain Create
Create a new domain.
POST /apps/{app_id_or_name}/domains
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| hostname | string | full hostname | "subdomain.example.com" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/domains \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"hostname":"subdomain.example.com"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
Domain Delete
Delete an existing domain
DELETE /apps/{app_id_or_name}/domains/{domain_id_or_hostname}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/domains/$DOMAIN_ID_OR_HOSTNAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
Domain Info
Info for existing domain.
GET /apps/{app_id_or_name}/domains/{domain_id_or_hostname}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/domains/$DOMAIN_ID_OR_HOSTNAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
Domain List
List existing domains.
Acceptable order values for the Range header are id or hostname.
GET /apps/{app_id_or_name}/domains
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/domains \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: id, hostname 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Dyno
Stability: development
Dynos encapsulate running processes of an app on Heroku.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| attach_url | nullable string | a URL to stream output from for attached processes or null for non-attached processes | "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}" |
| command | string | command used to start this process | "bash" |
| created_at | date-time | when dyno was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of this dyno | "01234567-89ab-cdef-0123-456789abcdef" |
| name | string | the name of this process on this dyno | "run.1" |
| release:id | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
| release:version | integer | unique version assigned to the release | 11 |
| size | string | dyno size (default: “1X”) | "1X" |
| state | string | current status of process (either: crashed, down, idle, starting, or up) | "up" |
| type | string | type of process | "run" |
| updated_at | date-time | when process last changed state | "2012-01-01T12:00:00Z" |
Dyno Create
Create a new dyno.
POST /apps/{app_id_or_name}/dynos
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| command | string | command used to start this process | "bash" |
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| attach | boolean | whether to stream output or not | true |
| env | object | custom environment to add to the dyno config vars | {"COLUMNS":"80","LINES":"24"} |
| size | string | dyno size (default: “1X”) | "1X" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"attach":true,"command":"bash","env":{"COLUMNS":"80","LINES":"24"},"size":"1X"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
"command": "bash",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "run.1",
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"version": 11
},
"size": "1X",
"state": "up",
"type": "run",
"updated_at": "2012-01-01T12:00:00Z"
}
Dyno Restart
Restart dyno.
DELETE /apps/{app_id_or_name}/dynos/{dyno_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos/$DYNO_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{}
Dyno Restart all
Restart all dynos
DELETE /apps/{app_id_or_name}/dynos
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{}
Dyno Info
Info for existing dyno.
GET /apps/{app_id_or_name}/dynos/{dyno_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos/$DYNO_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
"command": "bash",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "run.1",
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"version": 11
},
"size": "1X",
"state": "up",
"type": "run",
"updated_at": "2012-01-01T12:00:00Z"
}
Dyno List
List existing dynos.
Acceptable order values for the Range header are id or name.
GET /apps/{app_id_or_name}/dynos
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
"command": "bash",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "run.1",
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"version": 11
},
"size": "1X",
"state": "up",
"type": "run",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Formation
Stability: production
The formation of processes that should be maintained for an app. Update the formation to scale processes or change dyno sizes. Available process type names and commands are defined by the process_types attribute for the slug currently released on an app.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| command | string | command to use to launch this process | "bundle exec rails server -p $PORT" |
| created_at | date-time | when process type was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of this process type | "01234567-89ab-cdef-0123-456789abcdef" |
| quantity | integer | number of processes to maintain | 1 |
| size | string | dyno size (default: “1X”) | "1X" |
| type | string | type of process to maintain | "web" |
| updated_at | date-time | when dyno type was updated | "2012-01-01T12:00:00Z" |
Formation Info
Info for a process type
GET /apps/{app_id_or_name}/formation/{formation_id_or_type}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/formation/$FORMATION_ID_OR_TYPE \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"command": "bundle exec rails server -p $PORT",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"quantity": 1,
"size": "1X",
"type": "web",
"updated_at": "2012-01-01T12:00:00Z"
}
Formation List
List process type formation
Acceptable order values for the Range header are id or type.
GET /apps/{app_id_or_name}/formation
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/formation \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"command": "bundle exec rails server -p $PORT",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"quantity": 1,
"size": "1X",
"type": "web",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Formation Batch update
Batch update process types
PATCH /apps/{app_id_or_name}/formation
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| updates | array | Array with formation updates. Each element must have “process”, the id or name of the process type to be updated, and can optionally update its “quantity” or “size”. | {"updates":[{"process":"web","quantity":1,"size":"2X"}]} |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/formation \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"updates":{"updates":[{"process":"web","quantity":1,"size":"2X"}]}}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"command": "bundle exec rails server -p $PORT",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"quantity": 1,
"size": "1X",
"type": "web",
"updated_at": "2012-01-01T12:00:00Z"
}
Formation Update
Update process type
PATCH /apps/{app_id_or_name}/formation/{formation_id_or_type}
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| quantity | integer | number of processes to maintain | 1 |
| size | string | dyno size (default: “1X”) | "1X" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/formation/$FORMATION_ID_OR_TYPE \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"quantity":1,"size":"1X"}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"command": "bundle exec rails server -p $PORT",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"quantity": 1,
"size": "1X",
"type": "web",
"updated_at": "2012-01-01T12:00:00Z"
}
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 |
|---|---|---|---|
| created_at | date-time | when key was created | "2012-01-01T12:00:00Z" |
| email address provided in key contents | "username@example.com" |
||
| fingerprint | string | a unique identifying string based on contents | "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf" |
| id | uuid | unique identifier of this key | "01234567-89ab-cdef-0123-456789abcdef" |
| public_key | string | full public_key as uploaded | "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com" |
| updated_at | date-time | when key was updated | "2012-01-01T12:00:00Z" |
Key Create
Create a new key.
POST /account/keys
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| public_key | string | full public_key as uploaded | "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com" |
Curl Example
$ curl -n -X POST https://api.heroku.com/account/keys \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"public_key":"ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"fingerprint": "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"public_key": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com",
"updated_at": "2012-01-01T12:00:00Z"
}
Key Delete
Delete an existing key
DELETE /account/keys/{key_id_or_fingerprint}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/account/keys/$KEY_ID_OR_FINGERPRINT \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"fingerprint": "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"public_key": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com",
"updated_at": "2012-01-01T12:00:00Z"
}
Key Info
Info for existing key.
GET /account/keys/{key_id_or_fingerprint}
Curl Example
$ curl -n -X GET https://api.heroku.com/account/keys/$KEY_ID_OR_FINGERPRINT \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"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 id or fingerprint.
GET /account/keys
Curl Example
$ curl -n -X GET https://api.heroku.com/account/keys \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: id, fingerprint 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"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: development
Log drains provide a way to forward your Heroku logs to an external syslog server for long-term archiving. This external service must be configured to receive syslog packets from Heroku, whereupon its URL can be added to an app using this API. Some addons will add a log drain when they are provisioned to an app. These drains can only be removed by removing the add-on.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| addon | nullable object | addon that created the drain | "example" |
| created_at | date-time | when log drain was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of this log drain | "01234567-89ab-cdef-0123-456789abcdef" |
| token | string | token associated with the log drain | "d.01234567-89ab-cdef-0123-456789abcdef" |
| updated_at | date-time | when log drain was updated | "2012-01-01T12:00:00Z" |
| url | string | url associated with the log drain | "https://example.com/drain" |
Log Drain Create
Create a new log drain.
POST /apps/{app_id_or_name}/log-drains
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| url | string | url associated with the log drain | "https://example.com/drain" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/drain"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain Delete
Delete an existing log drain. Log drains added by add-ons can only be removed by removing the add-on.
DELETE /apps/{app_id_or_name}/log-drains/{log_drain_id_or_url}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain Info
Info for existing log drain.
GET /apps/{app_id_or_name}/log-drains/{log_drain_id_or_url}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain List
List existing log drains.
Acceptable order values for the Range header are id or url.
GET /apps/{app_id_or_name}/log-drains
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: id, url Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200 ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"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: development
A log session is a reference to the http based log stream for an app.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when log connection was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of this log session | "01234567-89ab-cdef-0123-456789abcdef" |
| logplex_url | string | URL for log streaming session | "https://logplex.heroku.com/sessions/01234567-89ab-cdef-0123-456789abcdef?srv=1325419200" |
| updated_at | date-time | when log session was updated | "2012-01-01T12:00:00Z" |
Log Session Create
Create a new log session.
POST /apps/{app_id_or_name}/log-sessions
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| dyno | string | dyno to limit results to | "web.1" |
| lines | integer | number of log lines to stream at once | 10 |
| source | string | log source to limit results to | "app" |
| tail | boolean | whether to stream ongoing logs | true |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/log-sessions \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"dyno":"web.1","lines":10,"source":"app","tail":true}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"logplex_url": "https://logplex.heroku.com/sessions/01234567-89ab-cdef-0123-456789abcdef?srv=1325419200",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Authorization
Stability: production
OAuth authorizations represent clients that a Heroku user has authorized to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| access_token | nullable object | access token for this authorization | null |
| client | nullable object | identifier of the client that obtained this authorization, if any | null |
| created_at | date-time | when OAuth authorization was created | "2012-01-01T12:00:00Z" |
| grant | nullable object | this authorization’s grant | null |
| id | uuid | unique identifier of OAuth authorization | "01234567-89ab-cdef-0123-456789abcdef" |
| refresh_token | nullable object | refresh token for this authorization | null |
| scope | array | The scope of access OAuth authorization allows | ["global"] |
| updated_at | date-time | when OAuth authorization was updated | "2012-01-01T12:00:00Z" |
OAuth Authorization Create
Create a new OAuth authorization.
POST /oauth/authorizations
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| scope | array | The scope of access OAuth authorization allows | ["global"] |
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| client | string | unique identifier of this OAuth client | "01234567-89ab-cdef-0123-456789abcdef" |
| description | string | human-friendly description of this OAuth authorization | "sample authorization" |
| expires_in | nullable integer | seconds until OAuth token expires; may be `null` for tokens with indefinite lifetime | 2592000 |
Curl Example
$ curl -n -X POST https://api.heroku.com/oauth/authorizations \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"client":"01234567-89ab-cdef-0123-456789abcdef","description":"sample authorization","expires_in":2592000,"scope":["global"]}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Authorization Delete
Delete OAuth authorization.
DELETE /oauth/authorizations/{oauth_authorization_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Authorization Info
Info for an OAuth authorization.
GET /oauth/authorizations/{oauth_authorization_id}
Curl Example
$ curl -n -X GET https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Authorization List
List OAuth authorizations.
The only acceptable order value for the Range header is id.
GET /oauth/authorizations
Curl Example
$ curl -n -X GET https://api.heroku.com/oauth/authorizations \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z"
}
]
OAuth Client
Stability: production
OAuth clients are applications that Heroku users can authorize to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when OAuth client was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of this OAuth client | "01234567-89ab-cdef-0123-456789abcdef" |
| ignores_delinquent | nullable boolean | whether the client is still operable given a delinquent account | false |
| name | string | OAuth client name | "example" |
| redirect_uri | string | endpoint for redirection after authorization with OAuth client | "https://example.com/auth/heroku/callback" |
| secret | string | secret used to obtain OAuth authorizations under this client | "01234567-89ab-cdef-0123-456789abcdef" |
| updated_at | date-time | when OAuth client was updated | "2012-01-01T12:00:00Z" |
OAuth Client Create
Create a new OAuth client.
POST /oauth/clients
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| name | string | OAuth client name | "example" |
| redirect_uri | string | endpoint for redirection after authorization with OAuth client | "https://example.com/auth/heroku/callback" |
Curl Example
$ curl -n -X POST https://api.heroku.com/oauth/clients \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"name":"example","redirect_uri":"https://example.com/auth/heroku/callback"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Client Delete
Delete OAuth client.
DELETE /oauth/clients/{oauth_client_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Client Info
Info for an OAuth client
GET /oauth/clients/{oauth_client_id}
Curl Example
$ curl -n -X GET https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Client List
List OAuth clients
The only acceptable order value for the Range header is id.
GET /oauth/clients
Curl Example
$ curl -n -X GET https://api.heroku.com/oauth/clients \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
]
OAuth Client Update
Update OAuth client
PATCH /oauth/clients/{oauth_client_id}
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| name | string | OAuth client name | "example" |
| redirect_uri | string | endpoint for redirection after authorization with OAuth client | "https://example.com/auth/heroku/callback" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"name":"example","redirect_uri":"https://example.com/auth/heroku/callback"}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Token
Stability: production
OAuth tokens provide access for authorized clients to act on behalf of a Heroku user to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| access_token:expires_in | nullable integer | seconds until OAuth token expires; may be `null` for tokens with indefinite lifetime | 2592000 |
| access_token:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
| access_token:token | string | contents of the token to be used for authorization | "01234567-89ab-cdef-0123-456789abcdef" |
| authorization:id | uuid | unique identifier of OAuth authorization | "01234567-89ab-cdef-0123-456789abcdef" |
| client | nullable object | OAuth client secret used to obtain token | null |
| created_at | date-time | when OAuth token was created | "2012-01-01T12:00:00Z" |
| grant:code | string | grant code received from OAuth web application authorization | "01234567-89ab-cdef-0123-456789abcdef" |
| grant:type | string | type of grant requested, one of `authorization_code` or `refresh_token` | "authorization_code" |
| id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
| refresh_token:expires_in | nullable integer | seconds until OAuth token expires; may be `null` for tokens with indefinite lifetime | 2592000 |
| refresh_token:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
| refresh_token:token | string | contents of the token to be used for authorization | "01234567-89ab-cdef-0123-456789abcdef" |
| session:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
| updated_at | date-time | when OAuth token was updated | "2012-01-01T12:00:00Z" |
| user:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
OAuth Token Create
Create a new OAuth token.
POST /oauth/tokens
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| client:secret | string | secret used to obtain OAuth authorizations under this client | "01234567-89ab-cdef-0123-456789abcdef" |
| grant:code | string | grant code received from OAuth web application authorization | "01234567-89ab-cdef-0123-456789abcdef" |
| grant:type | string | type of grant requested, one of `authorization_code` or `refresh_token` | "authorization_code" |
| refresh_token:token | string | contents of the token to be used for authorization | "01234567-89ab-cdef-0123-456789abcdef" |
Curl Example
$ curl -n -X POST https://api.heroku.com/oauth/tokens \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"client":null,"grant":null,"refresh_token":null}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"authorization": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"secret": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"type": "authorization_code"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"session": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Plan
Stability: production
Plans represent different configurations of add-ons that may be added to apps.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when plan was created | "2012-01-01T12:00:00Z" |
| default | boolean | whether this plan is the default for its addon service | false |
| description | string | description of plan | "Heroku Postgres Dev" |
| id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
| name | string | name of this plan | "heroku-postgresql:dev" |
| price:cents | integer | price in cents per unit of plan | 0 |
| price:unit | string | unit of price for plan | "month" |
| state | string | release status for plan | "public" |
| updated_at | date-time | when plan was updated | "2012-01-01T12:00:00Z" |
Plan Info
Info for existing plan.
GET /addon-services/{addon_service_id_or_name}/plans/{plan_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/addon-services/$ADDON_SERVICE_ID_OR_NAME/plans/$PLAN_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"default": false,
"description": "Heroku Postgres Dev",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev",
"price": {
"cents": 0,
"unit": "month"
},
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
Plan List
List existing plans.
Acceptable order values for the Range header are id or name.
GET /addon-services/{addon_service_id_or_name}/plans
Curl Example
$ curl -n -X GET https://api.heroku.com/addon-services/$ADDON_SERVICE_ID_OR_NAME/plans \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"default": false,
"description": "Heroku Postgres Dev",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev",
"price": {
"cents": 0,
"unit": "month"
},
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Rate Limit
Stability: production
Rate Limit represents the number of request tokens each account holds. Requests to this endpoint do not count towards the rate limit.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| remaining | integer | allowed requests remaining in current interval | 2399 |
Rate Limit Info
Info for rate limits.
GET /account/rate-limits
Curl Example
$ curl -n -X GET https://api.heroku.com/account/rate-limits \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"remaining": 2399
}
Region
Stability: development
A region represents a geographic location in which your application may run.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when region was created | "2012-01-01T12:00:00Z" |
| description | string | description of region | "United States" |
| id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
| name | string | name of region | "us" |
| updated_at | date-time | when region was updated | "2012-01-01T12:00:00Z" |
Region Info
Info for existing region.
GET /regions/{region_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/regions/$REGION_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"description": "United States",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us",
"updated_at": "2012-01-01T12:00:00Z"
}
Region List
List existing regions.
Acceptable order values for the Range header are id or name.
GET /regions
Curl Example
$ curl -n -X GET https://api.heroku.com/regions \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"description": "United States",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Release
Stability: development
A release represents a combination of code, config vars and add-ons for an app on Heroku.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when release was created | "2012-01-01T12:00:00Z" |
| description | string | description of changes in this release | "Added new feature" |
| id | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
| updated_at | date-time | when release was updated | "2012-01-01T12:00:00Z" |
| slug | nullable object | slug running in this release | null |
| user:email | email address of account | "username@example.com" |
|
| user:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
| version | integer | unique version assigned to the release | 11 |
Release Info
Info for existing release.
GET /apps/{app_id_or_name}/releases/{release_id_or_version}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/releases/$RELEASE_ID_OR_VERSION \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11
}
Release List
List existing releases.
Acceptable order values for the Range header are id or version.
GET /apps/{app_id_or_name}/releases
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/releases \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11
}
]
Release Create
Create new release. The API cannot be used to create releases on Bamboo apps.
POST /apps/{app_id_or_name}/releases
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| slug | string | unique identifier of slug | "01234567-89ab-cdef-0123-456789abcdef" |
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| description | string | description of changes in this release | "Added new feature" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/releases \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"description":"Added new feature","slug":"01234567-89ab-cdef-0123-456789abcdef"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11
}
Release Rollback
Rollback to an existing release.
POST /apps/{app_id_or_name}/releases
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| release | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/releases \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"release":"01234567-89ab-cdef-0123-456789abcdef"}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11
}
Slug
Stability: development
A slug is a snapshot of your application code that is ready to run on the platform.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| blob:method | string | method to be used to interact with the slug blob | "GET" |
| blob:url | string | URL to interact with the slug blob | "https://api.heroku.com/slugs/1234.tgz" |
| buildpack_provided_description | nullable string | description from buildpack of slug | "Ruby/Rack" |
| commit | nullable string | identification of the code with your version control system (eg: SHA of the git HEAD) | "60883d9e8947a57e04dc9124f25df004866a2051" |
| created_at | date-time | when slug was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of slug | "01234567-89ab-cdef-0123-456789abcdef" |
| process_types | object | hash mapping process type names to their respective command | {"web":"./bin/web -p $PORT"} |
| updated_at | date-time | when slug was updated | "2012-01-01T12:00:00Z" |
Slug Info
Info for existing slug.
GET /apps/{app_id_or_name}/slugs/{slug_id}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/slugs/$SLUG_ID \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"blob": {
"method": "GET",
"url": "https://api.heroku.com/slugs/1234.tgz"
},
"buildpack_provided_description": "Ruby/Rack",
"commit": "60883d9e8947a57e04dc9124f25df004866a2051",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"process_types": {
"web": "./bin/web -p $PORT"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Slug Create
Create a new slug. For more information please refer to Deploying Slugs using the Platform API.
POST /apps/{app_id_or_name}/slugs
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| process_types | object | hash mapping process type names to their respective command | {"web":"./bin/web -p $PORT"} |
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| buildpack_provided_description | nullable string | description from buildpack of slug | "Ruby/Rack" |
| commit | nullable string | identification of the code with your version control system (eg: SHA of the git HEAD) | "60883d9e8947a57e04dc9124f25df004866a2051" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/slugs \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"buildpack_provided_description":"Ruby/Rack","commit":"60883d9e8947a57e04dc9124f25df004866a2051","process_types":{"web":"./bin/web -p $PORT"}}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"blob": {
"method": "GET",
"url": "https://api.heroku.com/slugs/1234.tgz"
},
"buildpack_provided_description": "Ruby/Rack",
"commit": "60883d9e8947a57e04dc9124f25df004866a2051",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"process_types": {
"web": "./bin/web -p $PORT"
},
"updated_at": "2012-01-01T12:00:00Z"
}
SSL Endpoint
Stability: development
SSL Endpoint is a public address serving custom SSL cert for HTTPS traffic to a Heroku app. Note that an app must have the ssl:endpoint addon installed before it can provision an SSL Endpoint using these APIs.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
| cname | string | canonical name record, the address to point a domain at | "example.herokussl.com" |
| created_at | date-time | when endpoint was created | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier of this SSL endpoint | "01234567-89ab-cdef-0123-456789abcdef" |
| name | string | unique name for SSL endpoint | "example" |
| updated_at | date-time | when endpoint was updated | "2012-01-01T12:00:00Z" |
SSL Endpoint Create
Create a new SSL endpoint.
POST /apps/{app_id_or_name}/ssl-endpoints
Required Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
| private_key | string | contents of the private key (eg .key file) | "-----BEGIN RSA PRIVATE KEY----- ..." |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"certificate_chain":"-----BEGIN CERTIFICATE----- ...","private_key":"-----BEGIN RSA PRIVATE KEY----- ..."}'
Response Example
HTTP/1.1 201 Created ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
SSL Endpoint Delete
Delete existing SSL endpoint.
DELETE /apps/{app_id_or_name}/ssl-endpoints/{ssl_endpoint_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints/$SSL_ENDPOINT_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
SSL Endpoint Info
Info for existing SSL endpoint.
GET /apps/{app_id_or_name}/ssl-endpoints/{ssl_endpoint_id_or_name}
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints/$SSL_ENDPOINT_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
SSL Endpoint List
List existing SSL endpoints.
Acceptable order values for the Range header are id or name.
GET /apps/{app_id_or_name}/ssl-endpoints
Curl Example
$ curl -n -X GET https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: 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: 1200
[
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
]
SSL Endpoint Update
Update an existing SSL endpoint.
PATCH /apps/{app_id_or_name}/ssl-endpoints/{ssl_endpoint_id_or_name}
Optional Parameters
| Name | Type | Description | Example |
|---|---|---|---|
| certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
| private_key | string | contents of the private key (eg .key file) | "-----BEGIN RSA PRIVATE KEY----- ..." |
| rollback | boolean | indicates that a rollback should be performed | false |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints/$SSL_ENDPOINT_ID_OR_NAME \ -H "Accept: application/vnd.heroku+json; version=3" \ -H "Content-Type: application/json" \ -d '{"certificate_chain":"-----BEGIN CERTIFICATE----- ...","private_key":"-----BEGIN RSA PRIVATE KEY----- ...","rollback":false}'
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
Stack
Stability: development
Stacks are the different application execution environments available in the Heroku platform.
Attributes
| Name | Type | Description | Example |
|---|---|---|---|
| created_at | date-time | when stack was introduced | "2012-01-01T12:00:00Z" |
| id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
| name | string | name of stack | "cedar" |
| state | string | availability of this stack: beta, deprecated or public | "public" |
| updated_at | date-time | when stack was last modified | "2012-01-01T12:00:00Z" |
Stack Info
Stack info.
GET /stacks/{stack_name_or_id}
Curl Example
$ curl -n -X GET https://api.heroku.com/stacks/$STACK_NAME_OR_ID \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK ETag: "0123456789abcdef0123456789abcdef" Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT RateLimit-Remaining: 1200
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
Stack List
List available stacks.
Acceptable order values for the Range header are name or id.
GET /stacks
Curl Example
$ curl -n -X GET https://api.heroku.com/stacks \ -H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK Accept-Range: name, 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: 1200
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Your feedback has been sent to the Dev Center team. Thank you.