Platform API Reference
Last updated September 27, 2024
Table of Contents
- Overview
- Account
- Account Delinquency
- Account Feature
- Add-on
- Add-on Action
- Add-on Attachment
- Add-on Config
- Add-on Plan Action
- Add-on Region Capability
- Add-on Service
- Add-on Webhook
- Add-on Webhook Delivery
- Add-on Webhook Event
- Allowed Add-on Service
- App
- App Feature
- App Setup
- App Transfer
- App Webhook
- App Webhook Delivery
- App Webhook Event
- Audit Trail Archive
- Audit Trail Event
- Build
- Buildpack Installations
- Collaborator
- Config Vars
- Credit
- Domain
- Dyno
- Dyno Size
- Enterprise Account
- Enterprise Account Daily Usage
- Enterprise Account Member
- Enterprise Account Monthly Usage
- Filters
- Formation
- Identity Provider
- Inbound Ruleset
- Invoice
- Invoice Address
- Key
- Log Drain
- Log Session
- OAuth Authorization
- OAuth Client
- OAuth Grant
- OAuth Token
- PasswordReset
- Peering
- Peering Info
- Permission Entity
- Pipeline
- Pipeline Build
- Pipeline Config Vars
- Pipeline Coupling
- Pipeline Deployment
- Pipeline Promotion
- Pipeline Promotion Target
- Pipeline Release
- Pipeline Stack
- Pipeline Transfer
- Plan
- Rate Limit
- Region
- Release
- Review App
- Review App Configuration
- Slug
- SMS Number
- SNI Endpoint
- Source
- Space
- Space Access
- Space Network Address Translation
- Space Topology
- Space Transfer
- Stack
- Team
- Team Add-on
- Team App
- Team App Collaborator
- Team App Permission
- Team Daily Usage
- Team Delinquency
- Team Feature
- Team Invitation
- Team Invoice
- Team Member
- Team Monthly Usage
- Team Preferences
- Team Space
- Test Case
- Test Node
- Test Run
- User Preferences
- Private Spaces VPN
Overview
The platform API empowers developers to automate, extend and combine Heroku with other services. You can use the platform API to programmatically create apps, provision add-ons and perform other tasks that could previously only be accomplished with the Heroku CLI or Dashboard. For details on getting started, see Getting Started with the Platform API.
Authentication
OAuth should be used to authorize and revoke access to your account to yourself and third parties. Details can be found in the OAuth article.
For personal scripts you may also use HTTP bearer authentication, but OAuth is recommended for any third party services. HTTP bearer authentication must be constructed using an API token, passed as the Authorization header for each request, for example Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef
. The quick start guide has more details.
Caching
All responses include an ETag
(or Entity Tag) header, identifying the specific version of a returned resource. You may use this value to check for changes to a resource by repeating the request and passing the ETag
value in the If-None-Match
header. If the resource has not changed, a 304 Not Modified
status will be returned with an empty body. If the resource has changed, the request will proceed normally.
Clients
Clients must address requests to api.heroku.com
using HTTPS and specify the Accept: application/vnd.heroku+json; version=3
Accept header. Clients should specify a User-Agent
header to facilitate tracking and debugging.
CORS
The Platform API supports cross-origin resource sharing (CORS) so that requests can be sent from browsers using JavaScript served from any domain.
Schema
The API has a machine-readable JSON schema that describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. You can access the schema using cURL:
$ curl https://api.heroku.com/schema \
-H "Accept: application/vnd.heroku+json; version=3"
{
"description": "The platform API empowers developers to automate, extend and combine Heroku with other services.",
"definitions": {
...
}
}
cURL Examples
cURL examples are provided to facilitate experimentation. Variable values are represented as $SOMETHING
so that you can manipulate them using environment variables. Examples use the -n
option to fetch credentials from a ~/.netrc
file, which should include an entry for api.heroku.com
similar to the following:
machine api.heroku.com
login {your-email}
password {your-api-token}
Because Heroku’s V3 API is only accessible through HTTP Accept
header, it may also be convenient to create a cURL alias for easy access:
alias c3='curl -n -H "Accept: application/vnd.heroku+json; version=3"'
Custom Types
Name | JSON Type | Description |
---|---|---|
date-time | string | timestamp in iso8601 format |
uuid | string | uuid in 8-4-4-4-12 format |
Data Integrity
Both unique id and more human-friendly attributes can be used reference resources. For example you can use name
or id
to refer to an app. Though the human-friendly version may be more convenient, id
should be preferred to avoid ambiguity.
You may pass the If-Match
header with an ETag
value from a previous response to ensure a resource has not changed since you last received it. If the resource has changed, you will receive a 412 Precondition Failed
response. If the resource has not changed, the request will proceed normally.
Errors
Failing responses will have an appropriate status and a JSON body containing more details about a particular error. See error responses for more example ids.
Error Attributes
Name | Type | Description | Example |
---|---|---|---|
id | string | id of error raised | "rate_limit" |
message | string | end user message of error raised | "Your account reached the API limit. Please wait a few minutes before making new requests" |
url | string | reference url with more information about the error | https://devcenter.heroku.com/articles/platform-api-reference#rate-limits |
Note that the url
is included only when relevant and may not be present in the response.
Error Response
HTTP/1.1 429 Too Many Requests
{
"id": "rate_limit",
"message": "Your account reached the API rate limit\nPlease wait a few minutes before making new requests",
"url": "https://devcenter.heroku.com/articles/platform-api-reference#rate-limits"
}
Escaping
Some attributes are text fields. Those fields will not be escaped to prevent XSS flaws. It is up to the client to escape that data.
Methods
Method | Usage |
---|---|
DELETE | used for destroying existing objects |
GET | used for retrieving lists and individual objects |
HEAD | used for retrieving metadata about existing objects |
PATCH | used for updating existing objects |
POST | used for creating new objects |
Method Override
When using a client that does not support all of the methods, you can override by using a POST
and setting the X-Http-Method-Override
header to the desired methed. For instance, to do a PATCH
request, do a POST
with header X-Http-Method-Override: PATCH
.
Parameters
Values that can be provided for an action are divided between optional and required values. The expected type for each value is specified and unlisted values should be considered immutable. Parameters should be JSON encoded and passed in the request body.
Ranges
List requests will return a Content-Range
header indicating the range of values returned. Large lists may require additional requests to retrieve. If a list response has been truncated you will receive a 206 Partial Content
status and the Next-Range
header set. To retrieve the next range, repeat the request with the Range
header set to the value of the previous request’s Next-Range
header.
The number of values returned in a range can be controlled using a max
key in the Range
header. For example, to get only the first 10 values, set this header: Range: id ..; max=10;
. max
can also be passed when iterating over Next-Range
. The default page size is 200 and maximum page size is 1000.
The property used to sort values in a list response can be changed. The default property is id
, as in Range: id ..;
. To learn what other properties you can use to sort a list response, inspect the Accept-Ranges
headers. For the apps
resource, for example, you can sort on either id
or name
:
$ curl -i -n -X GET https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"
...
Accept-Ranges: id, name
...
The default sort order for resource lists responses is ascending. You can opt for descending sort order by passing a order
key in the range header:
$ curl -i -n -X GET https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3" -H "Range: name ..; order=desc;"
Combining with the max
key would look like this:
$ curl -i -n -X GET https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Range: name ..; order=desc,max=10;"
Rate Limits
The API limits the number of requests each user can make per hour to protect against abuse and buggy code. Each account has a pool of request tokens that can hold at most 4500 tokens. Each API call removes one token from the pool. Tokens are added to the account pool at a rate of roughly 75 per minute (or 4500 per hour), up to a maximum of 4500. If no tokens remain, further calls will return 429 Too Many Requests
until more tokens become available.
You can use the RateLimit-Remaining
response header to check your current token count. You can also query the rate limit endpoint to get your token count. Requests to the rate limit endpoint do not count toward the limit. If you find your account is being rate limited but don’t know the cause, consider cycling your API key on the account page on Heroku dashboard.
Request Id
Each API response contains a unique request id in the Request-Id
header to facilitate tracking. When reporting issues, providing this value makes it easier to pinpoint problems and provide solutions more quickly.
Responses
Values returned by the API are split into a section with example status code and relevant headers (with common http headers omitted) and a section with an example JSON body (if any).
Response Headers
Header | Description |
---|---|
RateLimit-Remaining | allowed requests remaining in current interval |
Stability
Each resource in the Heroku Platform API Schema is annotated with a stability
attribute, which will be set to one of three values: prototype
, development
, or production
.
This attribute reflects the change management policy in place for the resource. For a full explanation of these policies, please see the Dev Center API compatibility article.
Statuses
The result of responses can be determined by returned status.
Successful Responses
Status | Description |
---|---|
200 OK | request succeeded |
201 Created | resource created, for example a new app was created or an add-on was provisioned |
202 Accepted | request accepted, but the processing has not been completed |
206 Partial Content | request succeeded, but this is only a partial response, see ranges |
Error Responses
Error responses can be divided in to two classes. Client errors result from malformed requests and should be addressed by the client. Heroku errors result from problems on the server side and must be addressed internally.
Client Error Responses
Status | Error ID | Description |
---|---|---|
400 Bad Request | bad_request |
request invalid, validate usage and try again |
401 Unauthorized | unauthorized |
request not authenticated, API token is missing, invalid or expired |
402 Payment Required | delinquent |
either the account has become delinquent as a result of non-payment, or the account’s payment method must be confirmed to continue |
403 Forbidden | forbidden |
request not authorized, provided credentials do not provide access to specified resource |
403 Forbidden | suspended |
request not authorized, account or application was suspended. |
404 Not Found | not_found |
request failed, the specified resource does not exist |
406 Not Acceptable | not_acceptable |
request failed, set Accept: application/vnd.heroku+json; version=3 header and try again |
409 Conflict | conflict |
request failed, see response body for suggested resolution |
410 Gone | gone |
requested resource can no longer be found at this location, see the Platform API Reference for alternatives. |
416 Requested Range Not Satisfiable | requested_range_not_satisfiable |
request failed, validate Content-Range header and try again |
422 Unprocessable Entity | invalid_params |
request failed, validate parameters try again |
422 Unprocessable Entity | verification_needed |
request failed, enter billing information in the Heroku Dashboard before utilizing resources. |
429 Too Many Requests | rate_limit |
request failed, wait for rate limits to reset and try again, see rate limits |
Heroku Error Responses
Status | Description |
---|---|
500 Internal Server Error | error occurred, we are notified, but contact support if the issue persists |
503 Service Unavailable | API is unavailable, check response body or Heroku status for details |
Versioning
The current version of the API is version 3. See the API compatibility policy article for details on versioning.
Account
Stability: production
An account represents an individual signed up to use the Heroku platform.
Attributes
Name | Type | Description | Example |
---|---|---|---|
allow_tracking | boolean | whether to allow third party web activity tracking default: true |
true |
beta | boolean | whether allowed to utilize beta Heroku features | false |
country_of_residence | nullable string | country where account owner resides | "United States" |
created_at | date-time | when account was created | "2012-01-01T12:00:00Z" |
default_organization | nullable object | team selected by default | null |
default_organization:id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
default_organization:name | string | unique name of team | "example" |
default_team | nullable object | team selected by default | null |
default_team:id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
default_team:name | string | unique name of team | "example" |
delinquent_at | nullable date-time | when account became delinquent | "2012-01-01T12:00:00Z" |
unique email address of account | "username@example.com" |
||
federated | boolean | whether the user is federated and belongs to an Identity Provider | false |
id | uuid | unique identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider | nullable object | Identity Provider details for federated users. | null |
identity_provider:id | uuid | unique identifier of this identity provider | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:name | string | user-friendly unique identifier for this identity provider | "acme-sso" |
identity_provider:organization:name | string | unique name of team | "example" |
identity_provider:owner:id | uuid | unique identifier of the owner | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:owner:name | string | name of the owner | "acme" |
identity_provider:owner:type | string | type of the owner one of: "team" or "enterprise-account" |
"team" |
identity_provider:team:name | string | unique name of team | "example" |
last_login | nullable date-time | when account last authorized with Heroku | "2012-01-01T12:00:00Z" |
name | nullable string | full name of the account owner | "Tina Edmonds" |
sms_number | nullable string | SMS number of account | "+1 ***-***-1234" |
suspended_at | nullable date-time | when account was suspended | "2012-01-01T12:00:00Z" |
two_factor_authentication | boolean | whether two-factor auth is enabled on the account | false |
updated_at | date-time | when account was updated | "2012-01-01T12:00:00Z" |
verified | boolean | whether account has been verified with billing information | false |
Account Info
Info for account.
GET /account
Curl Example
$ curl -n https://api.heroku.com/account \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Update
Update account.
PATCH /account
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
allow_tracking | boolean | whether to allow third party web activity tracking default: true |
true |
beta | boolean | whether allowed to utilize beta Heroku features | false |
name | nullable string | full name of the account owner | "Tina Edmonds" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/account \
-d '{
"allow_tracking": true,
"beta": false,
"name": "Tina Edmonds"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Delete
Delete account. Note that this action cannot be undone. Note: This endpoint requires the HTTP_HEROKU_PASSWORD or HTTP_HEROKU_PASSWORD_BASE64 header be set correctly for the user account.
DELETE /account
Curl Example
$ curl -n -X DELETE https://api.heroku.com/account \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Info By User
Info for account.
GET /users/{account_email_or_id_or_self}
Curl Example
$ curl -n https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Update By User
Update account.
PATCH /users/{account_email_or_id_or_self}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
allow_tracking | boolean | whether to allow third party web activity tracking default: true |
true |
beta | boolean | whether allowed to utilize beta Heroku features | false |
name | nullable string | full name of the account owner | "Tina Edmonds" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
-d '{
"allow_tracking": true,
"beta": false,
"name": "Tina Edmonds"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Delete By User
Delete account. Note that this action cannot be undone. Note: This endpoint requires the HTTP_HEROKU_PASSWORD or HTTP_HEROKU_PASSWORD_BASE64 header be set correctly for the user account.
DELETE /users/{account_email_or_id_or_self}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Delinquency
Stability: development
A Heroku account becomes delinquent due to non-payment. We suspend and delete delinquent accounts if their invoices remain unpaid.
Attributes
Name | Type | Description | Example |
---|---|---|---|
scheduled_deletion_time | nullable date-time | scheduled time of when we will delete your account due to delinquency | "2024-01-01T12:00:00Z" |
scheduled_suspension_time | nullable date-time | scheduled time of when we will suspend your account due to delinquency | "2024-01-01T12:00:00Z" |
Account Delinquency Info
Account delinquency information.
GET /account/delinquency
Curl Example
$ curl -n https://api.heroku.com/account/delinquency \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"scheduled_suspension_time": "2024-01-01T12:00:00Z",
"scheduled_deletion_time": "2024-01-01T12:00:00Z"
}
Account Feature
Stability: production
An account feature represents a Heroku labs capability that can be enabled or disabled for an account on Heroku.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when account feature was created | "2012-01-01T12:00:00Z" |
description | string | description of account feature | "Causes account to example." |
display_name | string | user readable feature name | "My Feature" |
doc_url | string | documentation URL of account feature | "http://devcenter.heroku.com/articles/example" |
enabled | boolean | whether or not account feature has been enabled | true |
feedback_email | string | e-mail to send feedback about the feature | "feedback@heroku.com" |
id | uuid | unique identifier of account feature | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name of account feature | "name" |
state | string | state of account feature | "public" |
updated_at | date-time | when account feature was updated | "2012-01-01T12:00:00Z" |
Account Feature Info
Info for an existing account feature.
GET /account/features/{account_feature_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/account/features/$ACCOUNT_FEATURE_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
Account Feature List
List existing account features.
Acceptable order values for the Range header are id
or name
.
GET /account/features
Curl Example
$ curl -n https://api.heroku.com/account/features \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
]
Account Feature Update
Update an existing account feature.
PATCH /account/features/{account_feature_id_or_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
enabled | boolean | whether or not account feature has been enabled | true |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/account/features/$ACCOUNT_FEATURE_ID_OR_NAME \
-d '{
"enabled": true
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
Add-on
Stability: production
Add-ons represent add-ons that have been provisioned and attached to one or more apps.
Attributes
Name | Type | Description | Example |
---|---|---|---|
actions:action | string | identifier of the action to take that is sent via SSO | "example" |
actions:id | uuid | a unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
actions:label | string | the display text shown in Dashboard | "Example" |
actions:requires_owner | boolean | if the action requires the user to own the app | true |
actions:url | string | absolute URL to use instead of an action | "http://example.com?resource_id=:resource_id" |
addon_service | string | Add-on services represent add-ons that may be provisioned for apps. Endpoints under add-on services can be accessed without authentication. | |
app:id | uuid | unique identifier of app | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | unique name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
billed_price | nullable object | billed price | null |
billed_price:cents | integer | price in cents per unit of plan | 0 |
billed_price:contract | boolean | price is negotiated in a contract outside of monthly add-on billing | false |
billed_price:unit | string | unit of price for plan | "month" |
billing_entity:id | uuid | unique identifier of the billing entity | "01234567-89ab-cdef-0123-456789abcdef" |
billing_entity:name | string | name of the billing entity | "example" |
billing_entity:type | string | type of Object of the billing entity; new types allowed at any time. one of: "app" or "team" |
"app" |
config_vars | array | config vars exposed to the owning app by this add-on | ["FOO","BAZ"] |
created_at | date-time | when add-on was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of add-on | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$ |
"acme-inc-primary-database" |
plan | string | Plans represent different configurations of add-ons that may be added to apps. Endpoints under add-on services can be accessed without authentication. | |
provider_id | string | id of this add-on with its provider | "abcd1234" |
provision_message | string | A provision message | "example" |
state | string | state in the add-on’s lifecycle one of: "provisioning" or "provisioned" or "deprovisioned" |
"provisioned" |
updated_at | date-time | when add-on was updated | "2012-01-01T12:00:00Z" |
web_url | nullable uri | URL for logging into web interface of add-on (e.g. a dashboard) | "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef" |
Add-on List
List all existing add-ons.
Acceptable order values for the Range header are id
or name
.
GET /addons
Curl Example
$ curl -n https://api.heroku.com/addons \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Info
Info for an existing add-on.
GET /addons/{add_on_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Create
Create a new add-on.
POST /apps/{app_id_or_name}/addons
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
plan | string | unique identifier or name of this plan | "01234567-89ab-cdef-0123-456789abcdef" or "heroku-postgresql:dev" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
attachment:name | string | unique name for this add-on attachment to this app | "DATABASE" |
config | object | custom add-on provisioning options | {"db-version":"1.2.3"} |
confirm | string | name of billing entity for confirmation | "example" |
name | string | globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$ |
"acme-inc-primary-database" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/addons \
-d '{
"attachment": {
"name": "DATABASE_FOLLOWER"
},
"config": {
"db-version": "1.2.3"
},
"confirm": "example",
"plan": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Delete
Delete an existing add-on.
DELETE /apps/{app_id_or_name}/addons/{add_on_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADD_ON_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Info By App
Info for an existing add-on.
GET /apps/{app_id_or_name}/addons/{add_on_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADD_ON_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on List By App
List existing add-ons for an app.
Acceptable order values for the Range header are id
or name
.
GET /apps/{app_id_or_name}/addons
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addons \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Update
Change add-on plan. Some add-ons may not support changing plans. In that case, an error will be returned.
PATCH /apps/{app_id_or_name}/addons/{add_on_id_or_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
plan | string | unique identifier or name of this plan | "01234567-89ab-cdef-0123-456789abcdef" or "heroku-postgresql:dev" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$ |
"acme-inc-primary-database" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADD_ON_ID_OR_NAME \
-d '{
"name": "acme-inc-primary-database",
"plan": "01234567-89ab-cdef-0123-456789abcdef"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on List By User
List all existing add-ons a user has access to
Acceptable order values for the Range header are id
or name
.
GET /users/{account_email_or_id_or_self}/addons
Curl Example
$ curl -n https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF/addons \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on List By Team
List add-ons used across all Team apps
Acceptable order values for the Range header are id
or name
.
GET /teams/{team_name_or_id}/addons
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/addons \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Resolution
Resolve an add-on from a name, optionally passing an app name. If there are matches it returns at least one add-on (exact match) or many.
POST /actions/addons/resolve
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
addon | string | globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$ |
"acme-inc-primary-database" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
addon_service | string | unique name of this add-on-service | "heroku-postgresql" |
app | string | unique name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
Curl Example
$ curl -n -X POST https://api.heroku.com/actions/addons/resolve \
-d '{
"addon": "acme-inc-primary-database",
"app": "example",
"addon_service": "heroku-postgresql"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Action
Stability: development
Add-on Actions are lifecycle operations for add-on provisioning and deprovisioning. They allow add-on providers to (de)provision add-ons in the background and then report back when (de)provisioning is complete.
Add-on Action Provision
Mark an add-on as provisioned for use.
POST /addons/{add_on_id_or_name}/actions/provision
Curl Example
$ curl -n -X POST https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/actions/provision \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Action Deprovision
Mark an add-on as deprovisioned.
POST /addons/{add_on_id_or_name}/actions/deprovision
Curl Example
$ curl -n -X POST https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/actions/deprovision \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Attachment
Stability: prototype
An add-on attachment represents a connection between an app and an add-on that it has been given access to.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addon:app:id | uuid | unique identifier of app | "01234567-89ab-cdef-0123-456789abcdef" |
addon:app:name | string | unique name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
addon:id | uuid | unique identifier of add-on | "01234567-89ab-cdef-0123-456789abcdef" |
addon:name | string | globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$ |
"acme-inc-primary-database" |
app:id | uuid | unique identifier of app | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | unique name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
created_at | date-time | when add-on attachment was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of this add-on attachment | "01234567-89ab-cdef-0123-456789abcdef" |
log_input_url | nullable string | URL for add-on partners to write to an add-on’s logs | "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs" |
name | string | unique name for this add-on attachment to this app | "DATABASE" |
namespace | nullable string | attachment namespace | "role:analytics" |
updated_at | date-time | when add-on attachment was updated | "2012-01-01T12:00:00Z" |
web_url | nullable uri | URL for logging into web interface of add-on in attached app context | "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef" |
Add-on Attachment Create
Create a new add-on attachment.
POST /addon-attachments
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
addon | string | unique identifier or globally name of the add-on | "01234567-89ab-cdef-0123-456789abcdef" or "acme-inc-primary-database" |
app | string | unique identifier or name of app | "01234567-89ab-cdef-0123-456789abcdef" or "example" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
confirm | string | name of owning app for confirmation | "example" |
name | string | unique name for this add-on attachment to this app | "DATABASE" |
namespace | nullable string | attachment namespace | "role:analytics" |
Curl Example
$ curl -n -X POST https://api.heroku.com/addon-attachments \
-d '{
"addon": "01234567-89ab-cdef-0123-456789abcdef",
"app": "01234567-89ab-cdef-0123-456789abcdef",
"confirm": "example",
"name": "DATABASE",
"namespace": "role:analytics"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
"log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}
Add-on Attachment Delete
Delete an existing add-on attachment.
DELETE /addon-attachments/{add_on_attachment_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/addon-attachments/$ADD_ON_ATTACHMENT_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
"log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}
Add-on Attachment Info
Info for existing add-on attachment.
GET /addon-attachments/{add_on_attachment_id}
Curl Example
$ curl -n https://api.heroku.com/addon-attachments/$ADD_ON_ATTACHMENT_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
"log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}
Add-on Attachment List
List existing add-on attachments.
The only acceptable order value for the Range header is id
.
GET /addon-attachments
Curl Example
$ curl -n https://api.heroku.com/addon-attachments \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
"log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}
]
Add-on Attachment List by Add-on
List existing add-on attachments for an add-on.
The only acceptable order value for the Range header is id
.
GET /addons/{add_on_id_or_name}/addon-attachments
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/addon-attachments \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
"log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}
]
Add-on Attachment List by App
List existing add-on attachments for an app.
The only acceptable order value for the Range header is id
.
GET /apps/{app_id_or_name}/addon-attachments
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addon-attachments \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
"log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}
]
Add-on Attachment Info by App
Info for existing add-on attachment for an app.
GET /apps/{app_id_or_name}/addon-attachments/{add_on_attachment_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addon-attachments/$ADD_ON_ATTACHMENT_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
"log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}
Add-on Attachment Resolution
Resolve an add-on attachment from a name, optionally passing an app name. If there are matches it returns at least one add-on attachment (exact match) or many.
POST /actions/addon-attachments/resolve
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
addon_attachment | string | unique name for this add-on attachment to this app | "DATABASE" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
addon_service | string | unique name of this add-on-service | "heroku-postgresql" |
app | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
Curl Example
$ curl -n -X POST https://api.heroku.com/actions/addon-attachments/resolve \
-d '{
"addon_attachment": "DATABASE",
"app": "example",
"addon_service": "heroku-postgresql"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef",
"log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
}
]
Add-on Config
Stability: development
Configuration of an Add-on
Attributes
Name | Type | Description | Example |
---|---|---|---|
name | string | unique name of the config | "FOO" |
value | nullable string | value of the config | "bar" |
Add-on Config List
Get an add-on’s config. Accessible by customers with access and by the add-on partner providing this add-on.
The only acceptable order value for the Range header is name
.
GET /addons/{add_on_id_or_name}/config
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/config \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"name": "FOO",
"value": "bar"
}
]
Add-on Config Update
Update an add-on’s config. Can only be accessed by the add-on partner providing this add-on.
PATCH /addons/{add_on_id_or_name}/config
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
config | array | [{"name":"FOO","value":"bar"}] |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/config \
-d '{
"config": [
{
"name": "FOO",
"value": "bar"
}
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"name": "FOO",
"value": "bar"
}
]
Add-on Plan Action
Stability: development
Add-on Plan Actions are Provider functionality for specific add-on installations
Attributes
Name | Type | Description | Example |
---|---|---|---|
action | string | identifier of the action to take that is sent via SSO | "example" |
id | uuid | a unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
label | string | the display text shown in Dashboard | "Example" |
requires_owner | boolean | if the action requires the user to own the app | true |
url | string | absolute URL to use instead of an action | "http://example.com?resource_id=:resource_id" |
Add-on Region Capability
Stability: production
Add-on region capabilities represent the relationship between an Add-on Service and a specific Region. Only Beta and GA add-ons are returned by these endpoints.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addon_service:cli_plugin_name | nullable string | npm package name of the add-on service’s Heroku CLI plugin | "heroku-papertrail" |
addon_service:created_at | date-time | when add-on-service was created | "2012-01-01T12:00:00Z" |
addon_service:human_name | string | human-readable name of the add-on service provider | "Heroku Postgres" |
addon_service:id | uuid | unique identifier of this add-on-service | "01234567-89ab-cdef-0123-456789abcdef" |
addon_service:name | string | unique name of this add-on-service | "heroku-postgresql" |
addon_service:state | string | release status for add-on service one of: "alpha" or "beta" or "ga" or "shutdown" |
"ga" |
addon_service:supports_multiple_installations | boolean | whether or not apps can have access to more than one instance of this add-on at the same time | false |
addon_service:supports_sharing | boolean | whether or not apps can have access to add-ons billed to a different app | false |
addon_service:updated_at | date-time | when add-on-service was updated | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of this add-on-region-capability | "01234567-89ab-cdef-0123-456789abcdef" |
region:country | string | country where the region exists | "United States" |
region:created_at | date-time | when region was created | "2012-01-01T12:00:00Z" |
region:description | string | description of region | "United States" |
region:id | uuid | unique identifier of region | "01234567-89ab-cdef-0123-456789abcdef" |
region:locale | string | area in the country where the region exists | "Virginia" |
region:name | string | unique name of region | "us" |
region:private_capable | boolean | whether or not region is available for creating a Private Space | false |
region:provider:name | string | name of provider | "amazon-web-services" |
region:provider:region | string | region name used by provider one of: "ap-south-1" or "eu-west-1" or "ap-southeast-1" or "ap-southeast-2" or "eu-central-1" or "eu-west-2" or "ap-northeast-2" or "ap-northeast-1" or "us-east-1" or "sa-east-1" or "us-west-1" or "us-west-2" or "ca-central-1" |
"us-east-1" |
region:updated_at | date-time | when region was updated | "2012-01-01T12:00:00Z" |
supports_private_networking | boolean | whether the add-on can be installed to a Space | true |
Add-on Region Capability List
List all existing add-on region capabilities.
The only acceptable order value for the Range header is id
.
GET /addon-region-capabilities
Curl Example
$ curl -n https://api.heroku.com/addon-region-capabilities \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"supports_private_networking": true,
"addon_service": {
"cli_plugin_name": "heroku-papertrail",
"created_at": "2012-01-01T12:00:00Z",
"human_name": "Heroku Postgres",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"state": "ga",
"supports_multiple_installations": false,
"supports_sharing": false,
"updated_at": "2012-01-01T12:00:00Z"
},
"region": {
"country": "United States",
"created_at": "2012-01-01T12:00:00Z",
"description": "United States",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"locale": "Virginia",
"name": "us",
"private_capable": false,
"provider": {
"name": "amazon-web-services",
"region": "us-east-1"
},
"updated_at": "2012-01-01T12:00:00Z"
}
}
]
Add-on Region Capability List by Add-on Service
List existing add-on region capabilities for an add-on-service
The only acceptable order value for the Range header is id
.
GET /addon-services/{add_on_service_id_or_name}/region-capabilities
Curl Example
$ curl -n https://api.heroku.com/addon-services/$ADD_ON_SERVICE_ID_OR_NAME/region-capabilities \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"supports_private_networking": true,
"addon_service": {
"cli_plugin_name": "heroku-papertrail",
"created_at": "2012-01-01T12:00:00Z",
"human_name": "Heroku Postgres",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"state": "ga",
"supports_multiple_installations": false,
"supports_sharing": false,
"updated_at": "2012-01-01T12:00:00Z"
},
"region": {
"country": "United States",
"created_at": "2012-01-01T12:00:00Z",
"description": "United States",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"locale": "Virginia",
"name": "us",
"private_capable": false,
"provider": {
"name": "amazon-web-services",
"region": "us-east-1"
},
"updated_at": "2012-01-01T12:00:00Z"
}
}
]
Add-on Region Capability List By Region
List existing add-on region capabilities for a region.
The only acceptable order value for the Range header is id
.
GET /regions/{region_id_or_name}/addon-region-capabilities
Curl Example
$ curl -n https://api.heroku.com/regions/$REGION_ID_OR_NAME/addon-region-capabilities \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"supports_private_networking": true,
"addon_service": {
"cli_plugin_name": "heroku-papertrail",
"created_at": "2012-01-01T12:00:00Z",
"human_name": "Heroku Postgres",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"state": "ga",
"supports_multiple_installations": false,
"supports_sharing": false,
"updated_at": "2012-01-01T12:00:00Z"
},
"region": {
"country": "United States",
"created_at": "2012-01-01T12:00:00Z",
"description": "United States",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"locale": "Virginia",
"name": "us",
"private_capable": false,
"provider": {
"name": "amazon-web-services",
"region": "us-east-1"
},
"updated_at": "2012-01-01T12:00:00Z"
}
}
]
Add-on Service
Stability: production
Add-on services represent add-ons that may be provisioned for apps. Endpoints under add-on services can be accessed without authentication.
Attributes
Name | Type | Description | Example |
---|---|---|---|
cli_plugin_name | nullable string | npm package name of the add-on service’s Heroku CLI plugin | "heroku-papertrail" |
created_at | date-time | when add-on-service was created | "2012-01-01T12:00:00Z" |
human_name | string | human-readable name of the add-on service provider | "Heroku Postgres" |
id | uuid | unique identifier of this add-on-service | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name of this add-on-service | "heroku-postgresql" |
state | string | release status for add-on service one of: "alpha" or "beta" or "ga" or "shutdown" |
"ga" |
supports_multiple_installations | boolean | whether or not apps can have access to more than one instance of this add-on at the same time | false |
supports_sharing | boolean | whether or not apps can have access to add-ons billed to a different app | false |
updated_at | date-time | when add-on-service was updated | "2012-01-01T12:00:00Z" |
Add-on Service Info
Info for existing add-on-service.
GET /addon-services/{add_on_service_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/addon-services/$ADD_ON_SERVICE_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"cli_plugin_name": "heroku-papertrail",
"created_at": "2012-01-01T12:00:00Z",
"human_name": "Heroku Postgres",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"state": "ga",
"supports_multiple_installations": false,
"supports_sharing": false,
"updated_at": "2012-01-01T12:00:00Z"
}
Add-on Service List
List existing add-on-services.
Acceptable order values for the Range header are id
or name
.
GET /addon-services
Curl Example
$ curl -n https://api.heroku.com/addon-services \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"cli_plugin_name": "heroku-papertrail",
"created_at": "2012-01-01T12:00:00Z",
"human_name": "Heroku Postgres",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"state": "ga",
"supports_multiple_installations": false,
"supports_sharing": false,
"updated_at": "2012-01-01T12:00:00Z"
}
]
Add-on Webhook
Stability: production
Represents the details of a webhook subscription
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when the webhook was created | "2015-01-01T12:00:00Z" |
id | uuid | the webhook’s unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
include | array | the entities that the subscription provides notifications for | ["api:release"] |
level | string | if notify , Heroku makes a single, fire-and-forget delivery attempt. If sync , Heroku attempts multiple deliveries until the request is successful or a limit is reachedone of: "notify" or "sync" |
"notify" |
updated_at | date-time | when the webhook was updated | "2015-01-01T12:00:00Z" |
url | uri | the URL where the webhook’s notification requests are sent |
Add-on Webhook Create
Create an add-on webhook subscription. Can only be accessed by the add-on partner providing this add-on.
POST /addons/{add_on_id_or_name}/webhooks
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
include | array | the entities that the subscription provides notifications for | ["api:release"] |
level | string | if notify , Heroku makes a single, fire-and-forget delivery attempt. If sync , Heroku attempts multiple deliveries until the request is successful or a limit is reachedone of: "notify" or "sync" |
"notify" |
url | uri | the URL where the webhook’s notification requests are sent |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
authorization | nullable string | a custom Authorization header that Heroku will include with all webhook notifications |
"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3" |
secret | nullable string | a value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s Heroku-Webhook-Hmac-SHA256 header) |
"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad" |
Curl Example
$ curl -n -X POST https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks \
-d '{
"authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
"include": [
"api:release"
],
"level": "notify",
"secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
"url": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
Add-on Webhook Delete
Removes an add-on webhook subscription. Can only be accessed by the add-on partner providing this add-on.
DELETE /addons/{add_on_id_or_name}/webhooks/{app_webhook_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
Add-on Webhook Info
Returns the info for an add-on webhook subscription. Can only be accessed by the add-on partner providing this add-on.
GET /addons/{add_on_id_or_name}/webhooks/{app_webhook_id}
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
Add-on Webhook List
List all webhook subscriptions for a particular add-on. Can only be accessed by the add-on partner providing this add-on.
GET /addons/{add_on_id_or_name}/webhooks
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
]
Add-on Webhook Update
Updates the details of an add-on webhook subscription. Can only be accessed by the add-on partner providing this add-on.
PATCH /addons/{add_on_id_or_name}/webhooks/{app_webhook_id}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
authorization | nullable string | a custom Authorization header that Heroku will include with all webhook notifications |
"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3" |
include | array | the entities that the subscription provides notifications for | ["api:release"] |
level | string | if notify , Heroku makes a single, fire-and-forget delivery attempt. If sync , Heroku attempts multiple deliveries until the request is successful or a limit is reachedone of: "notify" or "sync" |
"notify" |
secret | nullable string | a value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s Heroku-Webhook-Hmac-SHA256 header) |
"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad" |
url | uri | the URL where the webhook’s notification requests are sent |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
-d '{
"authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
"include": [
"api:release"
],
"level": "notify",
"secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
"url": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
Add-on Webhook Delivery
Stability: production
Represents the delivery of a webhook notification, including its current status.
Add-on Webhook Delivery Info
Returns the info for an existing delivery. Can only be accessed by the add-on partner providing this add-on.
GET /addons/{add_on_id_or_name}/webhook-deliveries/{app_webhook_delivery_id}
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhook-deliveries/$APP_WEBHOOK_DELIVERY_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2015-01-01T12:00:00Z",
"event": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": "api:release"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"num_attempts": 42,
"next_attempt_at": "2015-01-01T12:00:00Z",
"last_attempt": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"code": 42,
"error_class": "example",
"status": "scheduled",
"created_at": "2015-01-01T12:00:00Z",
"updated_at": "2015-01-01T12:00:00Z"
},
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"webhook": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"level": "notify"
}
}
Add-on Webhook Delivery List
Lists existing deliveries for an add-on. Can only be accessed by the add-on partner providing this add-on.
GET /addons/{add_on_id_or_name}/webhook-deliveries
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhook-deliveries \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2015-01-01T12:00:00Z",
"event": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": "api:release"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"num_attempts": 42,
"next_attempt_at": "2015-01-01T12:00:00Z",
"last_attempt": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"code": 42,
"error_class": "example",
"status": "scheduled",
"created_at": "2015-01-01T12:00:00Z",
"updated_at": "2015-01-01T12:00:00Z"
},
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"webhook": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"level": "notify"
}
}
]
Add-on Webhook Event
Stability: production
Represents a webhook event that occurred.
Add-on Webhook Event Info
Returns the info for a specified webhook event. Can only be accessed by the add-on partner providing this add-on.
GET /addons/{add_on_id_or_name}/webhook-events/{app_webhook_event_id}
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhook-events/$APP_WEBHOOK_EVENT_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": "api:release",
"payload": {
"action": "create",
"actor": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"data": null,
"previous_data": null,
"resource": "release",
"version": "1"
},
"updated_at": "2015-01-01T12:00:00Z"
}
Add-on Webhook Event List
Lists existing webhook events for an add-on. Can only be accessed by the add-on partner providing this add-on.
GET /addons/{add_on_id_or_name}/webhook-events
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/webhook-events \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": "api:release",
"payload": {
"action": "create",
"actor": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"data": null,
"previous_data": null,
"resource": "release",
"version": "1"
},
"updated_at": "2015-01-01T12:00:00Z"
}
]
Allowed Add-on Service
Stability: prototype
Entities that have been allowed to be used by a Team
Attributes
Name | Type | Description | Example |
---|---|---|---|
added_at | date-time | when the add-on service was allowed | "2012-01-01T12:00:00Z" |
added_by:email | nullable email | unique email address of account | "username@example.com" |
added_by:id | nullable uuid | unique identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
addon_service:human_name | string | human-readable name of the add-on service provider | "Heroku Postgres" |
addon_service:id | uuid | unique identifier of this add-on-service | "01234567-89ab-cdef-0123-456789abcdef" |
addon_service:name | string | unique name of this add-on-service | "heroku-postgresql" |
id | uuid | unique identifier for this allowed add-on service record | "01234567-89ab-cdef-0123-456789abcdef" |
Allowed Add-on Service List By Team
List all allowed add-on services for a team
Acceptable order values for the Range header are id
or name
.
GET /teams/{team_name_or_id}/allowed-addon-services
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/allowed-addon-services \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"added_at": "2012-01-01T12:00:00Z",
"added_by": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"human_name": "Heroku Postgres"
},
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
]
Allowed Add-on Service Create By Team
Allow an Add-on Service
POST /teams/{team_name_or_id}/allowed-addon-services
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
addon_service | string | name of the add-on service to allow | "heroku-postgresql" |
Curl Example
$ curl -n -X POST https://api.heroku.com/teams/$TEAM_NAME_OR_ID/allowed-addon-services \
-d '{
"addon_service": "heroku-postgresql"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"added_at": "2012-01-01T12:00:00Z",
"added_by": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"human_name": "Heroku Postgres"
},
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
]
Allowed Add-on Service Delete By Team
Remove an allowed add-on service
DELETE /teams/{team_name_or_id}/allowed-addon-services/{allowed_add_on_service_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/teams/$TEAM_NAME_OR_ID/allowed-addon-services/$ALLOWED_ADD_ON_SERVICE_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"added_at": "2012-01-01T12:00:00Z",
"added_by": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql",
"human_name": "Heroku Postgres"
},
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
App
Stability: production
An app represents the program that you would like to deploy and run on Heroku.
Attributes
Name | Type | Description | Example |
---|---|---|---|
acm | boolean | ACM status of this app | false |
archived_at | nullable date-time | when app was archived | "2012-01-01T12:00:00Z" |
build_stack:id | uuid | unique identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
build_stack:name | string | unique name of stack | "heroku-18" |
buildpack_provided_description | nullable string | description from buildpack of app | "Ruby/Rack" |
created_at | date-time | when app was created | "2012-01-01T12:00:00Z" |
git_url | string | git repo URL of app pattern: ^https://git.heroku.com/[a-z][a-z0-9-]{2,29}.git$ |
"https://git.heroku.com/example.git" |
id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
internal_routing | nullable boolean | describes whether a Private Spaces app is externally routable or not | false |
maintenance | boolean | maintenance status of app | false |
name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
organization | nullable object | identity of team | null |
organization:id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
organization:name | string | unique name of team | "example" |
owner:email | unique email address of account | "username@example.com" |
|
owner:id | uuid | unique identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
region:id | uuid | unique identifier of region | "01234567-89ab-cdef-0123-456789abcdef" |
region:name | string | unique name of region | "us" |
released_at | nullable date-time | when app was released | "2012-01-01T12:00:00Z" |
repo_size | nullable integer | git repo size in bytes of app | 0 |
slug_size | nullable integer | slug size in bytes of app | 0 |
space | nullable object | identity of space | null |
space:id | uuid | unique identifier of space | "01234567-89ab-cdef-0123-456789abcdef" |
space:name | string | unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$ |
"nasa" |
space:shield | boolean | true if this space has shield enabled | true |
stack:id | uuid | unique identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
stack:name | string | unique name of stack | "heroku-18" |
team | nullable object | identity of team | null |
team:id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
team:name | string | unique name of team | "example" |
updated_at | date-time | when app was updated | "2012-01-01T12:00:00Z" |
web_url | nullable uri | web URL of app pattern: ^https?://[a-z][a-z0-9-]{3,43}.herokuapp.com/$ |
"https://example.herokuapp.com/" |
App Create
Create a new app.
POST /apps
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
feature_flags | array | unique name of app feature | ["name"] |
name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
region | string | unique identifier or name of region | "01234567-89ab-cdef-0123-456789abcdef" or "us" |
stack | string | unique name or identifier of stack | "heroku-18" or "01234567-89ab-cdef-0123-456789abcdef" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps \
-d '{
"name": "example",
"region": "01234567-89ab-cdef-0123-456789abcdef",
"stack": "01234567-89ab-cdef-0123-456789abcdef",
"feature_flags": [
"name"
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Delete
Delete an existing app.
DELETE /apps/{app_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Info
Info for existing app.
GET /apps/{app_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App List
List existing apps.
Acceptable order values for the Range header are id
, name
or updated_at
.
GET /apps
Curl Example
$ curl -n https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name, updated_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
App List Owned and Collaborated
List owned and collaborated apps (excludes team apps).
Acceptable order values for the Range header are id
, name
or updated_at
.
GET /users/{account_email_or_id_or_self}/apps
Curl Example
$ curl -n https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF/apps \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name, updated_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
App Update
Update an existing app.
PATCH /apps/{app_id_or_name}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
build_stack | string | unique name or identifier of stack | "heroku-18" or "01234567-89ab-cdef-0123-456789abcdef" |
maintenance | boolean | maintenance status of app | false |
name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME \
-d '{
"build_stack": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Enable ACM
Enable ACM flag for an app
POST /apps/{app_id_or_name}/acm
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/acm \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Disable ACM
Disable ACM flag for an app
DELETE /apps/{app_id_or_name}/acm
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/acm \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Refresh ACM
Refresh ACM for an app
PATCH /apps/{app_id_or_name}/acm
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/acm \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Feature
Stability: production
An app feature represents a Heroku labs capability that can be enabled or disabled for an app on Heroku.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when app feature was created | "2012-01-01T12:00:00Z" |
description | string | description of app feature | "Causes app to example." |
display_name | string | user readable feature name | "My Feature" |
doc_url | string | documentation URL of app feature | "http://devcenter.heroku.com/articles/example" |
enabled | boolean | whether or not app feature has been enabled | true |
feedback_email | string | e-mail to send feedback about the feature | "feedback@heroku.com" |
id | uuid | unique identifier of app feature | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name of app feature | "name" |
state | string | state of app feature | "public" |
updated_at | date-time | when app feature was updated | "2012-01-01T12:00:00Z" |
App Feature Info
Info for an existing app feature.
GET /apps/{app_id_or_name}/features/{app_feature_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/features/$APP_FEATURE_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes app to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
App Feature List
List existing app features.
Acceptable order values for the Range header are id
or name
.
GET /apps/{app_id_or_name}/features
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/features \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes app to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
]
App Feature Update
Update an existing app feature.
PATCH /apps/{app_id_or_name}/features/{app_feature_id_or_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
enabled | boolean | whether or not app feature has been enabled | true |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/features/$APP_FEATURE_ID_OR_NAME \
-d '{
"enabled": true
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes app to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
App Setup
Stability: production
An app setup represents an app on Heroku that is setup using an environment, addons, and scripts described in an app.json manifest file.
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
build | nullable object | identity and status of build | null |
build:id | uuid | unique identifier of build | "01234567-89ab-cdef-0123-456789abcdef" |
build:output_stream_url | string | Build process output will be available from this URL as a stream. The stream is available as either text/plain or text/event-stream . Clients should be prepared to handle disconnects and can resume the stream by sending a Range header (for text/plain ) or a Last-Event-Id header (for text/event-stream ). |
"https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef" |
build:status | string | status of build one of: "failed" or "pending" or "succeeded" |
"succeeded" |
created_at | date-time | when app setup was created | "2012-01-01T12:00:00Z" |
failure_message | nullable string | reason that app setup has failed | "invalid app.json" |
id | uuid | unique identifier of app setup | "01234567-89ab-cdef-0123-456789abcdef" |
manifest_errors | array | errors associated with invalid app.json manifest file | ["config var FOO is required"] |
postdeploy | nullable object | result of postdeploy script | null |
postdeploy:exit_code | integer | The exit code of the postdeploy script | 1 |
postdeploy:output | string | output of the postdeploy script | "assets precompiled" |
resolved_success_url | nullable string | fully qualified success url | "https://example.herokuapp.com/welcome" |
status | string | the overall status of app setup one of: "failed" or "pending" or "succeeded" |
"failed" |
updated_at | date-time | when app setup was updated | "2012-01-01T12:00:00Z" |
App Setup Create
Create a new app setup from a gzipped tar archive containing an app.json manifest file.
POST /app-setups
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
source_blob:checksum | nullable string | an optional checksum of the gzipped tarball for verifying its integrity | "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" |
source_blob:url | string | URL of gzipped tarball of source code containing app.json manifest file | "https://example.com/source.tgz?token=xyz" |
source_blob:version | nullable string | Version of the gzipped tarball. | "v1.3.0" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
app:locked | boolean | are other team members forbidden from joining this app. | false |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
app:organization | string | unique name of team | "example" |
app:personal | boolean | force creation of the app in the user account even if a default team is set. | false |
app:region | string | name of region | "us" |
app:space | string | unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$ |
"nasa" |
app:stack | string | unique name | "heroku-18" |
overrides:buildpacks | array | overrides the buildpacks specified in the app.json manifest file | [{"url":"https://example.com/buildpack.tgz"}] |
overrides:env | object | overrides of the env specified in the app.json manifest file | {"FOO":"bar","BAZ":"qux"} |
Curl Example
$ curl -n -X POST https://api.heroku.com/app-setups \
-d '{
"app": {
"locked": false,
"name": "example",
"organization": "example",
"personal": false,
"region": "us",
"space": "nasa",
"stack": "heroku-18"
},
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0"
},
"overrides": {
"buildpacks": [
{
"url": "https://example.com/buildpack.tgz"
}
],
"env": {
"FOO": "bar",
"BAZ": "qux"
}
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T12:00:00Z",
"status": "failed",
"failure_message": "invalid app.json",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"build": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"status": "succeeded",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
},
"manifest_errors": [
"config var FOO is required"
],
"postdeploy": {
"output": "assets precompiled",
"exit_code": 1
},
"resolved_success_url": "https://example.herokuapp.com/welcome"
}
App Setup Info
Get the status of an app setup.
GET /app-setups/{app_setup_id}
Curl Example
$ curl -n https://api.heroku.com/app-setups/$APP_SETUP_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T12:00:00Z",
"status": "failed",
"failure_message": "invalid app.json",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"build": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"status": "succeeded",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
},
"manifest_errors": [
"config var FOO is required"
],
"postdeploy": {
"output": "assets precompiled",
"exit_code": 1
},
"resolved_success_url": "https://example.herokuapp.com/welcome"
}
App Transfer
Stability: production
An app transfer represents a two party interaction for transferring ownership of an app.
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
created_at | date-time | when app transfer was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of app transfer | "01234567-89ab-cdef-0123-456789abcdef" |
owner:email | 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 one of: "pending" or "accepted" or "declined" |
"pending" |
updated_at | date-time | when app transfer was updated | "2012-01-01T12:00:00Z" |
App Transfer Create
Create a new app transfer.
POST /account/app-transfers
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
app | string | unique identifier or name of app | "01234567-89ab-cdef-0123-456789abcdef" or "example" |
recipient | string | unique email address, identifier of an account or Implicit reference to currently authorized user | "username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" or "~" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
silent | boolean | whether to suppress email notification when transferring apps | false |
Curl Example
$ curl -n -X POST https://api.heroku.com/account/app-transfers \
-d '{
"app": "01234567-89ab-cdef-0123-456789abcdef",
"recipient": "01234567-89ab-cdef-0123-456789abcdef",
"silent": false
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"recipient": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"state": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
App Transfer Delete
Delete an existing app transfer
DELETE /account/app-transfers/{app_transfer_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/account/app-transfers/$APP_TRANSFER_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"recipient": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"state": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
App Transfer Info
Info for existing app transfer.
GET /account/app-transfers/{app_transfer_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/account/app-transfers/$APP_TRANSFER_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"recipient": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"state": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
App Transfer List
List existing apps transfers.
Acceptable order values for the Range header are id
or name
.
GET /account/app-transfers
Curl Example
$ curl -n https://api.heroku.com/account/app-transfers \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"recipient": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"state": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
]
App Transfer Update
Update an existing app transfer.
PATCH /account/app-transfers/{app_transfer_id_or_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
state | string | the current state of an app transfer one of: "pending" or "accepted" or "declined" |
"pending" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/account/app-transfers/$APP_TRANSFER_ID_OR_NAME \
-d '{
"state": "pending"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"recipient": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"state": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
App Webhook
Stability: production
Represents the details of a webhook subscription
App Webhook Create
Create an app webhook subscription.
POST /apps/{app_id_or_name}/webhooks
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
include | array | the entities that the subscription provides notifications for | ["api:release"] |
level | string | if notify , Heroku makes a single, fire-and-forget delivery attempt. If sync , Heroku attempts multiple deliveries until the request is successful or a limit is reachedone of: "notify" or "sync" |
"notify" |
url | uri | the URL where the webhook’s notification requests are sent |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
authorization | nullable string | a custom Authorization header that Heroku will include with all webhook notifications |
"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3" |
secret | nullable string | a value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s Heroku-Webhook-Hmac-SHA256 header) |
"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks \
-d '{
"authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
"include": [
"api:release"
],
"level": "notify",
"secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
"url": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
App Webhook Delete
Removes an app webhook subscription.
DELETE /apps/{app_id_or_name}/webhooks/{app_webhook_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
App Webhook Info
Returns the info for an app webhook subscription.
GET /apps/{app_id_or_name}/webhooks/{app_webhook_id}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
App Webhook List
List all webhook subscriptions for a particular app.
The only acceptable order value for the Range header is id
.
GET /apps/{app_id_or_name}/webhooks
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
]
App Webhook Update
Updates the details of an app webhook subscription.
PATCH /apps/{app_id_or_name}/webhooks/{app_webhook_id}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
authorization | nullable string | a custom Authorization header that Heroku will include with all webhook notifications |
"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3" |
include | array | the entities that the subscription provides notifications for | ["api:release"] |
level | string | if notify , Heroku makes a single, fire-and-forget delivery attempt. If sync , Heroku attempts multiple deliveries until the request is successful or a limit is reachedone of: "notify" or "sync" |
"notify" |
secret | nullable string | a value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s Heroku-Webhook-Hmac-SHA256 header) |
"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad" |
url | uri | the URL where the webhook’s notification requests are sent |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks/$APP_WEBHOOK_ID \
-d '{
"authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
"include": [
"api:release"
],
"level": "notify",
"secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
"url": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": [
"api:release"
],
"level": "notify",
"updated_at": "2015-01-01T12:00:00Z",
"url": "example"
}
App Webhook Delivery
Stability: production
Represents the delivery of a webhook notification, including its current status.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when the delivery was created | "2015-01-01T12:00:00Z" |
event:id | uuid | the event’s unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
event:include | string | the type of entity that the event is related to | "api:release" |
id | uuid | the delivery’s unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
last_attempt | nullable object | last attempt of a delivery | null |
last_attempt:code | nullable integer | http response code received during attempt | null |
last_attempt:created_at | date-time | when attempt was created | "2015-01-01T12:00:00Z" |
last_attempt:error_class | nullable string | error class encountered during attempt | null |
last_attempt:id | uuid | unique identifier of attempt | "01234567-89ab-cdef-0123-456789abcdef" |
last_attempt:status | string | status of an attempt one of: "scheduled" or "succeeded" or "failed" |
"scheduled" |
last_attempt:updated_at | date-time | when attempt was updated | "2015-01-01T12:00:00Z" |
next_attempt_at | nullable date-time | when delivery will be attempted again | null |
num_attempts | integer | number of times a delivery has been attempted | 42 |
status | string | the delivery’s status one of: "pending" or "scheduled" or "retrying" or "failed" or "succeeded" |
"pending" |
updated_at | date-time | when the delivery was last updated | "2015-01-01T12:00:00Z" |
webhook:id | uuid | the webhook’s unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
webhook:level | string | if notify , Heroku makes a single, fire-and-forget delivery attempt. If sync , Heroku attempts multiple deliveries until the request is successful or a limit is reachedone of: "notify" or "sync" |
"notify" |
App Webhook Delivery Info
Returns the info for an existing delivery.
GET /apps/{app_id_or_name}/webhook-deliveries/{app_webhook_delivery_id}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-deliveries/$APP_WEBHOOK_DELIVERY_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2015-01-01T12:00:00Z",
"event": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": "api:release"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"num_attempts": 42,
"next_attempt_at": "2015-01-01T12:00:00Z",
"last_attempt": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"code": 42,
"error_class": "example",
"status": "scheduled",
"created_at": "2015-01-01T12:00:00Z",
"updated_at": "2015-01-01T12:00:00Z"
},
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"webhook": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"level": "notify"
}
}
App Webhook Delivery List
Lists existing deliveries for an app.
The only acceptable order value for the Range header is id
.
GET /apps/{app_id_or_name}/webhook-deliveries
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-deliveries \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2015-01-01T12:00:00Z",
"event": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": "api:release"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"num_attempts": 42,
"next_attempt_at": "2015-01-01T12:00:00Z",
"last_attempt": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"code": 42,
"error_class": "example",
"status": "scheduled",
"created_at": "2015-01-01T12:00:00Z",
"updated_at": "2015-01-01T12:00:00Z"
},
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"webhook": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"level": "notify"
}
}
]
App Webhook Event
Stability: production
Represents a webhook event that occurred.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when event was created | "2015-01-01T12:00:00Z" |
id | uuid | the event’s unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
include | string | the type of entity that the event is related to | "api:release" |
payload:action | string | the type of event that occurred | "create" |
payload:actor:email | unique email address | "username@example.com" |
|
payload:actor:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
payload:data | object | the current details of the event | |
payload:previous_data | object | previous details of the event (if any) | |
payload:resource | string | the type of resource associated with the event | "release" |
payload:version | string | the version of the details provided for the event | "1" |
updated_at | date-time | when the event was last updated | "2015-01-01T12:00:00Z" |
App Webhook Event Info
Returns the info for a specified webhook event.
GET /apps/{app_id_or_name}/webhook-events/{app_webhook_event_id}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-events/$APP_WEBHOOK_EVENT_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": "api:release",
"payload": {
"action": "create",
"actor": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"data": null,
"previous_data": null,
"resource": "release",
"version": "1"
},
"updated_at": "2015-01-01T12:00:00Z"
}
App Webhook Event List
Lists existing webhook events for an app.
The only acceptable order value for the Range header is id
.
GET /apps/{app_id_or_name}/webhook-events
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-events \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"include": "api:release",
"payload": {
"action": "create",
"actor": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"data": null,
"previous_data": null,
"resource": "release",
"version": "1"
},
"updated_at": "2015-01-01T12:00:00Z"
}
]
Audit Trail Archive
Stability: production
An audit trail archive represents a monthly json zipped file containing events
Attributes
Name | Type | Description | Example |
---|---|---|---|
checksum | string | checksum for the archive | "example" |
created_at | date-time | when archive was created | "2015-01-01T12:00:00Z" |
month | string | month of the archive one of: "01" or "02" or "03" or "04" or "05" or "06" or "07" or "08" or "09" or "10" or "11" or "12" |
"10" |
size | integer | size of the archive in bytes | 100 |
url | string | url where to download the archive | "example" |
year | integer | year of the archive Range: 2017 <= value |
2019 |
Audit Trail Archive Info
Get archive for a single month.
GET /enterprise-accounts/{enterprise_account_id_or_name}/archives/{archive_year}/{archive_month}
Curl Example
$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/archives/$ARCHIVE_YEAR/$ARCHIVE_MONTH \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2015-01-01T12:00:00Z",
"month": "10",
"year": 2019,
"url": "example",
"checksum": "example",
"size": 100
}
Audit Trail Archive List
List existing archives.
The only acceptable order value for the Range header is id
.
GET /enterprise-accounts/{enterprise_account_id_or_name}/archives
Curl Example
$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/archives \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2015-01-01T12:00:00Z",
"month": "10",
"year": 2019,
"url": "example",
"checksum": "example",
"size": 100
}
]
Audit Trail Event
Stability: production
An audit trail event represents some action on the platform
Attributes
Name | Type | Description | Example |
---|---|---|---|
action | string | action for the event | "example" |
actor:email | "username@example.com" |
||
actor:id | uuid | "01234567-89ab-cdef-0123-456789abcdef" |
|
app:id | uuid | "01234567-89ab-cdef-0123-456789abcdef" |
|
app:name | string | "example" |
|
created_at | date-time | when event was created | "2015-01-01T12:00:00Z" |
data | object | data specific to the event | |
enterprise_account:id | uuid | "01234567-89ab-cdef-0123-456789abcdef" |
|
enterprise_account:name | string | "example" |
|
id | uuid | unique identifier of event | "01234567-89ab-cdef-0123-456789abcdef" |
owner:email | "username@example.com" |
||
owner:id | uuid | "01234567-89ab-cdef-0123-456789abcdef" |
|
request:ip_address | ipv4 | "192.0.2.1" |
|
team:id | uuid | "01234567-89ab-cdef-0123-456789abcdef" |
|
team:name | string | "example" |
|
type | string | type of event | "example" |
Audit Trail Event List
List existing events. Returns all events for one day, defaulting to current day. Order, actor, action, and type, and day query params can be specified as query parameters. For example, ‘/enterprise-accounts/:id/events?order=desc&actor=user@example.com&action=create&type=app&day=2020-09-30’ would return events in descending order and only return app created events by the user with user@example.com email address.
GET /enterprise-accounts/{enterprise_account_id_or_name}/events
Curl Example
$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/events \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "example",
"action": "example",
"actor": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"request": {
"ip_address": "192.0.2.1"
},
"data": null
}
]
Build
Stability: production
A build represents the process of transforming a code tarball into a slug
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
buildpacks | nullable array | buildpacks executed for this build, in order | null |
buildpacks/name | string | Buildpack Registry name of the buildpack for the app | "heroku/ruby" |
buildpacks/url | string | the URL of the buildpack for the app | "https://github.com/heroku/heroku-buildpack-ruby" |
created_at | date-time | when build was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of build | "01234567-89ab-cdef-0123-456789abcdef" |
output_stream_url | string | Build process output will be available from this URL as a stream. The stream is available as either text/plain or text/event-stream . Clients should be prepared to handle disconnects and can resume the stream by sending a Range header (for text/plain ) or a Last-Event-Id header (for text/event-stream ). |
"https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef" |
release | nullable object | release resulting from the build | {"id":"01234567-89ab-cdef-0123-456789abcdef"} |
release:id | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
slug | nullable object | slug created by this build | null |
slug:id | uuid | unique identifier of slug | "01234567-89ab-cdef-0123-456789abcdef" |
source_blob:checksum | nullable string | an optional checksum of the gzipped tarball for verifying its integrity | "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" |
source_blob:url | string | URL where gzipped tar archive of source code for build was downloaded. | "https://example.com/source.tgz?token=xyz" |
source_blob:version | nullable string | Version of the gzipped tarball. | "v1.3.0" |
source_blob:version_description | nullable string | Version description of the gzipped tarball. | "* Fake User: Change session key" |
stack | string | stack of build | "heroku-22" |
status | string | status of build one of: "failed" or "pending" or "succeeded" |
"succeeded" |
updated_at | date-time | when build was updated | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
Build Create
Create a new build.
POST /apps/{app_id_or_name}/builds
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
source_blob:checksum | nullable string | an optional checksum of the gzipped tarball for verifying its integrity | "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" |
source_blob:url | string | URL where gzipped tar archive of source code for build was downloaded. | "https://example.com/source.tgz?token=xyz" |
source_blob:version | nullable string | Version of the gzipped tarball. | "v1.3.0" |
source_blob:version_description | nullable string | Version description of the gzipped tarball. | "* Fake User: Change session key" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
buildpacks | nullable array | buildpacks executed for this build, in order | null |
buildpacks/name | string | Buildpack Registry name of the buildpack for the app | "heroku/ruby" |
buildpacks/url | string | the URL of the buildpack for the app | "https://github.com/heroku/heroku-buildpack-ruby" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/builds \
-d '{
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby",
"name": "heroku/ruby"
}
],
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0",
"version_description": "* Fake User: Change session key"
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby",
"name": "heroku/ruby"
}
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0",
"version_description": "* Fake User: Change session key"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stack": "heroku-22",
"status": "succeeded",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
}
}
Build Info
Info for existing build.
GET /apps/{app_id_or_name}/builds/{build_id}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/builds/$BUILD_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby",
"name": "heroku/ruby"
}
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0",
"version_description": "* Fake User: Change session key"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stack": "heroku-22",
"status": "succeeded",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
}
}
Build List
List existing build.
Acceptable order values for the Range header are id
or started_at
.
GET /apps/{app_id_or_name}/builds
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/builds \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, started_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby",
"name": "heroku/ruby"
}
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0",
"version_description": "* Fake User: Change session key"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stack": "heroku-22",
"status": "succeeded",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
}
}
]
Build Delete cache
Destroy a build cache.
DELETE /apps/{app_id_or_name}/build-cache
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/build-cache \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
Build Cancel
Cancel running build.
DELETE /apps/{app_id_or_name}/builds/{build_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/builds/$BUILD_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby",
"name": "heroku/ruby"
}
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0",
"version_description": "* Fake User: Change session key"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stack": "heroku-22",
"status": "succeeded",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
}
}
Buildpack Installations
Stability: production
A buildpack installation represents a buildpack that will be run against an app.
Attributes
Name | Type | Description | Example |
---|---|---|---|
buildpack:name | string | either the Buildpack Registry name or a URL of the buildpack for the app | "heroku/ruby" |
buildpack:url | string | location of the buildpack for the app. Either a url (unofficial buildpacks) or an internal urn (heroku official buildpacks). | "https://github.com/heroku/heroku-buildpack-ruby" |
ordinal | integer | determines the order in which the buildpacks will execute | 0 |
Buildpack Installations Update
Update an app’s buildpack installations.
PUT /apps/{app_id_or_name}/buildpack-installations
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
updates | array | The buildpack attribute can accept a name, a url, or a urn. | [{"buildpack":"https://github.com/heroku/heroku-buildpack-ruby"}] |
Curl Example
$ curl -n -X PUT https://api.heroku.com/apps/$APP_ID_OR_NAME/buildpack-installations \
-d '{
"updates": [
{
"buildpack": "https://github.com/heroku/heroku-buildpack-ruby"
}
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"ordinal": 0,
"buildpack": {
"url": "https://github.com/heroku/heroku-buildpack-ruby",
"name": "heroku/ruby"
}
}
]
Buildpack Installations List
List an app’s existing buildpack installations.
GET /apps/{app_id_or_name}/buildpack-installations
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/buildpack-installations \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"ordinal": 0,
"buildpack": {
"url": "https://github.com/heroku/heroku-buildpack-ruby",
"name": "heroku/ruby"
}
}
]
Collaborator
Stability: production
A collaborator represents an account that has been given access to an app on Heroku.
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
created_at | date-time | when collaborator was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of collaborator | "01234567-89ab-cdef-0123-456789abcdef" |
permissions | array | [{"name":"view","description":"Can manage config, deploy, run commands and restart the app."}] |
|
role | nullable string | role in the team one of: "admin" or "collaborator" or "member" or "owner" or null |
"admin" |
updated_at | date-time | when collaborator was updated | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:federated | boolean | whether the user is federated and belongs to an Identity Provider | false |
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
Collaborator Create
Create a new collaborator.
POST /apps/{app_id_or_name}/collaborators
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
user | string | unique email address, identifier of an account or Implicit reference to currently authorized user | "username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" or "~" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
silent | boolean | whether to suppress email invitation when creating collaborator | false |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators \
-d '{
"silent": false,
"user": "01234567-89ab-cdef-0123-456789abcdef"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
],
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Collaborator Delete
Delete an existing collaborator.
DELETE /apps/{app_id_or_name}/collaborators/{collaborator_email_or_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators/$COLLABORATOR_EMAIL_OR_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
],
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Collaborator Info
Info for existing collaborator.
GET /apps/{app_id_or_name}/collaborators/{collaborator_email_or_id}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators/$COLLABORATOR_EMAIL_OR_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
],
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Collaborator List
List existing collaborators.
Acceptable order values for the Range header are email
or id
.
GET /apps/{app_id_or_name}/collaborators
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/collaborators \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: email, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
],
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
]
Config Vars
Stability: production
Config Vars allow you to manage the configuration information provided to an app on Heroku.
Config Vars Info for App
Get config-vars for app.
GET /apps/{app_id_or_name}/config-vars
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/config-vars \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"FOO": "bar",
"BAZ": "qux"
}
Config Vars Info for App Release
Get config-vars for a release.
GET /apps/{app_id_or_name}/releases/{release_id_or_version}/config-vars
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/releases/$RELEASE_ID_OR_VERSION/config-vars \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"FOO": "bar",
"BAZ": "qux"
}
Config Vars Update
Update config-vars for app. You can update existing config-vars by setting them again, and remove by setting it to null
.
PATCH /apps/{app_id_or_name}/config-vars
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/config-vars \
-d '{
"FOO": "bar",
"BAZ": "qux"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"FOO": "bar",
"BAZ": "qux"
}
Credit
Stability: development
A credit represents value that will be used up before further charges are assigned to an account.
Attributes
Name | Type | Description | Example |
---|---|---|---|
amount | number | total value of credit in cents | 10000 |
balance | number | remaining value of credit in cents | 5000 |
created_at | date-time | when credit was created | "2012-01-01T12:00:00Z" |
expires_at | date-time | when credit will expire | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of credit | "01234567-89ab-cdef-0123-456789abcdef" |
title | string | a name for credit | "gift card" |
updated_at | date-time | when credit was updated | "2012-01-01T12:00:00Z" |
Credit Create
Create a new credit.
POST /account/credits
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
code1 | string | first code from a discount card | "012abc" |
code2 | string | second code from a discount card | "012abc" |
Curl Example
$ curl -n -X POST https://api.heroku.com/account/credits \
-d '{
"code1": "012abc",
"code2": "012abc"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"amount": 10000,
"balance": 5000,
"created_at": "2012-01-01T12:00:00Z",
"expires_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"title": "gift card",
"updated_at": "2012-01-01T12:00:00Z"
}
Credit Info
Info for existing credit.
GET /account/credits/{credit_id}
Curl Example
$ curl -n https://api.heroku.com/account/credits/$CREDIT_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"amount": 10000,
"balance": 5000,
"created_at": "2012-01-01T12:00:00Z",
"expires_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"title": "gift card",
"updated_at": "2012-01-01T12:00:00Z"
}
Credit List
List existing credits.
The only acceptable order value for the Range header is id
.
GET /account/credits
Curl Example
$ curl -n https://api.heroku.com/account/credits \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"amount": 10000,
"balance": 5000,
"created_at": "2012-01-01T12:00:00Z",
"expires_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"title": "gift card",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Domain
Stability: production
Domains define what web routes should be routed to an app on Heroku.
Attributes
Name | Type | Description | Example |
---|---|---|---|
acm_status | nullable string | status of this record’s ACM | "pending" |
acm_status_reason | nullable string | reason for the status of this record’s ACM | "Failing CCA check" |
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
cname | nullable string | canonical name record, the address to point a domain at | "example.herokudns.com" |
created_at | date-time | when domain was created | "2012-01-01T12:00:00Z" |
hostname | uri | full hostname | "subdomain.example.com" |
id | uuid | unique identifier of this domain | "01234567-89ab-cdef-0123-456789abcdef" |
kind | string | type of domain name one of: "heroku" or "custom" |
"custom" |
sni_endpoint | nullable object | sni endpoint the domain is associated with | null |
sni_endpoint:id | uuid | unique identifier of this SNI endpoint | "01234567-89ab-cdef-0123-456789abcdef" |
sni_endpoint:name | string | unique name for SNI endpoint pattern: ^[a-z][a-z0-9-]{2,29}$ |
"example" |
status | string | status of this record’s cname | "pending" |
updated_at | date-time | when domain was updated | "2012-01-01T12:00:00Z" |
Domain Create
Create a new domain.
POST /apps/{app_id_or_name}/domains
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
hostname | uri | full hostname | "subdomain.example.com" |
sni_endpoint | nullable string | null or unique identifier or name for SNI endpoint | null |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/domains \
-d '{
"hostname": "subdomain.example.com",
"sni_endpoint": null
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm_status": "pending",
"acm_status_reason": "Failing CCA check",
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"cname": "example.herokudns.com",
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"kind": "custom",
"updated_at": "2012-01-01T12:00:00Z",
"status": "pending",
"sni_endpoint": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Domain Update
Associate an SNI endpoint
PATCH /apps/{app_id_or_name}/domains/{domain_id_or_hostname}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
sni_endpoint | nullable string | null or unique identifier or name for SNI endpoint | null |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/domains/$DOMAIN_ID_OR_HOSTNAME \
-d '{
"sni_endpoint": null
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm_status": "pending",
"acm_status_reason": "Failing CCA check",
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"cname": "example.herokudns.com",
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"kind": "custom",
"updated_at": "2012-01-01T12:00:00Z",
"status": "pending",
"sni_endpoint": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Domain Delete
Delete an existing domain
DELETE /apps/{app_id_or_name}/domains/{domain_id_or_hostname}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/domains/$DOMAIN_ID_OR_HOSTNAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm_status": "pending",
"acm_status_reason": "Failing CCA check",
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"cname": "example.herokudns.com",
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"kind": "custom",
"updated_at": "2012-01-01T12:00:00Z",
"status": "pending",
"sni_endpoint": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Domain Info
Info for existing domain.
GET /apps/{app_id_or_name}/domains/{domain_id_or_hostname}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/domains/$DOMAIN_ID_OR_HOSTNAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm_status": "pending",
"acm_status_reason": "Failing CCA check",
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"cname": "example.herokudns.com",
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"kind": "custom",
"updated_at": "2012-01-01T12:00:00Z",
"status": "pending",
"sni_endpoint": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Domain List
List existing domains.
Acceptable order values for the Range header are hostname
or id
.
GET /apps/{app_id_or_name}/domains
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/domains \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: hostname, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"acm_status": "pending",
"acm_status_reason": "Failing CCA check",
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"cname": "example.herokudns.com",
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"kind": "custom",
"updated_at": "2012-01-01T12:00:00Z",
"status": "pending",
"sni_endpoint": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
]
Dyno
Stability: production
Dynos encapsulate running processes of an app on Heroku. Detailed information about dyno sizes can be found at: https://devcenter.heroku.com/articles/dyno-types.
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
attach_url | nullable string | a URL to stream output from for attached processes or null for non-attached processes | "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}" |
command | string | command used to start this process | "bash" |
created_at | date-time | when dyno was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of this dyno | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | the name of this process on this dyno | "run.1" |
release:id | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
release:version | integer | unique version assigned to the release | 11 |
size | string | dyno size | "standard-1X" |
state | string | current status of process (either: crashed, down, idle, starting, or up) | "up" |
type | string | type of process | "run" |
updated_at | date-time | when process last changed state | "2012-01-01T12:00:00Z" |
Dyno Create
Create a new dyno.
POST /apps/{app_id_or_name}/dynos
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
command | string | command used to start this process | "bash" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
attach | boolean | whether to stream output or not | true |
env | object | custom environment to add to the dyno config vars | {"COLUMNS":"80","LINES":"24"} |
force_no_tty | nullable boolean | force an attached one-off dyno to not run in a tty | null |
size | string | dyno size | "standard-1X" |
time_to_live | integer | seconds until dyno expires, after which it will soon be killed, max 86400 seconds (24 hours) | 1800 |
type | string | type of process | "run" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos \
-d '{
"attach": true,
"command": "bash",
"env": {
"COLUMNS": "80",
"LINES": "24"
},
"force_no_tty": null,
"size": "standard-1X",
"type": "run",
"time_to_live": 1800
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
"command": "bash",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "run.1",
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"version": 11
},
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"size": "standard-1X",
"state": "up",
"type": "run",
"updated_at": "2012-01-01T12:00:00Z"
}
Dyno Restart
Restart dyno.
DELETE /apps/{app_id_or_name}/dynos/{dyno_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos/$DYNO_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
Dyno Restart all
Restart all dynos.
DELETE /apps/{app_id_or_name}/dynos
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
Dyno Stop
Stop dyno.
POST /apps/{app_id_or_name}/dynos/{dyno_id_or_name}/actions/stop
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos/$DYNO_ID_OR_NAME/actions/stop \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
Dyno Info
Info for existing dyno.
GET /apps/{app_id_or_name}/dynos/{dyno_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos/$DYNO_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
"command": "bash",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "run.1",
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"version": 11
},
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"size": "standard-1X",
"state": "up",
"type": "run",
"updated_at": "2012-01-01T12:00:00Z"
}
Dyno List
List existing dynos.
Acceptable order values for the Range header are id
or name
.
GET /apps/{app_id_or_name}/dynos
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/dynos \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
"command": "bash",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "run.1",
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"version": 11
},
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"size": "standard-1X",
"state": "up",
"type": "run",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Dyno Size
Stability: prototype
Dyno sizes are the values and details of sizes that can be assigned to dynos. This information can also be found at : https://devcenter.heroku.com/articles/dyno-types.
Attributes
Name | Type | Description | Example |
---|---|---|---|
compute | integer | minimum vCPUs, non-dedicated may get more depending on load | 1 |
cost | nullable object | price information for this dyno size | null |
dedicated | boolean | whether this dyno will be dedicated to one user | false |
id | uuid | unique identifier of this dyno size | "01234567-89ab-cdef-0123-456789abcdef" |
memory | number | amount of RAM in GB | 0.5 |
name | string | the name of this dyno-size | "eco" |
precise_dyno_units | number | unit of consumption for Heroku Enterprise customers to 2 decimal places | 0.28 |
private_space_only | boolean | whether this dyno can only be provisioned in a private space | false |
Dyno Size Info
Info for existing dyno size.
GET /dyno-sizes/{dyno_size_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/dyno-sizes/$DYNO_SIZE_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"compute": 1,
"cost": null,
"dedicated": false,
"precise_dyno_units": 0.28,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"memory": 0.5,
"name": "eco",
"private_space_only": false
}
Dyno Size List
List existing dyno sizes.
Acceptable order values for the Range header are id
or name
.
GET /dyno-sizes
Curl Example
$ curl -n https://api.heroku.com/dyno-sizes \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"compute": 1,
"cost": null,
"dedicated": false,
"precise_dyno_units": 0.28,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"memory": 0.5,
"name": "eco",
"private_space_only": false
}
]
Enterprise Account
Stability: development
Enterprise accounts allow companies to manage their development teams and billing.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when the enterprise account was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of the enterprise account | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider | nullable object | Identity Provider associated with the Enterprise Account | null |
identity_provider:id | uuid | unique identifier of this identity provider | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:name | string | user-friendly unique identifier for this identity provider | "acme-sso" |
identity_provider:owner:id | uuid | unique identifier of the owner | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:owner:name | string | name of the owner | "acme" |
identity_provider:owner:type | string | type of the owner one of: "team" or "enterprise-account" |
"team" |
name | string | unique name of the enterprise account | "example" |
permissions | array | the current user’s permissions for this enterprise account | ["view"] |
trial | boolean | whether the enterprise account is a trial or not | false |
updated_at | date-time | when the enterprise account was updated | "2012-01-01T12:00:00Z" |
Enterprise Account List
List enterprise accounts in which you are a member.
Acceptable order values for the Range header are id
or name
.
GET /enterprise-accounts
Curl Example
$ curl -n https://api.heroku.com/enterprise-accounts \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z",
"permissions": [
"view"
],
"trial": false,
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
}
]
Enterprise Account Info
Information about an enterprise account.
GET /enterprise-accounts/{enterprise_account_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z",
"permissions": [
"view"
],
"trial": false,
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
}
Enterprise Account Update
Update enterprise account properties
PATCH /enterprise-accounts/{enterprise_account_id_or_name}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | unique name of the enterprise account | "example" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME \
-d '{
"name": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z",
"permissions": [
"view"
],
"trial": false,
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
}
Enterprise Account Daily Usage
Stability: development
Usage for an enterprise account at a daily resolution.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addons | number | total add-on credits used | 250.0 |
data | number | total add-on credits used for first party add-ons | 34.89 |
date | date | date of the usage | "2019-01-01" |
dynos | number | dynos used | 1.548 |
id | uuid | enterprise account identifier | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | name of the enterprise account | "example-co" |
partner | number | total add-on credits used for third party add-ons | 12.34 |
space | number | space credits used | 1.548 |
teams/addons | number | total add-on credits used | 250.0 |
teams/apps | array | app usage in the team | [{"addons":250.0,"app_name":"example","data":34.89,"dynos":1.548,"partner":12.34}] |
teams/data | number | total add-on credits used for first party add-ons | 34.89 |
teams/dynos | number | dynos used | 1.548 |
teams/id | uuid | team identifier | "01234567-89ab-cdef-0123-456789abcdef" |
teams/name | string | name of the team | "ops" |
teams/partner | number | total add-on credits used for third party add-ons | 12.34 |
teams/space | number | space credits used | 1.548 |
Enterprise Account Daily Usage Info
Retrieves usage for an enterprise account for a range of days. Start and end dates can be specified as query parameters using the date format YYYY-MM-DD. The enterprise account identifier can be found from the enterprise account list.
GET /enterprise-accounts/{enterprise_account_id}/usage/daily
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
start | string | range start date pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ |
"2019-01-25" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
end | string | range end date pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ |
"2019-02-25" |
Curl Example
$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID/usage/daily \
-G \
-d start=2019-01-25 \
-d end=2019-02-25 \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addons": 250.0,
"teams": [
{
"addons": 250.0,
"apps": [
{
"addons": 250.0,
"app_name": "example",
"data": 34.89,
"dynos": 1.548,
"partner": 12.34
}
],
"data": 34.89,
"dynos": 1.548,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "ops",
"partner": 12.34,
"space": 1.548
}
],
"data": 34.89,
"date": "2019-01-01",
"dynos": 1.548,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example-co",
"partner": 12.34,
"space": 1.548
}
]
Enterprise Account Member
Stability: development
Enterprise account members are users with access to an enterprise account.
Attributes
Name | Type | Description | Example |
---|---|---|---|
enterprise_account:id | uuid | unique identifier of the enterprise account | "01234567-89ab-cdef-0123-456789abcdef" |
enterprise_account:name | string | unique name of the enterprise account | "example" |
id | uuid | unique identifier of the member | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider | nullable object | Identity Provider information the member is federated with | null |
identity_provider:id | uuid | unique identifier of this identity provider | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:name | string | name of the identity provider | "acme" |
identity_provider:owner:id | uuid | unique identifier of the owner | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:owner:name | string | name of the owner | "acme" |
identity_provider:owner:type | string | type of the owner one of: "team" or "enterprise-account" |
"team" |
identity_provider:redacted | boolean | whether the identity_provider information is redacted or not | false |
permissions/description | string | "View enterprise account members and teams." |
|
permissions/name | string | permission in the enterprise account one of: "view" or "create" or "manage" or "billing" |
"view" |
two_factor_authentication | boolean | whether the Enterprise Account member has two factor authentication enabled | true |
user:email | unique email address | "username@example.com" |
|
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
Enterprise Account Member List
List members in an enterprise account.
The only acceptable order value for the Range header is id
.
GET /enterprise-accounts/{enterprise_account_id_or_name}/members
Curl Example
$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/members \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"description": "View enterprise account members and teams.",
"name": "view"
}
],
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"two_factor_authentication": true,
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
}
]
Enterprise Account Member Create
Create a member in an enterprise account.
POST /enterprise-accounts/{enterprise_account_id_or_name}/members
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
permissions | array | permissions for enterprise account | ["view"] |
user | string | unique email address or identifier of an account | "username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
federated | boolean | whether membership is being created as part of SSO JIT | false |
Curl Example
$ curl -n -X POST https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/members \
-d '{
"user": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
"view"
],
"federated": false
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"description": "View enterprise account members and teams.",
"name": "view"
}
],
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"two_factor_authentication": true,
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
}
Enterprise Account Member Update
Update a member in an enterprise account.
PATCH /enterprise-accounts/{enterprise_account_id_or_name}/members/{enterprise_account_member_email_or_id}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
permissions | array | permissions for enterprise account | ["view"] |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/members/$ENTERPRISE_ACCOUNT_MEMBER_EMAIL_OR_ID \
-d '{
"permissions": [
"view"
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"description": "View enterprise account members and teams.",
"name": "view"
}
],
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"two_factor_authentication": true,
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
}
Enterprise Account Member Delete
delete a member in an enterprise account.
DELETE /enterprise-accounts/{enterprise_account_id_or_name}/members/{enterprise_account_member_email_or_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/members/$ENTERPRISE_ACCOUNT_MEMBER_EMAIL_OR_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"description": "View enterprise account members and teams.",
"name": "view"
}
],
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"two_factor_authentication": true,
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
}
Enterprise Account Monthly Usage
Stability: development
Usage for an enterprise account at a monthly resolution.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addons | number | total add-on credits used | 250.0 |
connect | number | max connect rows synced | 15000 |
data | number | total add-on credits used for first party add-ons | 34.89 |
dynos | number | dynos used | 1.548 |
id | uuid | enterprise account identifier | "01234567-89ab-cdef-0123-456789abcdef" |
month | string | year and month of the usage pattern: ^[0-9]{4}-[0-9]{2}$ |
"2019-01" |
name | string | name of the enterprise account | "example-co" |
partner | number | total add-on credits used for third party add-ons | 12.34 |
space | number | space credits used | 1.548 |
teams/addons | number | total add-on credits used | 250.0 |
teams/apps | array | app usage in the team | [{"addons":250.0,"app_name":"example","data":34.89,"dynos":1.548,"partner":12.34}] |
teams/connect | number | max connect rows synced | 15000 |
teams/data | number | total add-on credits used for first party add-ons | 34.89 |
teams/dynos | number | dynos used | 1.548 |
teams/id | uuid | team identifier | "01234567-89ab-cdef-0123-456789abcdef" |
teams/name | string | name of the team | "ops" |
teams/partner | number | total add-on credits used for third party add-ons | 12.34 |
teams/space | number | space credits used | 1.548 |
Enterprise Account Monthly Usage Info
Retrieves usage for an enterprise account for a range of months. Start and end dates can be specified as query parameters using the date format YYYY-MM. If no end date is specified, one month of usage is returned. The enterprise account identifier can be found from the enterprise account list.
GET /enterprise-accounts/{enterprise_account_id}/usage/monthly
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
start | string | range start date pattern: ^[0-9]{4}-[0-9]{2}$ |
"2019-01" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
end | string | range end date pattern: ^[0-9]{4}-[0-9]{2}$ |
"2019-02" |
Curl Example
$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID/usage/monthly \
-G \
-d start=2019-01 \
-d end=2019-02 \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addons": 250.0,
"teams": [
{
"addons": 250.0,
"apps": [
{
"addons": 250.0,
"app_name": "example",
"data": 34.89,
"dynos": 1.548,
"partner": 12.34
}
],
"connect": 15000,
"data": 34.89,
"dynos": 1.548,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "ops",
"partner": 12.34,
"space": 1.548
}
],
"connect": 15000,
"data": 34.89,
"dynos": 1.548,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"month": "2019-01",
"name": "example-co",
"partner": 12.34,
"space": 1.548
}
]
Filters
Stability: development
Filters are special endpoints to allow for API consumers to specify a subset of resources to consume in order to reduce the number of requests that are performed. Each filter endpoint endpoint is responsible for determining its supported request format. The endpoints are over POST in order to handle large request bodies without hitting request uri query length limitations, but the requests themselves are idempotent and will not have side effects.
Filters Apps
Request an apps list filtered by app id.
Acceptable order values for the Range header are id
, name
or updated_at
.
POST /filters/apps
Curl Example
$ curl -n -X POST https://api.heroku.com/filters/apps \
-d '{
"in": {
"id": [
"01234567-89ab-cdef-0123-456789abcdef"
]
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name, updated_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
Formation
Stability: production
The formation of processes that should be maintained for an app. Update the formation to scale processes or change dyno sizes. Available process type names and commands are defined by the process_types
attribute for the slug currently released on an app.
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
command | string | command to use to launch this process | "bundle exec rails server -p $PORT" |
created_at | date-time | when process type was created | "2012-01-01T12:00:00Z" |
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 | "standard-1X" |
type | string | type of process to maintain pattern: ^[-\w]{1,128}$ |
"web" |
updated_at | date-time | when dyno type was updated | "2012-01-01T12:00:00Z" |
Formation Info
Info for a process type
GET /apps/{app_id_or_name}/formation/{formation_id_or_type}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/formation/$FORMATION_ID_OR_TYPE \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"command": "bundle exec rails server -p $PORT",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"quantity": 1,
"size": "standard-1X",
"type": "web",
"updated_at": "2012-01-01T12:00:00Z"
}
Formation List
List process type formation
Acceptable order values for the Range header are id
or type
.
GET /apps/{app_id_or_name}/formation
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/formation \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, type
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"command": "bundle exec rails server -p $PORT",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"quantity": 1,
"size": "standard-1X",
"type": "web",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Formation Batch Update
Batch update process types
PATCH /apps/{app_id_or_name}/formation
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
updates | array | Array with formation updates. Each element must have “type”, the id or name of the process type to be updated, and can optionally update its “quantity” or “size”. | [{"quantity":1,"size":"standard-1X","type":"web"}] |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/formation \
-d '{
"updates": [
{
"quantity": 1,
"size": "standard-1X",
"type": "web"
}
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"command": "bundle exec rails server -p $PORT",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"quantity": 1,
"size": "standard-1X",
"type": "web",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Formation Update
Update process type
PATCH /apps/{app_id_or_name}/formation/{formation_id_or_type}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
quantity | integer | number of processes to maintain | 1 |
size | string | dyno size | "standard-1X" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/formation/$FORMATION_ID_OR_TYPE \
-d '{
"quantity": 1,
"size": "standard-1X"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"command": "bundle exec rails server -p $PORT",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"quantity": 1,
"size": "standard-1X",
"type": "web",
"updated_at": "2012-01-01T12:00:00Z"
}
Identity Provider
Stability: production
Identity Providers represent the SAML configuration of teams or an Enterprise account
Attributes
Name | Type | Description | Example |
---|---|---|---|
certificate | string | raw contents of the public certificate (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
created_at | date-time | when provider record was created | "2012-01-01T12:00:00Z" |
entity_id | string | URL identifier provided by the identity provider | "https://customer-domain.idp.com" |
id | uuid | unique identifier of this identity provider | "01234567-89ab-cdef-0123-456789abcdef" |
organization | nullable object | team associated with this identity provider | null |
organization:name | string | unique name of team | "example" |
owner:id | uuid | unique identifier of the owner | "01234567-89ab-cdef-0123-456789abcdef" |
owner:name | string | name of the owner | "acme" |
owner:type | string | type of the owner one of: "team" or "enterprise-account" |
"team" |
slo_target_url | string | single log out URL for this identity provider | "https://example.com/idp/logout" |
sso_target_url | string | single sign on URL for this identity provider | "https://example.com/idp/login" |
updated_at | date-time | when the identity provider record was updated | "2012-01-01T12:00:00Z" |
Identity Provider List By Team
Get a list of a team’s Identity Providers
GET /teams/{team_name}/identity-providers
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME/identity-providers \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
]
Identity Provider Create By Team
Create an Identity Provider for a team
POST /teams/{team_name}/identity-providers
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
certificate | string | raw contents of the public certificate (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
entity_id | string | URL identifier provided by the identity provider | "https://customer-domain.idp.com" |
sso_target_url | string | single sign on URL for this identity provider | "https://example.com/idp/login" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
slo_target_url | string | single log out URL for this identity provider | "https://example.com/idp/logout" |
Curl Example
$ curl -n -X POST https://api.heroku.com/teams/$TEAM_NAME/identity-providers \
-d '{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"entity_id": "https://customer-domain.idp.com",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
Identity Provider Update By Team
Update a team’s Identity Provider
PATCH /teams/{team_name}/identity-providers/{identity_provider_id}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
certificate | string | raw contents of the public certificate (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
entity_id | string | URL identifier provided by the identity provider | "https://customer-domain.idp.com" |
slo_target_url | string | single log out URL for this identity provider | "https://example.com/idp/logout" |
sso_target_url | string | single sign on URL for this identity provider | "https://example.com/idp/login" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/teams/$TEAM_NAME/identity-providers/$IDENTITY_PROVIDER_ID \
-d '{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"entity_id": "https://customer-domain.idp.com",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
Identity Provider Delete By Team
Delete a team’s Identity Provider
DELETE /teams/{team_name}/identity-providers/{identity_provider_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/teams/$TEAM_NAME/identity-providers/$IDENTITY_PROVIDER_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
}
Inbound Ruleset
Stability: prototype
An inbound-ruleset is a collection of rules that specify what hosts can or cannot connect to an application.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when inbound-ruleset was created | "2012-01-01T12:00:00Z" |
created_by | unique email address | "username@example.com" |
|
id | uuid | unique identifier of an inbound-ruleset | "01234567-89ab-cdef-0123-456789abcdef" |
rules | array | [{"action":"allow","source":"1.1.1.1/1"}] |
|
space:id | uuid | unique identifier of space | "01234567-89ab-cdef-0123-456789abcdef" |
space:name | string | unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$ |
"nasa" |
Inbound Ruleset Current
Current inbound ruleset for a space
GET /spaces/{space_id_or_name}/inbound-ruleset
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/inbound-ruleset \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"created_at": "2012-01-01T12:00:00Z",
"rules": [
{
"action": "allow",
"source": "1.1.1.1/1"
}
],
"created_by": "username@example.com"
}
Inbound Ruleset Info
Info on an existing Inbound Ruleset
GET /spaces/{space_id_or_name}/inbound-rulesets/{inbound_ruleset_id}
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/inbound-rulesets/$INBOUND_RULESET_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"created_at": "2012-01-01T12:00:00Z",
"rules": [
{
"action": "allow",
"source": "1.1.1.1/1"
}
],
"created_by": "username@example.com"
}
Inbound Ruleset List
List all inbound rulesets for a space
The only acceptable order value for the Range header is id
.
GET /spaces/{space_id_or_name}/inbound-rulesets
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/inbound-rulesets \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"created_at": "2012-01-01T12:00:00Z",
"rules": [
{
"action": "allow",
"source": "1.1.1.1/1"
}
],
"created_by": "username@example.com"
}
]
Inbound Ruleset Create
Create a new inbound ruleset
PUT /spaces/{space_id_or_name}/inbound-ruleset
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
rules | array | [{"action":"allow","source":"1.1.1.1/1"}] |
Curl Example
$ curl -n -X PUT https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/inbound-ruleset \
-d '{
"rules": [
{
"action": "allow",
"source": "1.1.1.1/1"
}
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"created_at": "2012-01-01T12:00:00Z",
"rules": [
{
"action": "allow",
"source": "1.1.1.1/1"
}
],
"created_by": "username@example.com"
}
Invoice
Stability: development
An invoice is an itemized bill of goods for an account which includes pricing and charges.
Attributes
Name | Type | Description | Example |
---|---|---|---|
charges_total | number | total charges on this invoice | 100.0 |
created_at | date-time | when invoice was created | "2012-01-01T12:00:00Z" |
credits_total | number | total credits on this invoice | 100.0 |
id | uuid | unique identifier of this invoice | "01234567-89ab-cdef-0123-456789abcdef" |
number | integer | human readable invoice number | 9403943 |
period_end | string | the ending date that the invoice covers | "01/31/2014" |
period_start | string | the starting date that this invoice covers | "01/01/2014" |
state | integer | payment status for this invoice (pending, successful, failed) | 1 |
total | number | combined total of charges and credits on this invoice | 100.0 |
updated_at | date-time | when invoice was updated | "2012-01-01T12:00:00Z" |
Invoice Info
Info for existing invoice.
GET /account/invoices/{invoice_number}
Curl Example
$ curl -n https://api.heroku.com/account/invoices/$INVOICE_NUMBER \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"charges_total": 100.0,
"created_at": "2012-01-01T12:00:00Z",
"credits_total": 100.0,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"number": 9403943,
"period_end": "01/31/2014",
"period_start": "01/01/2014",
"state": 1,
"total": 100.0,
"updated_at": "2012-01-01T12:00:00Z"
}
Invoice List
List existing invoices.
The only acceptable order value for the Range header is number
.
GET /account/invoices
Curl Example
$ curl -n https://api.heroku.com/account/invoices \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: number
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"charges_total": 100.0,
"created_at": "2012-01-01T12:00:00Z",
"credits_total": 100.0,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"number": 9403943,
"period_end": "01/31/2014",
"period_start": "01/01/2014",
"state": 1,
"total": 100.0,
"updated_at": "2012-01-01T12:00:00Z"
}
]
Invoice Address
Stability: development
An invoice address represents the address that should be listed on an invoice.
Attributes
Name | Type | Description | Example |
---|---|---|---|
address_1 | string | invoice street address line 1 | "40 Hickory Blvd." |
address_2 | string | invoice street address line 2 | "Suite 300" |
city | string | invoice city | "Seattle" |
country | string | country | "US" |
heroku_id | string | heroku_id identifier reference | "user930223902@heroku.com" |
other | string | metadata / additional information to go on invoice | "Company ABC Inc. VAT 903820" |
postal_code | string | invoice zip code | "98101" |
state | string | invoice state | "WA" |
use_invoice_address | boolean | flag to use the invoice address for an account or not | true |
Invoice Address info
Retrieve existing invoice address.
GET /account/invoice-address
Curl Example
$ curl -n https://api.heroku.com/account/invoice-address \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"address_1": "40 Hickory Blvd.",
"address_2": "Suite 300",
"city": "Seattle",
"country": "US",
"heroku_id": "user930223902@heroku.com",
"other": "Company ABC Inc. VAT 903820",
"postal_code": "98101",
"state": "WA",
"use_invoice_address": true
}
Invoice Address update
Update invoice address for an account.
PUT /account/invoice-address
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
address_1 | string | invoice street address line 1 | "40 Hickory Blvd." |
address_2 | string | invoice street address line 2 | "Suite 300" |
city | string | invoice city | "Seattle" |
country | string | country | "US" |
other | string | metadata / additional information to go on invoice | "Company ABC Inc. VAT 903820" |
postal_code | string | invoice zip code | "98101" |
state | string | invoice state | "WA" |
use_invoice_address | boolean | flag to use the invoice address for an account or not | true |
Curl Example
$ curl -n -X PUT https://api.heroku.com/account/invoice-address \
-d '{
"address_1": "40 Hickory Blvd.",
"address_2": "Suite 300",
"city": "Seattle",
"country": "US",
"other": "Company ABC Inc. VAT 903820",
"postal_code": "98101",
"state": "WA",
"use_invoice_address": true
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"address_1": "40 Hickory Blvd.",
"address_2": "Suite 300",
"city": "Seattle",
"country": "US",
"heroku_id": "user930223902@heroku.com",
"other": "Company ABC Inc. VAT 903820",
"postal_code": "98101",
"state": "WA",
"use_invoice_address": true
}
Key
Stability: production
Keys represent public SSH keys associated with an account and are used to authorize accounts as they are performing git operations.
Attributes
Name | Type | Description | Example |
---|---|---|---|
comment | string | comment on the key | "username@host" |
created_at | date-time | when key was created | "2012-01-01T12:00:00Z" |
string | deprecated. Please refer to ‘comment’ instead | "username@host" |
|
fingerprint | string | a unique identifying string based on contents | "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf" |
id | uuid | unique identifier of this key | "01234567-89ab-cdef-0123-456789abcdef" |
public_key | string | full public_key as uploaded | "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com" |
updated_at | date-time | when key was updated | "2012-01-01T12:00:00Z" |
Key Info
Info for existing key.
GET /account/keys/{key_id_or_fingerprint}
Curl Example
$ curl -n https://api.heroku.com/account/keys/$KEY_ID_OR_FINGERPRINT \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"comment": "username@host",
"created_at": "2012-01-01T12:00:00Z",
"email": "username@host",
"fingerprint": "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"public_key": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com",
"updated_at": "2012-01-01T12:00:00Z"
}
Key List
List existing keys.
Acceptable order values for the Range header are fingerprint
or id
.
GET /account/keys
Curl Example
$ curl -n https://api.heroku.com/account/keys \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: fingerprint, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"comment": "username@host",
"created_at": "2012-01-01T12:00:00Z",
"email": "username@host",
"fingerprint": "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"public_key": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Log Drain
Stability: production
Log drains provide a way to forward your Heroku logs to an external syslog server for long-term archiving. This external service must be configured to receive syslog packets from Heroku, whereupon its URL can be added to an app using this API. Some add-ons will add a log drain when they are provisioned to an app. These drains can only be removed by removing the add-on.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addon | nullable object | add-on that created the drain | {"id":"01234567-89ab-cdef-0123-456789abcdef","name":"singing-swiftly-1242","app":{"id":"01234567-89ab-cdef-0123-456789abcdef","name":"example"}} |
addon:app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
addon:app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
addon:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
addon:name | string | globally name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$ |
"acme-inc-primary-database" |
app | nullable object | application that is attached to this drain | {"id":"01234567-89ab-cdef-0123-456789abcdef","name":"example"} |
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
created_at | date-time | when log drain was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of this log drain | "01234567-89ab-cdef-0123-456789abcdef" |
token | string | token associated with the log drain | "d.01234567-89ab-cdef-0123-456789abcdef" |
updated_at | date-time | when log drain was updated | "2012-01-01T12:00:00Z" |
url | string | url associated with the log drain | "https://example.com/drain" |
Log Drain Create
Create a new log drain.
POST /apps/{app_id_or_name}/log-drains
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
url | string | url associated with the log drain | "https://example.com/drain" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains \
-d '{
"url": "https://example.com/drain"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain Update
Update an add-on owned log drain.
PUT /addons/{add_on_id_or_name}/log-drains/{log_drain_id_or_url_or_token}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
url | string | url associated with the log drain | "https://example.com/drain" |
Curl Example
$ curl -n -X PUT https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL_OR_TOKEN \
-d '{
"url": "https://example.com/drain"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain Delete
Delete an existing log drain. Log drains added by add-ons can only be removed by removing the add-on.
DELETE /apps/{app_id_or_name}/log-drains/{log_drain_id_or_url_or_token}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL_OR_TOKEN \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain Info
Info for existing log drain.
GET /apps/{app_id_or_name}/log-drains/{log_drain_id_or_url_or_token}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL_OR_TOKEN \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain List By Add-on
List existing log drains for an add-on.
The only acceptable order value for the Range header is url
.
GET /addons/{add_on_id_or_name}/log-drains
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/log-drains \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: url
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
]
Log Drain List
List existing log drains.
The only acceptable order value for the Range header is url
.
GET /apps/{app_id_or_name}/log-drains
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: url
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
]
Log Session
Stability: production
A log session is a reference to the http based log stream for an app.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when log connection was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of this log session | "01234567-89ab-cdef-0123-456789abcdef" |
logplex_url | string | URL for log streaming session | "https://logplex.heroku.com/sessions/01234567-89ab-cdef-0123-456789abcdef?srv=1325419200" |
updated_at | date-time | when log session was updated | "2012-01-01T12:00:00Z" |
Log Session Create
Create a new log session.
POST /apps/{app_id_or_name}/log-sessions
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
dyno | 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 \
-d '{
"dyno": "web.1",
"lines": 10,
"source": "app",
"tail": true
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"logplex_url": "https://logplex.heroku.com/sessions/01234567-89ab-cdef-0123-456789abcdef?srv=1325419200",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Authorization
Stability: production
OAuth authorizations represent clients that a Heroku user has authorized to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation
Attributes
Name | Type | Description | Example |
---|---|---|---|
access_token | nullable object | access token for this authorization | null |
access_token:expires_in | nullable integer | seconds until OAuth token expires; may be null for tokens with indefinite lifetime |
2592000 |
access_token:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
access_token:token | string | contents of the token to be used for authorization | "HRKU-01234567-89ab-cdef-0123-456789abcdef" |
client | nullable object | identifier of the client that obtained this authorization, if any | null |
client:id | uuid | unique identifier of this OAuth client | "01234567-89ab-cdef-0123-456789abcdef" |
client:name | string | OAuth client name | "example" |
client:redirect_uri | string | endpoint for redirection after authorization with OAuth client | "https://example.com/auth/heroku/callback" |
created_at | date-time | when OAuth authorization was created | "2012-01-01T12:00:00Z" |
grant | nullable object | this authorization’s grant | null |
grant:code | string | grant code received from OAuth web application authorization | "01234567-89ab-cdef-0123-456789abcdef" |
grant:expires_in | integer | seconds until OAuth grant expires | 2592000 |
grant:id | uuid | unique identifier of OAuth grant | "01234567-89ab-cdef-0123-456789abcdef" |
id | uuid | unique identifier of OAuth authorization | "01234567-89ab-cdef-0123-456789abcdef" |
refresh_token | nullable object | refresh token for this authorization | null |
refresh_token:expires_in | nullable integer | seconds until OAuth token expires; may be null for tokens with indefinite lifetime |
2592000 |
refresh_token:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
refresh_token:token | string | contents of the token to be used for authorization | "HRKU-01234567-89ab-cdef-0123-456789abcdef" |
scope | array | The scope of access OAuth authorization allows | ["global"] |
updated_at | date-time | when OAuth authorization was updated | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:full_name | nullable string | full name of the account owner | "Tina Edmonds" |
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
OAuth Authorization Create
Create a new OAuth authorization.
POST /oauth/authorizations
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
scope | array | The scope of access OAuth authorization allows | ["global"] |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
client | string | unique identifier of this OAuth client | "01234567-89ab-cdef-0123-456789abcdef" |
description | string | human-friendly description of this OAuth authorization | "sample authorization" |
expires_in | nullable integer | seconds until OAuth token expires; may be null for tokens with indefinite lifetime |
2592000 |
Curl Example
$ curl -n -X POST https://api.heroku.com/oauth/authorizations \
-d '{
"client": "01234567-89ab-cdef-0123-456789abcdef",
"description": "sample authorization",
"expires_in": 2592000,
"scope": [
"global"
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
OAuth Authorization Delete
Delete OAuth authorization.
DELETE /oauth/authorizations/{oauth_authorization_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
OAuth Authorization Info
Info for an OAuth authorization.
GET /oauth/authorizations/{oauth_authorization_id}
Curl Example
$ curl -n https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
OAuth Authorization List
List OAuth authorizations.
The only acceptable order value for the Range header is id
.
GET /oauth/authorizations
Curl Example
$ curl -n https://api.heroku.com/oauth/authorizations \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
]
OAuth Authorization Regenerate
Regenerate OAuth tokens. This endpoint is only available to direct authorizations or privileged OAuth clients.
POST /oauth/authorizations/{oauth_authorization_id}/actions/regenerate-tokens
Curl Example
$ curl -n -X POST https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID/actions/regenerate-tokens \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
OAuth Client
Stability: production
OAuth clients are applications that Heroku users can authorize to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when OAuth client was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of this OAuth client | "01234567-89ab-cdef-0123-456789abcdef" |
ignores_delinquent | nullable boolean | whether the client is still operable given a delinquent account | false |
name | string | OAuth client name | "example" |
redirect_uri | string | endpoint for redirection after authorization with OAuth client | "https://example.com/auth/heroku/callback" |
secret | string | secret used to obtain OAuth authorizations under this client | "01234567-89ab-cdef-0123-456789abcdef" |
updated_at | date-time | when OAuth client was updated | "2012-01-01T12:00:00Z" |
OAuth Client Create
Create a new OAuth client.
POST /oauth/clients
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | OAuth client name | "example" |
redirect_uri | string | endpoint for redirection after authorization with OAuth client | "https://example.com/auth/heroku/callback" |
Curl Example
$ curl -n -X POST https://api.heroku.com/oauth/clients \
-d '{
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Client Delete
Delete OAuth client.
DELETE /oauth/clients/{oauth_client_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Client Info
Info for an OAuth client. The output for unauthenticated requests excludes the secret
parameter.
GET /oauth/clients/{oauth_client_id}
Curl Example
$ curl -n https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Client List
List OAuth clients
The only acceptable order value for the Range header is id
.
GET /oauth/clients
Curl Example
$ curl -n https://api.heroku.com/oauth/clients \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
]
OAuth Client Update
Update OAuth client
PATCH /oauth/clients/{oauth_client_id}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | OAuth client name | "example" |
redirect_uri | string | endpoint for redirection after authorization with OAuth client | "https://example.com/auth/heroku/callback" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID \
-d '{
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Client Rotate Credentials
Rotate credentials for an OAuth client
POST /oauth/clients/{oauth_client_id}/actions/rotate-credentials
Curl Example
$ curl -n -X POST https://api.heroku.com/oauth/clients/$OAUTH_CLIENT_ID/actions/rotate-credentials \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"ignores_delinquent": false,
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback",
"secret": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z"
}
OAuth Grant
Stability: production
OAuth grants are used to obtain authorizations on behalf of a user. For more information please refer to the Heroku OAuth documentation
OAuth Token
Stability: production
OAuth tokens provide access for authorized clients to act on behalf of a Heroku user to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation
Attributes
Name | Type | Description | Example |
---|---|---|---|
access_token:expires_in | nullable integer | seconds until OAuth token expires; may be null for tokens with indefinite lifetime |
2592000 |
access_token:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
access_token:token | string | contents of the token to be used for authorization | "HRKU-01234567-89ab-cdef-0123-456789abcdef" |
authorization:id | uuid | unique identifier of OAuth authorization | "01234567-89ab-cdef-0123-456789abcdef" |
client | nullable object | OAuth client secret used to obtain token | null |
client:secret | string | secret used to obtain OAuth authorizations under this client | "01234567-89ab-cdef-0123-456789abcdef" |
created_at | date-time | when OAuth token was created | "2012-01-01T12:00:00Z" |
grant:code | string | grant code received from OAuth web application authorization | "01234567-89ab-cdef-0123-456789abcdef" |
grant:type | string | type of grant requested, one of authorization_code or refresh_token |
"authorization_code" |
id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
refresh_token:expires_in | nullable integer | seconds until OAuth token expires; may be null for tokens with indefinite lifetime |
2592000 |
refresh_token:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
refresh_token:token | string | contents of the token to be used for authorization | "HRKU-01234567-89ab-cdef-0123-456789abcdef" |
session:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
updated_at | date-time | when OAuth token was updated | "2012-01-01T12:00:00Z" |
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
OAuth Token Create
Create a new OAuth token.
POST /oauth/tokens
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
client:secret | string | secret used to obtain OAuth authorizations under this client | "01234567-89ab-cdef-0123-456789abcdef" |
grant:code | string | grant code received from OAuth web application authorization | "01234567-89ab-cdef-0123-456789abcdef" |
grant:type | string | type of grant requested, one of authorization_code or refresh_token |
"authorization_code" |
refresh_token:token | string | contents of the token to be used for authorization | "HRKU-01234567-89ab-cdef-0123-456789abcdef" |
Curl Example
$ curl -n -X POST https://api.heroku.com/oauth/tokens \
-d '{
"client": {
"secret": "01234567-89ab-cdef-0123-456789abcdef"
},
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"type": "authorization_code"
},
"refresh_token": {
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"authorization": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"secret": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"type": "authorization_code"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"session": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
OAuth Token Delete
Revoke OAuth access token.
DELETE /oauth/tokens/{oauth_token_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/oauth/tokens/$OAUTH_TOKEN_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"authorization": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"secret": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"type": "authorization_code"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "HRKU-01234567-89ab-cdef-0123-456789abcdef"
},
"session": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
PasswordReset
Stability: production
A password reset represents a in-process password reset attempt.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when password reset was created | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
PasswordReset Reset Password
Reset account’s password. This will send a reset password link to the user’s email address.
POST /password-resets
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
unique email address | "username@example.com" |
Curl Example
$ curl -n -X POST https://api.heroku.com/password-resets \
-d '{
"email": "username@example.com"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
PasswordReset Complete Reset Password
Complete password reset.
POST /password-resets/{password_reset_reset_password_token}/actions/finalize
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
password | string | current password on the account | "currentpassword" |
password_confirmation | string | confirmation of the new password | "newpassword" |
Curl Example
$ curl -n -X POST https://api.heroku.com/password-resets/$PASSWORD_RESET_RESET_PASSWORD_TOKEN/actions/finalize \
-d '{
"password": "currentpassword",
"password_confirmation": "newpassword"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Peering
Stability: prototype
Peering provides a way to peer your Private Space VPC to another AWS VPC.
Attributes
Name | Type | Description | Example |
---|---|---|---|
aws_account_id | string | The AWS account ID of your Private Space. | "123456789012" |
aws_region | string | The AWS region of the peer connection. | "us-east-1" |
aws_vpc_id | string | The AWS VPC ID of the peer. | "vpc-1234567890" |
cidr_blocks | array | The CIDR blocks of the peer. | ["10.0.0.0/16"] |
expires | date-time | When a peering connection will expire. | "2020-01-01T12:00:00Z" |
pcx_id | string | The AWS VPC Peering Connection ID of the peering. | "pcx-123456789012" |
status | string | The status of the peering connection. one of: "initiating-request" or "pending-acceptance" or "provisioning" or "active" or "failed" or "expired" or "rejected" or "deleted" |
"pending-acceptance" |
type | string | The type of peering connection. one of: "heroku-managed" or "customer-managed" or "unknown" |
"heroku-managed" |
Peering List
List peering connections of a private space.
GET /spaces/{space_id_or_name}/peerings
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/peerings \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"type": "heroku-managed",
"pcx_id": "pcx-123456789012",
"cidr_blocks": [
"10.0.0.0/16"
],
"status": "pending-acceptance",
"aws_vpc_id": "vpc-1234567890",
"aws_region": "us-east-1",
"aws_account_id": "123456789012",
"expires": "2020-01-01T12:00:00Z"
}
]
Peering Accept
Accept a pending peering connection with a private space.
POST /spaces/{space_id_or_name}/peerings/{peering_pcx_id}/actions/accept
Curl Example
$ curl -n -X POST https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/peerings/$PEERING_PCX_ID/actions/accept \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
Peering Destroy
Destroy an active peering connection with a private space.
DELETE /spaces/{space_id_or_name}/peerings/{peering_pcx_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/peerings/$PEERING_PCX_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
Peering Info
Fetch information for existing peering connection
GET /spaces/{space_id_or_name}/peerings/{peering_pcx_id}
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/peerings/$PEERING_PCX_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"type": "heroku-managed",
"pcx_id": "pcx-123456789012",
"cidr_blocks": [
"10.0.0.0/16"
],
"status": "pending-acceptance",
"aws_vpc_id": "vpc-1234567890",
"aws_region": "us-east-1",
"aws_account_id": "123456789012",
"expires": "2020-01-01T12:00:00Z"
}
Peering Info
Stability: prototype
Peering Info gives you the information necessary to peer an AWS VPC to a Private Space.
Attributes
Name | Type | Description | Example |
---|---|---|---|
aws_account_id | string | The AWS account ID of your Private Space. | "123456789012" |
aws_region | string | region name used by provider one of: "ap-south-1" or "eu-west-1" or "ap-southeast-1" or "ap-southeast-2" or "eu-central-1" or "eu-west-2" or "ap-northeast-2" or "ap-northeast-1" or "us-east-1" or "sa-east-1" or "us-west-1" or "us-west-2" or "ca-central-1" |
"us-east-1" |
dyno_cidr_blocks | array | The CIDR ranges that should be routed to the Private Space VPC. | ["10.0.0.0/16"] |
space_cidr_blocks | array | The CIDR ranges that should be routed to the Private Space VPC. | ["10.0.0.0/16"] |
unavailable_cidr_blocks | array | The CIDR ranges that you must not conflict with. | ["10.0.0.0/16"] |
vpc_cidr | string | The CIDR range of the Private Space VPC | "10.0.0.0/16" |
vpc_id | string | The AWS VPC ID of the peer. | "vpc-1234567890" |
Peering Info Info
Provides the necessary information to establish an AWS VPC Peering with your private space.
GET /spaces/{space_id_or_name}/peering-info
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/peering-info \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"aws_account_id": "123456789012",
"aws_region": "us-east-1",
"vpc_id": "vpc-1234567890",
"vpc_cidr": "10.0.0.0/16",
"dyno_cidr_blocks": [
"10.0.0.0/16"
],
"unavailable_cidr_blocks": [
"10.0.0.0/16"
],
"space_cidr_blocks": [
"10.0.0.0/16"
]
}
Permission Entity
Stability: development
An owned entity including users’ permissions.
Attributes
Name | Type | Description | Example |
---|---|---|---|
id | uuid | ID of the entity. | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | Name of the entity. | "polar-lake-12345" |
team_id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
type | string | The type of object the entity is referring to. one of: "app" or "space" |
"app" |
users/email | unique email address | "username@example.com" |
|
users/id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
users/permissions | array | enterprise account permissions | [null] |
Permission Entity List
List permission entities for a team.
GET /teams/{team_name_or_id}/permissions
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/permissions \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "polar-lake-12345",
"team_id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "app",
"users": [
{
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
null
]
}
]
}
]
Pipeline
Stability: production
A pipeline allows grouping of apps into different stages.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when pipeline was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | name of pipeline pattern: ^[a-z][a-z0-9-]{2,29}$ |
"example" |
owner | nullable object | Owner of a pipeline. | null |
owner:id | uuid | unique identifier of a pipeline owner | "01234567-89ab-cdef-0123-456789abcdef" |
owner:type | string | type of pipeline owner pattern: (^team$|^user$) |
"team" |
updated_at | date-time | when pipeline was updated | "2012-01-01T12:00:00Z" |
Pipeline Create
Create a new pipeline.
POST /pipelines
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | name of pipeline pattern: ^[a-z][a-z0-9-]{2,29}$ |
"example" |
Curl Example
$ curl -n -X POST https://api.heroku.com/pipelines \
-d '{
"name": "example",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "team"
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "team"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Info
Info for existing pipeline.
GET /pipelines/{pipeline_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "team"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Delete
Delete an existing pipeline.
DELETE /pipelines/{pipeline_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/pipelines/$PIPELINE_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "team"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Update
Update an existing pipeline.
PATCH /pipelines/{pipeline_id}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | name of pipeline pattern: ^[a-z][a-z0-9-]{2,29}$ |
"example" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/pipelines/$PIPELINE_ID \
-d '{
"name": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "team"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline List
List existing pipelines.
Acceptable order values for the Range header are id
or name
.
GET /pipelines
Curl Example
$ curl -n https://api.heroku.com/pipelines \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "team"
},
"updated_at": "2012-01-01T12:00:00Z"
}
]
Pipeline Build
Stability: production
Information about latest builds of apps in a pipeline.
Pipeline Build List
List latest builds for each app in a pipeline
GET /pipelines/{pipeline_id}/latest-builds
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/latest-builds \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby",
"name": "heroku/ruby"
}
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0",
"version_description": "* Fake User: Change session key"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stack": "heroku-22",
"status": "succeeded",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
}
}
]
Pipeline Config Vars
Stability: production
Pipeline Config Vars allow you to manage the configuration information provided to a pipeline.
Pipeline Config Vars Info for App
Get config-vars for a pipeline stage.
GET /pipelines/{pipeline_id}/stage/{pipeline_coupling_stage}/config-vars
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/stage/$PIPELINE_COUPLING_STAGE/config-vars \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"FOO": "bar",
"BAZ": "qux"
}
Pipeline Config Vars Update
Update config-vars for a pipeline stage. You can update existing config-vars by setting them again, and remove by setting it to null
.
PATCH /pipelines/{pipeline_id}/stage/{pipeline_coupling_stage}/config-vars
Curl Example
$ curl -n -X PATCH https://api.heroku.com/pipelines/$PIPELINE_ID/stage/$PIPELINE_COUPLING_STAGE/config-vars \
-d '{
"FOO": "bar",
"BAZ": "qux"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"FOO": "bar",
"BAZ": "qux"
}
Pipeline Coupling
Stability: production
Information about an app’s coupling to a pipeline
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
created_at | date-time | when pipeline coupling was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of pipeline coupling | "01234567-89ab-cdef-0123-456789abcdef" |
pipeline:id | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
stage | string | target pipeline stage one of: "test" or "review" or "development" or "staging" or "production" |
"production" |
updated_at | date-time | when pipeline coupling was updated | "2012-01-01T12:00:00Z" |
Pipeline Coupling List By Pipeline
List couplings for a pipeline
The only acceptable order value for the Range header is id
.
GET /pipelines/{pipeline_id}/pipeline-couplings
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/pipeline-couplings \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stage": "production",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Pipeline Coupling List By Current User
List pipeline couplings for the current user.
The only acceptable order value for the Range header is id
.
GET /users/~/pipeline-couplings
Curl Example
$ curl -n https://api.heroku.com/users/~/pipeline-couplings \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stage": "production",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Pipeline Coupling List
List pipeline couplings.
The only acceptable order value for the Range header is id
.
GET /pipeline-couplings
Curl Example
$ curl -n https://api.heroku.com/pipeline-couplings \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stage": "production",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Pipeline Coupling List By Team
List pipeline couplings for a team.
The only acceptable order value for the Range header is id
.
GET /teams/{team_name_or_id}/pipeline-couplings
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/pipeline-couplings \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stage": "production",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Pipeline Coupling Create
Create a new pipeline coupling.
POST /pipeline-couplings
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
app | string | unique identifier or name of app | "01234567-89ab-cdef-0123-456789abcdef" or "example" |
pipeline | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
stage | string | target pipeline stage one of: "test" or "review" or "development" or "staging" or "production" |
"production" |
Curl Example
$ curl -n -X POST https://api.heroku.com/pipeline-couplings \
-d '{
"app": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": "01234567-89ab-cdef-0123-456789abcdef",
"stage": "production"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stage": "production",
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Coupling Info
Info for an existing pipeline coupling.
GET /pipeline-couplings/{pipeline_coupling_id}
Curl Example
$ curl -n https://api.heroku.com/pipeline-couplings/$PIPELINE_COUPLING_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stage": "production",
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Coupling Delete
Delete an existing pipeline coupling.
DELETE /pipeline-couplings/{pipeline_coupling_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/pipeline-couplings/$PIPELINE_COUPLING_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stage": "production",
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Coupling Update
Update an existing pipeline coupling.
PATCH /pipeline-couplings/{pipeline_coupling_id}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
stage | string | target pipeline stage one of: "test" or "review" or "development" or "staging" or "production" |
"production" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/pipeline-couplings/$PIPELINE_COUPLING_ID \
-d '{
"stage": "production"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stage": "production",
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Coupling Info By App
Info for an existing pipeline coupling.
GET /apps/{app_id_or_name}/pipeline-couplings
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/pipeline-couplings \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stage": "production",
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Deployment
Stability: production
Information about latest deployments of apps in a pipeline.
Pipeline Deployment List
List latest slug releases for each app in a pipeline
GET /pipelines/{pipeline_id}/latest-deployments
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/latest-deployments \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon_plan_names": [
"heroku-postgresql:dev"
],
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "succeeded",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11,
"current": true,
"output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
}
]
Pipeline Promotion
Stability: production
Promotions allow you to move code from an app in a pipeline to all targets
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when promotion was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of promotion | "01234567-89ab-cdef-0123-456789abcdef" |
pipeline:id | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
source:app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
source:release:id | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
status | string | status of promotion one of: "pending" or "completed" |
"pending" |
updated_at | nullable date-time | when promotion was updated | "2012-01-01T12:00:00Z" |
Pipeline Promotion Create
Create a new promotion.
POST /pipeline-promotions
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
pipeline:id | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
source:app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
targets/app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
Curl Example
$ curl -n -X POST https://api.heroku.com/pipeline-promotions \
-d '{
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"source": {
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
},
"targets": [
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"source": {
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
},
"status": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Promotion Info
Info for existing pipeline promotion.
GET /pipeline-promotions/{pipeline_promotion_id}
Curl Example
$ curl -n https://api.heroku.com/pipeline-promotions/$PIPELINE_PROMOTION_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"source": {
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
},
"status": "pending",
"updated_at": "2012-01-01T12:00:00Z"
}
Pipeline Promotion Target
Stability: production
Promotion targets represent an individual app being promoted to
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
error_message | nullable string | an error message for why the promotion failed | "User does not have access to that app" |
id | uuid | unique identifier of promotion target | "01234567-89ab-cdef-0123-456789abcdef" |
pipeline_promotion:id | uuid | unique identifier of promotion | "01234567-89ab-cdef-0123-456789abcdef" |
release | nullable object | the release which was created on the target app | null |
release:id | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
status | string | status of promotion one of: "pending" or "succeeded" or "failed" |
"pending" |
Pipeline Promotion Target List
List promotion targets belonging to an existing promotion.
The only acceptable order value for the Range header is id
.
GET /pipeline-promotions/{pipeline_promotion_id}/promotion-targets
Curl Example
$ curl -n https://api.heroku.com/pipeline-promotions/$PIPELINE_PROMOTION_ID/promotion-targets \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"error_message": "User does not have access to that app",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline_promotion": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending"
}
]
Pipeline Release
Stability: production
Information about latest releases of apps in a pipeline.
Pipeline Release List
List latest releases for each app in a pipeline
GET /pipelines/{pipeline_id}/latest-releases
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/latest-releases \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon_plan_names": [
"heroku-postgresql:dev"
],
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "succeeded",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11,
"current": true,
"output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
}
]
Pipeline Stack
Stability: production
A pipeline’s stack is determined by the apps in the pipeline. This is used during creation of CI and Review Apps that have no stack defined in app.json
Attributes
Name | Type | Description | Example |
---|---|---|---|
stack | nullable object | identity of the stack that will be used for new builds without a stack defined in CI and Review Apps | null |
stack:id | uuid | identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
stack:name | string | unique name | "heroku-18" |
Pipeline Stack Default Stack
The stack for a given pipeline, used for CI and Review Apps that have no stack defined in app.json.
GET /pipelines/{pipeline_id}/pipeline-stack
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/pipeline-stack \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
}
}
Pipeline Transfer
Stability: production
A pipeline transfer is the process of changing pipeline ownership along with the contained apps.
Attributes
Name | Type | Description | Example |
---|---|---|---|
new_owner:id | uuid | unique identifier of a pipeline owner | "01234567-89ab-cdef-0123-456789abcdef" |
new_owner:type | string | type of pipeline owner pattern: (^team$|^user$) |
"team" |
pipeline:id | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
previous_owner:id | uuid | unique identifier of a pipeline owner | "01234567-89ab-cdef-0123-456789abcdef" |
previous_owner:type | string | type of pipeline owner pattern: (^team$|^user$) |
"team" |
Pipeline Transfer Create
Create a new pipeline transfer.
POST /pipeline-transfers
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
new_owner:id | uuid | unique identifier of a pipeline owner | "01234567-89ab-cdef-0123-456789abcdef" |
new_owner:type | string | type of pipeline owner pattern: (^team$|^user$) |
"team" |
pipeline:id | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
Curl Example
$ curl -n -X POST https://api.heroku.com/pipeline-transfers \
-d '{
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"new_owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "team"
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"previous_owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "team"
},
"new_owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"type": "team"
}
}
Plan
Stability: production
Plans represent different configurations of add-ons that may be added to apps. Endpoints under add-on services can be accessed without authentication.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addon_service:id | uuid | unique identifier of this add-on-service | "01234567-89ab-cdef-0123-456789abcdef" |
addon_service:name | string | unique name of this add-on-service | "heroku-postgresql" |
compliance | nullable array | the compliance regimes applied to an add-on plan | ["HIPAA"] |
created_at | date-time | when plan was created | "2012-01-01T12:00:00Z" |
default | boolean | whether this plan is the default for its add-on service | false |
description | string | description of plan | "Heroku Postgres Dev" |
human_name | string | human readable name of the add-on plan | "Dev" |
id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
installable_inside_private_network | boolean | whether this plan is installable to a Private Spaces app | false |
installable_outside_private_network | boolean | whether this plan is installable to a Common Runtime app | true |
name | string | name of this plan | "heroku-postgresql:dev" |
price:cents | integer | price in cents per unit of plan | 0 |
price:contract | boolean | price is negotiated in a contract outside of monthly add-on billing | false |
price:unit | string | unit of price for plan | "month" |
space_default | boolean | whether this plan is the default for apps in Private Spaces | false |
state | string | release status for plan | "public" |
updated_at | date-time | when plan was updated | "2012-01-01T12:00:00Z" |
visible | boolean | whether this plan is publicly visible | true |
Plan Info
Info for existing plan.
GET /plans/{plan_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/plans/$PLAN_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"created_at": "2012-01-01T12:00:00Z",
"compliance": [
"HIPAA"
],
"default": false,
"description": "Heroku Postgres Dev",
"human_name": "Dev",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"installable_inside_private_network": false,
"installable_outside_private_network": true,
"name": "heroku-postgresql:dev",
"price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"space_default": false,
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"visible": true
}
Plan Info By Add-on
Info for existing plan by Add-on.
GET /addon-services/{add_on_service_id_or_name}/plans/{plan_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/addon-services/$ADD_ON_SERVICE_ID_OR_NAME/plans/$PLAN_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"created_at": "2012-01-01T12:00:00Z",
"compliance": [
"HIPAA"
],
"default": false,
"description": "Heroku Postgres Dev",
"human_name": "Dev",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"installable_inside_private_network": false,
"installable_outside_private_network": true,
"name": "heroku-postgresql:dev",
"price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"space_default": false,
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"visible": true
}
Plan List By Add-on
List existing plans by Add-on.
Acceptable order values for the Range header are id
or name
.
GET /addon-services/{add_on_service_id_or_name}/plans
Curl Example
$ curl -n https://api.heroku.com/addon-services/$ADD_ON_SERVICE_ID_OR_NAME/plans \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"created_at": "2012-01-01T12:00:00Z",
"compliance": [
"HIPAA"
],
"default": false,
"description": "Heroku Postgres Dev",
"human_name": "Dev",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"installable_inside_private_network": false,
"installable_outside_private_network": true,
"name": "heroku-postgresql:dev",
"price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"space_default": false,
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"visible": true
}
]
Rate Limit
Stability: production
Rate Limit represents the number of request tokens each account holds. Requests to this endpoint do not count towards the rate limit.
Attributes
Name | Type | Description | Example |
---|---|---|---|
remaining | integer | allowed requests remaining in current interval | 2399 |
Rate Limit Info
Info for rate limits.
GET /account/rate-limits
Curl Example
$ curl -n https://api.heroku.com/account/rate-limits \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"remaining": 2399
}
Region
Stability: production
A region represents a geographic location in which your application may run.
Attributes
Name | Type | Description | Example |
---|---|---|---|
country | string | country where the region exists | "United States" |
created_at | date-time | when region was created | "2012-01-01T12:00:00Z" |
description | string | description of region | "United States" |
id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
locale | string | area in the country where the region exists | "Virginia" |
name | string | name of region | "us" |
private_capable | boolean | whether or not region is available for creating a Private Space | false |
provider:name | string | name of provider | "amazon-web-services" |
provider:region | string | region name used by provider one of: "ap-south-1" or "eu-west-1" or "ap-southeast-1" or "ap-southeast-2" or "eu-central-1" or "eu-west-2" or "ap-northeast-2" or "ap-northeast-1" or "us-east-1" or "sa-east-1" or "us-west-1" or "us-west-2" or "ca-central-1" |
"us-east-1" |
updated_at | date-time | when region was updated | "2012-01-01T12:00:00Z" |
Region Info
Info for existing region.
GET /regions/{region_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/regions/$REGION_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"country": "United States",
"created_at": "2012-01-01T12:00:00Z",
"description": "United States",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"locale": "Virginia",
"name": "us",
"private_capable": false,
"provider": {
"name": "amazon-web-services",
"region": "us-east-1"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Region List
List existing regions.
Acceptable order values for the Range header are id
or name
.
GET /regions
Curl Example
$ curl -n https://api.heroku.com/regions \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"country": "United States",
"created_at": "2012-01-01T12:00:00Z",
"description": "United States",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"locale": "Virginia",
"name": "us",
"private_capable": false,
"provider": {
"name": "amazon-web-services",
"region": "us-east-1"
},
"updated_at": "2012-01-01T12:00:00Z"
}
]
Release
Stability: production
A release represents a combination of code, config vars and add-ons for an app on Heroku.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addon_plan_names | array | add-on plans installed on the app for this release | ["heroku-postgresql:dev"] |
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
created_at | date-time | when release was created | "2012-01-01T12:00:00Z" |
current | boolean | indicates this release as being the current one for the app | true |
description | string | description of changes in this release | "Added new feature" |
id | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
output_stream_url | nullable string | Release command output will be available from this URL as a stream. The stream is available as either text/plain or text/event-stream . Clients should be prepared to handle disconnects and can resume the stream by sending a Range header (for text/plain ) or a Last-Event-Id header (for text/event-stream ). |
"https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef" |
slug | nullable object | slug running in this release | null |
slug:id | uuid | unique identifier of slug | "01234567-89ab-cdef-0123-456789abcdef" |
status | string | current status of the release one of: "failed" or "pending" or "succeeded" |
"succeeded" |
updated_at | date-time | when release was updated | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
version | integer | unique version assigned to the release | 11 |
Release Info
Info for existing release.
GET /apps/{app_id_or_name}/releases/{release_id_or_version}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/releases/$RELEASE_ID_OR_VERSION \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon_plan_names": [
"heroku-postgresql:dev"
],
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "succeeded",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11,
"current": true,
"output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
}
Release List
List existing releases.
Acceptable order values for the Range header are id
or version
.
GET /apps/{app_id_or_name}/releases
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/releases \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, version
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon_plan_names": [
"heroku-postgresql:dev"
],
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "succeeded",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11,
"current": true,
"output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
}
]
Release Create
Create new release.
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 \
-d '{
"description": "Added new feature",
"slug": "01234567-89ab-cdef-0123-456789abcdef"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon_plan_names": [
"heroku-postgresql:dev"
],
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "succeeded",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11,
"current": true,
"output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
}
Release Rollback
Rollback to an existing release.
POST /apps/{app_id_or_name}/releases
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
release | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/releases \
-d '{
"release": "01234567-89ab-cdef-0123-456789abcdef"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon_plan_names": [
"heroku-postgresql:dev"
],
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"description": "Added new feature",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "succeeded",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
},
"version": 11,
"current": true,
"output_stream_url": "https://release-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
}
Review App
Stability: production
An ephemeral app to review a set of changes
Attributes
Name | Type | Description | Example |
---|---|---|---|
app | nullable object | the Heroku app associated to this review app | null |
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app_setup | nullable object | the app setup for this review app | null |
app_setup:id | uuid | unique identifier of app setup | "01234567-89ab-cdef-0123-456789abcdef" |
branch | string | the branch of the repository which the review app is based on | "example" |
created_at | date-time | when test run was created | "2015-01-01T12:00:00Z" |
creator | object | The user who created the review app | |
error_status | nullable string | error message from creating the review app if any | null |
fork_repo | nullable object | null |
|
fork_repo:id | nullable integer | repository id of the fork the branch resides in | "123456" |
id | uuid | unique identifier of the review app | "01234567-89ab-cdef-0123-456789abcdef" |
message | nullable string | message from creating the review app if any | null |
pipeline:id | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
pr_number | nullable integer | pull request number the review app is built for | 24 |
status | string | current state of the review app one of: "pending" or "creating" or "created" or "deleting" or "deleted" or "errored" |
"pending" |
updated_at | date-time | when review app was updated | "2015-01-01T12:00:00Z" |
wait_for_ci | boolean | wait for ci before building the app | true |
Review App Create
Create a new review app
POST /review-apps
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
branch | string | the branch of the repository which the review app is based on | "example" |
pipeline | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
source_blob:url | string | URL where gzipped tar archive of source code for build was downloaded. | "https://example.com/source.tgz?token=xyz" |
source_blob:version | nullable string | The version number (or SHA) of the code to build. | "v1.2.0" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
environment | nullable object | A set of key value pairs which will be put into the environment of the spawned review app process. | {"FOO":"bar","BAZ":"qux"} |
fork_repo_id | nullable integer | repository id of the fork the branch resides in | "123456" |
pr_number | nullable integer | pull request number the review app is built for | 24 |
Curl Example
$ curl -n -X POST https://api.heroku.com/review-apps \
-d '{
"branch": "example",
"pr_number": 24,
"pipeline": "01234567-89ab-cdef-0123-456789abcdef",
"source_blob": {
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.2.0"
},
"environment": {
"FOO": "bar",
"BAZ": "qux"
},
"fork_repo_id": "123456"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"app_setup": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"branch": "example",
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"creator": null,
"wait_for_ci": true,
"error_status": "example",
"message": "example",
"fork_repo": {
"id": "123456"
},
"pr_number": 24
}
Review App Get review app
Gets an existing review app
GET /review-apps/{review_app_id}
Curl Example
$ curl -n https://api.heroku.com/review-apps/$REVIEW_APP_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"app_setup": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"branch": "example",
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"creator": null,
"wait_for_ci": true,
"error_status": "example",
"message": "example",
"fork_repo": {
"id": "123456"
},
"pr_number": 24
}
Review App Delete
Delete an existing review app
DELETE /review-apps/{review_app_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/review-apps/$REVIEW_APP_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"app_setup": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"branch": "example",
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"creator": null,
"wait_for_ci": true,
"error_status": "example",
"message": "example",
"fork_repo": {
"id": "123456"
},
"pr_number": 24
}
Review App Get review app by app_id
Get a review app using the associated app_id
GET /apps/{app_id_or_name}/review-app
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/review-app \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"app_setup": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"branch": "example",
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"creator": null,
"wait_for_ci": true,
"error_status": "example",
"message": "example",
"fork_repo": {
"id": "123456"
},
"pr_number": 24
}
Review App List
List review apps for a pipeline
The only acceptable order value for the Range header is id
.
GET /pipelines/{pipeline_id}/review-apps
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/review-apps \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"app_setup": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"branch": "example",
"created_at": "2015-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"creator": null,
"wait_for_ci": true,
"error_status": "example",
"message": "example",
"fork_repo": {
"id": "123456"
},
"pr_number": 24
}
]
Review App Configuration
Stability: production
Review apps can be configured for pipelines.
Attributes
Name | Type | Description | Example |
---|---|---|---|
automatic_review_apps | boolean | enable automatic review apps for pull requests | true |
base_name | nullable string | A unique prefix that will be used to create review app names | "singular-app" |
deploy_target | nullable object | the deploy target for the review apps of a pipeline | null |
deploy_target:id | string | unique identifier of deploy target pattern: (^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$|^[a-z]{2}$) |
"us" |
deploy_target:type | string | type of deploy target pattern: (^space$|^region$) |
"region" |
destroy_stale_apps | boolean | automatically destroy review apps when they haven’t been deployed for a number of days | true |
pipeline_id | uuid | unique identifier of pipeline | "01234567-89ab-cdef-0123-456789abcdef" |
repo:id | integer | repository id | "123456" |
stale_days | integer | number of days without a deployment after which to consider a review app stale | "5" |
wait_for_ci | boolean | If true, review apps are created only when CI passes | true |
Review App Configuration Enable
Enable review apps for a pipeline
POST /pipelines/{pipeline_id}/review-app-config
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
repo | string | The full_name of the repository that you want enable review-apps from. | "heroku/homebrew-brew" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
automatic_review_apps | boolean | If true, this will trigger the creation of review apps when pull-requests are opened in the repo. | true |
base_name | nullable string | A unique prefix that will be used to create review app names | "singular-app" |
deploy_target | nullable object | Provides a key/value pair to specify whether to use a common runtime or a private space | null |
deploy_target:id | string | unique identifier of deploy target pattern: (^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$|^[a-z]{2}$) |
"us" |
deploy_target:type | string | type of deploy target pattern: (^space$|^region$) |
"region" |
destroy_stale_apps | boolean | If true, this will trigger automatic deletion of review apps when they’re stale | true |
stale_days | integer | If destroy_stale_apps is true, then apps will be destroyed after this many days | "5" |
wait_for_ci | boolean | If true, review apps will only be created when CI passes | true |
Curl Example
$ curl -n -X POST https://api.heroku.com/pipelines/$PIPELINE_ID/review-app-config \
-d '{
"repo": "heroku/homebrew-brew",
"automatic_review_apps": true,
"destroy_stale_apps": true,
"stale_days": "5",
"deploy_target": {
"id": "us",
"type": "region"
},
"wait_for_ci": true,
"base_name": "singular-app"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"repo": {
"id": "123456"
},
"automatic_review_apps": true,
"deploy_target": {
"id": "us",
"type": "region"
},
"destroy_stale_apps": true,
"stale_days": "5",
"pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
"wait_for_ci": true,
"base_name": "singular-app"
}
Review App Configuration Info
Get review apps configuration for a pipeline
GET /pipelines/{pipeline_id}/review-app-config
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/review-app-config \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"repo": {
"id": "123456"
},
"automatic_review_apps": true,
"deploy_target": {
"id": "us",
"type": "region"
},
"destroy_stale_apps": true,
"stale_days": "5",
"pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
"wait_for_ci": true,
"base_name": "singular-app"
}
Review App Configuration Update
Update review app configuration for a pipeline
PATCH /pipelines/{pipeline_id}/review-app-config
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
automatic_review_apps | boolean | If true, this will trigger the creation of review apps when pull-requests are opened in the repo | true |
base_name | nullable string | A unique prefix that will be used to create review app names | "singular-app" |
deploy_target | nullable object | Provides a key/value pair to specify whether to use a common runtime or a private space | null |
deploy_target:id | string | unique identifier of deploy target pattern: (^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$|^[a-z]{2}$) |
"us" |
deploy_target:type | string | type of deploy target pattern: (^space$|^region$) |
"region" |
destroy_stale_apps | boolean | If true, this will trigger automatic deletion of review apps when they’re stale | true |
stale_days | integer | If destroy_stale_apps is true, then apps will be destroyed after this many days | "5" |
wait_for_ci | boolean | If true, review apps will only be created when CI passes | true |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/pipelines/$PIPELINE_ID/review-app-config \
-d '{
"automatic_review_apps": true,
"destroy_stale_apps": true,
"stale_days": "5",
"deploy_target": {
"id": "us",
"type": "region"
},
"wait_for_ci": true,
"base_name": "singular-app"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"repo": {
"id": "123456"
},
"automatic_review_apps": true,
"deploy_target": {
"id": "us",
"type": "region"
},
"destroy_stale_apps": true,
"stale_days": "5",
"pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
"wait_for_ci": true,
"base_name": "singular-app"
}
Review App Configuration Delete
Disable review apps for a pipeline
DELETE /pipelines/{pipeline_id}/review-app-config
Curl Example
$ curl -n -X DELETE https://api.heroku.com/pipelines/$PIPELINE_ID/review-app-config \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"repo": {
"id": "123456"
},
"automatic_review_apps": true,
"deploy_target": {
"id": "us",
"type": "region"
},
"destroy_stale_apps": true,
"stale_days": "5",
"pipeline_id": "01234567-89ab-cdef-0123-456789abcdef",
"wait_for_ci": true,
"base_name": "singular-app"
}
Slug
Stability: production
A slug is a snapshot of your application code that is ready to run on the platform.
Attributes
Name | Type | Description | Example |
---|---|---|---|
blob:method | string | method to be used to interact with the slug blob | "GET" |
blob:url | string | URL to interact with the slug blob | "https://api.heroku.com/slugs/1234.tgz" |
buildpack_provided_description | nullable string | description from buildpack of slug | "Ruby/Rack" |
checksum | nullable string | an optional checksum of the slug for verifying its integrity | "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" |
commit | nullable string | identification of the code with your version control system (eg: SHA of the git HEAD) | "60883d9e8947a57e04dc9124f25df004866a2051" |
commit_description | nullable string | an optional description of the provided commit | "fixed a bug with API documentation" |
created_at | date-time | when slug was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of slug | "01234567-89ab-cdef-0123-456789abcdef" |
process_types | object | hash mapping process type names to their respective command | {"web":"./bin/web -p $PORT"} |
size | nullable integer | size of slug, in bytes | 2048 |
stack:id | uuid | identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
stack:name | string | unique name | "heroku-18" |
updated_at | date-time | when slug was updated | "2012-01-01T12:00:00Z" |
Slug Info
Info for existing slug.
GET /apps/{app_id_or_name}/slugs/{slug_id}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/slugs/$SLUG_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"blob": {
"method": "GET",
"url": "https://api.heroku.com/slugs/1234.tgz"
},
"buildpack_provided_description": "Ruby/Rack",
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"commit": "60883d9e8947a57e04dc9124f25df004866a2051",
"commit_description": "fixed a bug with API documentation",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"process_types": {
"web": "./bin/web -p $PORT"
},
"size": 2048,
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Slug Create
Create a new slug. For more information please refer to Deploying Slugs using the Platform API.
POST /apps/{app_id_or_name}/slugs
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
process_types | object | hash mapping process type names to their respective command | {"web":"./bin/web -p $PORT"} |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
buildpack_provided_description | nullable string | description from buildpack of slug | "Ruby/Rack" |
checksum | nullable string | an optional checksum of the slug for verifying its integrity | "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" |
commit | nullable string | identification of the code with your version control system (eg: SHA of the git HEAD) | "60883d9e8947a57e04dc9124f25df004866a2051" |
commit_description | nullable string | an optional description of the provided commit | "fixed a bug with API documentation" |
stack | string | unique name or identifier of stack | "heroku-18" or "01234567-89ab-cdef-0123-456789abcdef" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/slugs \
-d '{
"buildpack_provided_description": "Ruby/Rack",
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"commit": "60883d9e8947a57e04dc9124f25df004866a2051",
"commit_description": "fixed a bug with API documentation",
"process_types": {
"web": "./bin/web -p $PORT"
},
"stack": "01234567-89ab-cdef-0123-456789abcdef"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"blob": {
"method": "PUT",
"url": "https://api.heroku.com/slugs/1234.tgz"
},
"buildpack_provided_description": "Ruby/Rack",
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"commit": "60883d9e8947a57e04dc9124f25df004866a2051",
"commit_description": "fixed a bug with API documentation",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"process_types": {
"web": "./bin/web -p $PORT"
},
"size": 2048,
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z"
}
SMS Number
Stability: production
SMS numbers are used for recovery on accounts with two-factor authentication enabled.
Attributes
Name | Type | Description | Example |
---|---|---|---|
sms_number | nullable string | SMS number of account | "+1 ***-***-1234" |
SMS Number SMS Number
Recover an account using an SMS recovery code
GET /users/{account_email_or_id_or_self}/sms-number
Curl Example
$ curl -n https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF/sms-number \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"sms_number": "+1 ***-***-1234"
}
SMS Number Recover
Recover an account using an SMS recovery code
POST /users/{account_email_or_id_or_self}/sms-number/actions/recover
Curl Example
$ curl -n -X POST https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF/sms-number/actions/recover \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"sms_number": "+1 ***-***-1234"
}
SMS Number Confirm
Confirm an SMS number change with a confirmation code
POST /users/{account_email_or_id_or_self}/sms-number/actions/confirm
Curl Example
$ curl -n -X POST https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF/sms-number/actions/confirm \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"sms_number": "+1 ***-***-1234"
}
SNI Endpoint
Stability: development
SNI Endpoint is a public address serving a custom SSL cert for HTTPS traffic, using the SNI TLS extension, to a Heroku app.
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
created_at | date-time | when endpoint was created | "2012-01-01T12:00:00Z" |
display_name | nullable string | unique name for SSL certificate pattern: ^[a-z][a-z0-9-]{2,29}$ |
"example" |
domains | array | domains associated with this SSL certificate | ["01234567-89ab-cdef-0123-456789abcdef"] |
id | uuid | unique identifier of this SNI endpoint | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name for SNI endpoint pattern: ^[a-z][a-z0-9-]{2,29}$ |
"example" |
ssl_cert:ca_signed? | boolean | true |
|
ssl_cert:cert_domains | array | ||
ssl_cert:expires_at | date-time | "2015-01-01T12:00:00Z" |
|
ssl_cert:id | uuid | unique identifier of this SSL certificate | "01234567-89ab-cdef-0123-456789abcdef" |
ssl_cert:issuer | string | "example" |
|
ssl_cert:self_signed? | boolean | true |
|
ssl_cert:starts_at | date-time | "2015-01-01T12:00:00Z" |
|
ssl_cert:subject | string | "example" |
|
updated_at | date-time | when SNI endpoint was updated | "2012-01-01T12:00:00Z" |
SNI Endpoint Create
Create a new SNI endpoint.
POST /apps/{app_id_or_name}/sni-endpoints
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
private_key | string | contents of the private key (eg .key file) | "-----BEGIN RSA PRIVATE KEY----- ..." |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/sni-endpoints \
-d '{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"private_key": "-----BEGIN RSA PRIVATE KEY----- ..."
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "example",
"domains": [
"01234567-89ab-cdef-0123-456789abcdef"
],
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"ssl_cert": {
"ca_signed?": true,
"cert_domains": null,
"expires_at": "2015-01-01T12:00:00Z",
"issuer": "example",
"self_signed?": true,
"starts_at": "2015-01-01T12:00:00Z",
"subject": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
SNI Endpoint Delete
Delete existing SNI endpoint.
DELETE /apps/{app_id_or_name}/sni-endpoints/{sni_endpoint_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/sni-endpoints/$SNI_ENDPOINT_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "example",
"domains": [
"01234567-89ab-cdef-0123-456789abcdef"
],
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"ssl_cert": {
"ca_signed?": true,
"cert_domains": null,
"expires_at": "2015-01-01T12:00:00Z",
"issuer": "example",
"self_signed?": true,
"starts_at": "2015-01-01T12:00:00Z",
"subject": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
SNI Endpoint Info
Info for existing SNI endpoint.
GET /apps/{app_id_or_name}/sni-endpoints/{sni_endpoint_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/sni-endpoints/$SNI_ENDPOINT_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "example",
"domains": [
"01234567-89ab-cdef-0123-456789abcdef"
],
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"ssl_cert": {
"ca_signed?": true,
"cert_domains": null,
"expires_at": "2015-01-01T12:00:00Z",
"issuer": "example",
"self_signed?": true,
"starts_at": "2015-01-01T12:00:00Z",
"subject": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
SNI Endpoint List
List existing SNI endpoints.
Acceptable order values for the Range header are id
or name
.
GET /apps/{app_id_or_name}/sni-endpoints
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/sni-endpoints \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "example",
"domains": [
"01234567-89ab-cdef-0123-456789abcdef"
],
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"ssl_cert": {
"ca_signed?": true,
"cert_domains": null,
"expires_at": "2015-01-01T12:00:00Z",
"issuer": "example",
"self_signed?": true,
"starts_at": "2015-01-01T12:00:00Z",
"subject": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
]
SNI Endpoint Update
Update an existing SNI endpoint.
PATCH /apps/{app_id_or_name}/sni-endpoints/{sni_endpoint_id_or_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
private_key | string | contents of the private key (eg .key file) | "-----BEGIN RSA PRIVATE KEY----- ..." |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/sni-endpoints/$SNI_ENDPOINT_ID_OR_NAME \
-d '{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"private_key": "-----BEGIN RSA PRIVATE KEY----- ..."
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "example",
"domains": [
"01234567-89ab-cdef-0123-456789abcdef"
],
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"ssl_cert": {
"ca_signed?": true,
"cert_domains": null,
"expires_at": "2015-01-01T12:00:00Z",
"issuer": "example",
"self_signed?": true,
"starts_at": "2015-01-01T12:00:00Z",
"subject": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Source
Stability: production
A source is a location for uploading and downloading an application’s source code.
Attributes
Name | Type | Description | Example |
---|---|---|---|
source_blob:get_url | string | URL to download the source | "https://api.heroku.com/sources/1234.tgz" |
source_blob:put_url | string | URL to upload the source | "https://api.heroku.com/sources/1234.tgz" |
Source Create
Create URLs for uploading and downloading source.
POST /sources
Curl Example
$ curl -n -X POST https://api.heroku.com/sources \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"source_blob": {
"get_url": "https://api.heroku.com/sources/1234.tgz",
"put_url": "https://api.heroku.com/sources/1234.tgz"
}
}
Source Create - Deprecated
Create URLs for uploading and downloading source. Deprecated in favor of POST /sources
POST /apps/{app_id_or_name}/sources
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/sources \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"source_blob": {
"get_url": "https://api.heroku.com/sources/1234.tgz",
"put_url": "https://api.heroku.com/sources/1234.tgz"
}
}
Space
Stability: production
A space is an isolated, highly available, secure app execution environment.
Attributes
Name | Type | Description | Example |
---|---|---|---|
cidr | string | The RFC-1918 CIDR the Private Space will use. It must be a /16 in 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16 default: "10.0.0.0/16" pattern: ^((?:10|172.(?:1[6-9]|2[0-9]|3[01])|192.168)..*.+\/16)$ |
"172.20.20.30/16" |
created_at | date-time | when space was created | "2012-01-01T12:00:00Z" |
data_cidr | string | The RFC-1918 CIDR that the Private Space will use for the Heroku-managed peering connection that’s automatically created when using Heroku Data add-ons. It must be between a /16 and a /20 | "10.2.0.0/16" |
id | uuid | unique identifier of space | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$ |
"nasa" |
organization:name | string | unique name of team | "example" |
region:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
region:name | string | name of region | "us" |
shield | boolean | true if this space has shield enabled | true |
state | string | availability of this space one of: "allocating" or "allocated" or "deleting" |
"allocated" |
team:id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
team:name | string | unique name of team | "example" |
updated_at | date-time | when space was updated | "2012-01-01T12:00:00Z" |
Space List
List existing spaces.
Acceptable order values for the Range header are id
or name
.
GET /spaces
Curl Example
$ curl -n https://api.heroku.com/spaces \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"organization": {
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"shield": true,
"state": "allocated",
"updated_at": "2012-01-01T12:00:00Z",
"cidr": "172.20.20.30/16",
"data_cidr": "10.2.0.0/16"
}
]
Space Info
Info for existing space.
GET /spaces/{space_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"organization": {
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"shield": true,
"state": "allocated",
"updated_at": "2012-01-01T12:00:00Z",
"cidr": "172.20.20.30/16",
"data_cidr": "10.2.0.0/16"
}
Space Update
Update an existing space.
PATCH /spaces/{space_id_or_name}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$ |
"nasa" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/spaces/$SPACE_ID_OR_NAME \
-d '{
"name": "nasa"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"organization": {
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"shield": true,
"state": "allocated",
"updated_at": "2012-01-01T12:00:00Z",
"cidr": "172.20.20.30/16",
"data_cidr": "10.2.0.0/16"
}
Space Delete
Delete an existing space.
DELETE /spaces/{space_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/spaces/$SPACE_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"organization": {
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"shield": true,
"state": "allocated",
"updated_at": "2012-01-01T12:00:00Z",
"cidr": "172.20.20.30/16",
"data_cidr": "10.2.0.0/16"
}
Space Create
Create a new space.
POST /spaces
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$ |
"nasa" |
team | string | unique name of team | "example" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
cidr | string | The RFC-1918 CIDR the Private Space will use. It must be a /16 in 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16 default: "10.0.0.0/16" pattern: ^((?:10|172.(?:1[6-9]|2[0-9]|3[01])|192.168)..*.+\/16)$ |
"172.20.20.30/16" |
data_cidr | string | The RFC-1918 CIDR that the Private Space will use for the Heroku-managed peering connection that’s automatically created when using Heroku Data add-ons. It must be between a /16 and a /20 | "10.2.0.0/16" |
log_drain_url | string | URL to which all apps will drain logs. Only settable during space creation and enables direct logging. Must use HTTPS. | "https://example.com/logs" |
region | string | unique identifier or name of region | "01234567-89ab-cdef-0123-456789abcdef" or "us" |
shield | boolean | true if this space has shield enabled | true |
Curl Example
$ curl -n -X POST https://api.heroku.com/spaces \
-d '{
"name": "nasa",
"team": "example",
"region": "01234567-89ab-cdef-0123-456789abcdef",
"shield": true,
"cidr": "172.20.20.30/16",
"data_cidr": "10.2.0.0/16",
"log_drain_url": "https://example.com/logs"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"organization": {
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"shield": true,
"state": "allocated",
"updated_at": "2012-01-01T12:00:00Z",
"cidr": "172.20.20.30/16",
"data_cidr": "10.2.0.0/16"
}
Space Access
Stability: prototype
Space access represents the permissions a particular user has on a particular space.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when space was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of space | "01234567-89ab-cdef-0123-456789abcdef" |
permissions/description | string | "example" |
|
permissions/name | string | "example" |
|
space:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
space:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
updated_at | date-time | when space was updated | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
Space Access Info
List permissions for a given user on a given space.
GET /spaces/{space_id_or_name}/members/{account_email_or_id_or_self}
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/members/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"space": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"description": "example",
"name": "example"
}
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Space Access Update
Update an existing user’s set of permissions on a space.
PATCH /spaces/{space_id_or_name}/members/{account_email_or_id_or_self}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
permissions/name | string | "example" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/members/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
-d '{
"permissions": [
{
"name": "example"
}
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"space": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"description": "example",
"name": "example"
}
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Space Access List
List all users and their permissions on a space.
The only acceptable order value for the Range header is id
.
GET /spaces/{space_id_or_name}/members
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/members \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"space": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"description": "example",
"name": "example"
}
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
]
Space Network Address Translation
Stability: prototype
Network address translation (NAT) for stable outbound IP addresses from a space
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when network address translation for a space was created | "2012-01-01T12:00:00Z" |
sources | array | potential IPs from which outbound network traffic will originate | ["123.123.123.123"] |
state | string | availability of network address translation for a space one of: "disabled" or "updating" or "enabled" |
"enabled" |
updated_at | date-time | when network address translation for a space was updated | "2012-01-01T12:00:00Z" |
Space Network Address Translation Info
Current state of network address translation for a space.
GET /spaces/{space_id_or_name}/nat
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/nat \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"sources": [
"123.123.123.123"
],
"state": "enabled",
"updated_at": "2012-01-01T12:00:00Z"
}
Space Topology
Stability: prototype
Space Topology provides you with a mechanism for viewing all the running dynos, formations and applications for a space. This is the same data thats used to power our DNS Service Discovery.
Attributes
Name | Type | Description | Example |
---|---|---|---|
apps/domains | array | ["example.com","example.net"] |
|
apps/formation | array | formations for application | [{"id":"01234567-89ab-cdef-0123-456789abcdef","process_type":"web","dynos":[{"id":"01234567-89ab-cdef-0123-456789abcdef","number":1,"private_ip":"10.0.134.42","hostname":"1.example-app-90210.app.localspace"}]}] |
apps/id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
version | integer | version of the space topology payload | 1 |
Space Topology Topology
Current space topology
GET /spaces/{space_id_or_name}/topology
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/topology \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"version": 1,
"apps": [
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"domains": [
"example.com",
"example.net"
],
"formation": [
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"process_type": "web",
"dynos": [
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"number": 1,
"private_ip": "10.0.134.42",
"hostname": "1.example-app-90210.app.localspace"
}
]
}
]
}
]
}
Space Transfer
Stability: development
Transfer spaces between enterprise teams with the same Enterprise Account.
Space Transfer transfer
Transfer space between enterprise teams
POST /spaces/{space_id_or_name}/transfer
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
new_owner | string | unique name of team | "example" |
Curl Example
$ curl -n -X POST https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/transfer \
-d '{
"new_owner": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"organization": {
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"shield": true,
"state": "allocated",
"updated_at": "2012-01-01T12:00:00Z",
"cidr": "172.20.20.30/16",
"data_cidr": "10.2.0.0/16"
}
Stack
Stability: production
Stacks are the different application execution environments available in the Heroku platform.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when stack was introduced | "2012-01-01T12:00:00Z" |
default | boolean | indicates this stack is the default for new apps | true |
id | uuid | identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name | "heroku-18" |
state | string | availability of this stack: beta, deprecated or public | "public" |
updated_at | date-time | when stack was last modified | "2012-01-01T12:00:00Z" |
Stack Info
Stack info.
GET /stacks/{stack_name_or_id}
Curl Example
$ curl -n https://api.heroku.com/stacks/$STACK_NAME_OR_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"default": true,
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
Stack List
List available stacks.
Acceptable order values for the Range header are id
or name
.
GET /stacks
Curl Example
$ curl -n https://api.heroku.com/stacks \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"default": true,
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Team
Stability: development
Teams allow you to manage access to a shared group of applications and other resources.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when the team was created | "2012-01-01T12:00:00Z" |
credit_card_collections | boolean | whether charges incurred by the team are paid by credit card. | true |
default | boolean | whether to use this team when none is specified | true |
enterprise_account | nullable object | null |
|
enterprise_account:id | uuid | unique identifier of the enterprise account | "01234567-89ab-cdef-0123-456789abcdef" |
enterprise_account:name | string | unique name of the enterprise account | "example" |
id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider | nullable object | Identity Provider associated with the Team | null |
identity_provider:id | uuid | unique identifier of this identity provider | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:name | string | user-friendly unique identifier for this identity provider | "acme-sso" |
identity_provider:owner:id | uuid | unique identifier of the owner | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:owner:name | string | name of the owner | "acme" |
identity_provider:owner:type | string | type of the owner one of: "team" or "enterprise-account" |
"team" |
membership_limit | nullable number | upper limit of members allowed in a team. | 25 |
name | string | unique name of team | "example" |
provisioned_licenses | boolean | whether the team is provisioned licenses by salesforce. | true |
role | nullable string | role in the team one of: "admin" or "collaborator" or "member" or "owner" or null |
"admin" |
type | string | type of team. one of: "enterprise" or "team" |
"team" |
updated_at | date-time | when the team was updated | "2012-01-01T12:00:00Z" |
Team List
List teams in which you are a member.
Acceptable order values for the Range header are id
or name
.
GET /teams
Curl Example
$ curl -n https://api.heroku.com/teams \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"credit_card_collections": true,
"default": true,
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Team Info
Info for a team.
GET /teams/{team_name_or_id}
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"credit_card_collections": true,
"default": true,
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
Team Update
Update team properties.
PATCH /teams/{team_name_or_id}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
default | boolean | whether to use this team when none is specified | true |
name | string | unique name of team | "example" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/teams/$TEAM_NAME_OR_ID \
-d '{
"default": true,
"name": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"credit_card_collections": true,
"default": true,
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
Team Create
Create a new team.
POST /teams
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | unique name of team | "example" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
address_1 | string | street address line 1 | "40 Hickory Lane" |
address_2 | nullable string | street address line 2 | "Suite 103" |
card_number | nullable string | encrypted card number of payment method | "encrypted-card-number" |
city | string | city | "San Francisco" |
country | string | country | "US" |
cvv | nullable string | card verification value | "123" |
device_data | nullable string | Device data string generated by the client | "VGhpcyBpcyBhIGdvb2QgZGF5IHRvIGRpZQ==" |
expiration_month | nullable string | expiration month | "11" |
expiration_year | nullable string | expiration year | "2014" |
first_name | string | the first name for payment method | "Jason" |
last_name | string | the last name for payment method | "Walker" |
nonce | nullable string | Nonce generated by Braintree hosted fields form | "VGhpcyBpcyBhIGdvb2QgZGF5IHRvIGRpZQ==" |
other | nullable string | metadata | "Additional information for payment method" |
postal_code | string | postal code | "90210" |
state | string | state | "CA" |
Curl Example
$ curl -n -X POST https://api.heroku.com/teams \
-d '{
"name": "example",
"address_1": "40 Hickory Lane",
"address_2": "Suite 103",
"card_number": "encrypted-card-number",
"city": "San Francisco",
"country": "US",
"cvv": "123",
"expiration_month": "11",
"expiration_year": "2014",
"first_name": "Jason",
"last_name": "Walker",
"other": "Additional information for payment method",
"postal_code": "90210",
"state": "CA",
"nonce": "VGhpcyBpcyBhIGdvb2QgZGF5IHRvIGRpZQ==",
"device_data": "VGhpcyBpcyBhIGdvb2QgZGF5IHRvIGRpZQ=="
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"credit_card_collections": true,
"default": true,
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
Team Delete
Delete an existing team.
DELETE /teams/{team_name_or_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/teams/$TEAM_NAME_OR_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"credit_card_collections": true,
"default": true,
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
Team List by Enterprise Account
List teams for an enterprise account.
Acceptable order values for the Range header are id
or name
.
GET /enterprise-accounts/{enterprise_account_id_or_name}/teams
Curl Example
$ curl -n https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/teams \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"credit_card_collections": true,
"default": true,
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Team Create in Enterprise Account
Create a team in an enterprise account.
POST /enterprise-accounts/{enterprise_account_id_or_name}/teams
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | unique name of team | "example" |
Curl Example
$ curl -n -X POST https://api.heroku.com/enterprise-accounts/$ENTERPRISE_ACCOUNT_ID_OR_NAME/teams \
-d '{
"name": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"credit_card_collections": true,
"default": true,
"enterprise_account": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
Team Add-on
Stability: production
Team Add-on List For Team
List add-ons used across all Team apps
GET /teams/{team_name_or_id}/addons
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/addons \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"billing_entity": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"type": "app"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"contract": false,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"provision_message": "example",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Team App
Stability: development
A team app encapsulates the team specific functionality of Heroku apps.
Attributes
Name | Type | Description | Example |
---|---|---|---|
archived_at | nullable date-time | when app was archived | "2012-01-01T12:00:00Z" |
build_stack:id | uuid | identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
build_stack:name | string | unique name | "heroku-18" |
buildpack_provided_description | nullable string | description from buildpack of app | "Ruby/Rack" |
created_at | date-time | when app was created | "2012-01-01T12:00:00Z" |
git_url | string | git repo URL of app pattern: ^https://git.heroku.com/[a-z][a-z0-9-]{2,29}.git$ |
"https://git.heroku.com/example.git" |
id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
internal_routing | nullable boolean | describes whether a Private Spaces app is externally routable or not | false |
joined | boolean | is the current member a collaborator on this app. | false |
locked | boolean | are other team members forbidden from joining this app. | false |
maintenance | boolean | maintenance status of app | false |
name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
owner | nullable object | identity of app owner | null |
owner:email | unique email address | "username@example.com" |
|
owner:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
region:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
region:name | string | name of region | "us" |
released_at | nullable date-time | when app was released | "2012-01-01T12:00:00Z" |
repo_size | nullable integer | git repo size in bytes of app | 0 |
slug_size | nullable integer | slug size in bytes of app | 0 |
space | nullable object | identity of space | null |
space:id | uuid | unique identifier of space | "01234567-89ab-cdef-0123-456789abcdef" |
space:name | string | unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$ |
"nasa" |
stack:id | uuid | identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
stack:name | string | unique name | "heroku-18" |
team | nullable object | team that owns this app | null |
team:name | string | unique name of team | "example" |
updated_at | date-time | when app was updated | "2012-01-01T12:00:00Z" |
web_url | nullable uri | web URL of app pattern: ^https?://[a-z][a-z0-9-]{3,43}.herokuapp.com/$ |
"https://example.herokuapp.com/" |
Team App Create
Create a new app in the specified team, in the default team if unspecified, or in personal account, if default team is not set.
POST /teams/apps
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
internal_routing | nullable boolean | describes whether a Private Spaces app is externally routable or not | false |
locked | boolean | are other team members forbidden from joining this app. | false |
name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
personal | boolean | force creation of the app in the user account even if a default team is set. | false |
region | string | name of region | "us" |
space | string | unique name of space pattern: ^[a-z0-9](?:[a-z0-9]|-(?!-))+[a-z0-9]$ |
"nasa" |
stack | string | unique name | "heroku-18" |
team | string | unique name of team | "example" |
Curl Example
$ curl -n -X POST https://api.heroku.com/teams/apps \
-d '{
"locked": false,
"name": "example",
"team": "example",
"personal": false,
"region": "us",
"space": "nasa",
"stack": "heroku-18",
"internal_routing": false
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Team App Info
Info for a team app.
GET /teams/apps/{team_app_name}
Curl Example
$ curl -n https://api.heroku.com/teams/apps/$TEAM_APP_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Team App Update Locked
Lock or unlock a team app.
PATCH /teams/apps/{team_app_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
locked | boolean | are other team members forbidden from joining this app. | false |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/teams/apps/$TEAM_APP_NAME \
-d '{
"locked": false
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Team App Transfer to Account
Transfer an existing team app to another Heroku account.
PATCH /teams/apps/{team_app_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
owner | string | unique email address, identifier of an account or Implicit reference to currently authorized user | "username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" or "~" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/teams/apps/$TEAM_APP_NAME \
-d '{
"owner": "01234567-89ab-cdef-0123-456789abcdef"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Team App Transfer to Team
Transfer an existing team app to another team.
PATCH /teams/apps/{team_app_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
owner | string | unique name of team | "example" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/teams/apps/$TEAM_APP_NAME \
-d '{
"owner": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Team App List By Team
List team apps.
The only acceptable order value for the Range header is name
.
GET /teams/{team_name_or_id}/apps
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/apps \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
Team App Collaborator
Stability: development
A team collaborator represents an account that has been given access to a team app on Heroku.
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{1,28}[a-z0-9]$ |
"example" |
created_at | date-time | when collaborator was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of collaborator | "01234567-89ab-cdef-0123-456789abcdef" |
permissions | array | array of permissions for the collaborator (only applicable if the app is on a team) | [{"name":"view","description":"Can manage config, deploy, run commands and restart the app."}] |
role | nullable string | role in the team one of: "admin" or "collaborator" or "member" or "owner" or null |
"admin" |
updated_at | date-time | when collaborator was updated | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:federated | boolean | whether the user is federated and belongs to an Identity Provider | false |
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
Team App Collaborator Create
Create a new collaborator on a team app. Use this endpoint instead of the /apps/{app_id_or_name}/collaborator
endpoint when you want the collaborator to be granted permissions according to their role in the team.
POST /teams/apps/{app_id_or_name}/collaborators
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
user | string | unique email address, identifier of an account or Implicit reference to currently authorized user | "username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" or "~" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
permissions | array | An array of permissions to give to the collaborator. | ["view"] |
silent | boolean | whether to suppress email invitation when creating collaborator | false |
Curl Example
$ curl -n -X POST https://api.heroku.com/teams/apps/$APP_ID_OR_NAME/collaborators \
-d '{
"permissions": [
"view"
],
"silent": false,
"user": "01234567-89ab-cdef-0123-456789abcdef"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
],
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Team App Collaborator Delete
Delete an existing collaborator from a team app.
DELETE /teams/apps/{team_app_name}/collaborators/{team_app_collaborator_email}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/teams/apps/$TEAM_APP_NAME/collaborators/$TEAM_APP_COLLABORATOR_EMAIL \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
],
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Team App Collaborator Info
Info for a collaborator on a team app.
GET /teams/apps/{team_app_name}/collaborators/{team_app_collaborator_email}
Curl Example
$ curl -n https://api.heroku.com/teams/apps/$TEAM_APP_NAME/collaborators/$TEAM_APP_COLLABORATOR_EMAIL \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
],
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Team App Collaborator Update
Update an existing collaborator from a team app.
PATCH /teams/apps/{team_app_name}/collaborators/{team_app_collaborator_email}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
permissions | array | An array of permissions to give to the collaborator. | ["view"] |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/teams/apps/$TEAM_APP_NAME/collaborators/$TEAM_APP_COLLABORATOR_EMAIL \
-d '{
"permissions": [
"view"
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
],
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Team App Collaborator List
List collaborators on a team app.
The only acceptable order value for the Range header is email
.
GET /teams/apps/{team_app_name}/collaborators
Curl Example
$ curl -n https://api.heroku.com/teams/apps/$TEAM_APP_NAME/collaborators \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: email
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"permissions": [
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
],
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
]
Team App Permission
Stability: prototype
A team app permission is a behavior that is assigned to a user in a team app.
Attributes
Name | Type | Description | Example |
---|---|---|---|
description | string | A description of what the app permission allows. | "Can manage config, deploy, run commands and restart the app." |
name | string | The name of the app permission. | "view" |
Team App Permission List
Lists permissions available to teams.
The only acceptable order value for the Range header is name
.
GET /teams/permissions
Curl Example
$ curl -n https://api.heroku.com/teams/permissions \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"name": "view",
"description": "Can manage config, deploy, run commands and restart the app."
}
]
Team Daily Usage
Stability: development
Usage for an enterprise team at a daily resolution.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addons | number | total add-on credits used | 250.0 |
apps | array | app usage in the team | [{"addons":250.0,"app_name":"example","data":34.89,"dynos":1.548,"partner":12.34}] |
data | number | total add-on credits used for first party add-ons | 34.89 |
date | date | date of the usage | "2019-01-01" |
dynos | number | dynos used | 1.548 |
id | uuid | team identifier | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | name of the team | "ops" |
partner | number | total add-on credits used for third party add-ons | 12.34 |
space | number | space credits used | 1.548 |
Team Daily Usage Info
Retrieves usage for an enterprise team for a range of days. Start and end dates can be specified as query parameters using the date format YYYY-MM-DD. The team identifier can be found from the team list endpoint.
GET /teams/{team_id}/usage/daily
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
start | string | range start date pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ |
"2019-01-25" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
end | string | range end date pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ |
"2019-02-25" |
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_ID/usage/daily \
-G \
-d start=2019-01-25 \
-d end=2019-02-25 \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addons": 250.0,
"apps": [
{
"addons": 250.0,
"app_name": "example",
"data": 34.89,
"dynos": 1.548,
"partner": 12.34
}
],
"data": 34.89,
"date": "2019-01-01",
"dynos": 1.548,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "ops",
"partner": 12.34,
"space": 1.548
}
]
Team Delinquency
Stability: development
A Heroku team becomes delinquent due to non-payment. We suspend and delete delinquent teams if their invoices remain unpaid.
Attributes
Name | Type | Description | Example |
---|---|---|---|
scheduled_deletion_time | nullable date-time | scheduled time of when we will delete your team due to delinquency | "2024-01-01T12:00:00Z" |
scheduled_suspension_time | nullable date-time | scheduled time of when we will suspend your team due to delinquency | "2024-01-01T12:00:00Z" |
Team Delinquency Info
Team delinquency information.
GET /teams/{team_name_or_id}/delinquency
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/delinquency \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"scheduled_suspension_time": "2024-01-01T12:00:00Z",
"scheduled_deletion_time": "2024-01-01T12:00:00Z"
}
Team Feature
Stability: development
A team feature represents a feature enabled on a team account.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when team feature was created | "2012-01-01T12:00:00Z" |
description | string | description of team feature | "Causes account to example." |
display_name | string | user readable feature name | "My Feature" |
doc_url | string | documentation URL of team feature | "http://devcenter.heroku.com/articles/example" |
enabled | boolean | whether or not team feature has been enabled | true |
feedback_email | string | e-mail to send feedback about the feature | "feedback@heroku.com" |
id | uuid | unique identifier of team feature | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name of team feature | "name" |
state | string | state of team feature | "public" |
updated_at | date-time | when team feature was updated | "2012-01-01T12:00:00Z" |
Team Feature Info
Info for an existing team feature.
GET /teams/{team_name_or_id}/features/{team_feature_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/features/$TEAM_FEATURE_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
Team Feature List
List existing team features.
Acceptable order values for the Range header are id
or name
.
GET /teams/{team_name_or_id}/features
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/features \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
]
Team Invitation
Stability: development
A team invitation represents an invite to a team.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when invitation was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of an invitation | "01234567-89ab-cdef-0123-456789abcdef" |
invited_by:email | unique email address | "username@example.com" |
|
invited_by:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
invited_by:name | nullable string | full name of the account owner | "Tina Edmonds" |
role | nullable string | role in the team one of: "admin" or "collaborator" or "member" or "owner" or null |
"admin" |
team:id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
team:name | string | unique name of team | "example" |
updated_at | date-time | when invitation was updated | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
user:name | nullable string | full name of the account owner | "Tina Edmonds" |
Team Invitation List
Get a list of a team’s Identity Providers
The only acceptable order value for the Range header is id
.
GET /teams/{team_name}/invitations
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME/invitations \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"invited_by": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
]
Team Invitation Create
Create Team Invitation
PUT /teams/{team_name_or_id}/invitations
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
unique email address | "username@example.com" |
||
role | nullable string | role in the team one of: "admin" or "collaborator" or "member" or "owner" or null |
"admin" |
Curl Example
$ curl -n -X PUT https://api.heroku.com/teams/$TEAM_NAME_OR_ID/invitations \
-d '{
"email": "username@example.com",
"role": "admin"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"invited_by": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
Team Invitation Revoke
Revoke a team invitation.
DELETE /teams/{team_name_or_id}/invitations/{team_invitation_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/teams/$TEAM_NAME_OR_ID/invitations/$TEAM_INVITATION_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"invited_by": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
Team Invitation Get
Get an invitation by its token
The only acceptable order value for the Range header is id
.
GET /teams/invitations/{team_invitation_token}
Curl Example
$ curl -n https://api.heroku.com/teams/invitations/$TEAM_INVITATION_TOKEN \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"invited_by": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
Team Invitation Accept
Accept Team Invitation
POST /teams/invitations/{team_invitation_token}/accept
Curl Example
$ curl -n -X POST https://api.heroku.com/teams/invitations/$TEAM_INVITATION_TOKEN/accept \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"email": "someone@example.org",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"role": "admin",
"two_factor_authentication": true,
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
Team Invoice
Stability: development
A Team Invoice is an itemized bill of goods for a team which includes pricing and charges.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addons_total | integer | total add-ons charges in on this invoice | 25000 |
charges_total | integer | total charges on this invoice | 0 |
created_at | date-time | when invoice was created | "2012-01-01T12:00:00Z" |
credits_total | integer | total credits on this invoice | 100000 |
database_total | integer | total database charges on this invoice | 25000 |
dyno_units | number | total amount of dyno units consumed across dyno types. | 1.92 |
id | uuid | unique identifier of this invoice | "01234567-89ab-cdef-0123-456789abcdef" |
number | integer | human readable invoice number | 9403943 |
payment_status | string | status of the invoice payment | "Paid" |
period_end | string | the ending date that the invoice covers | "01/31/2014" |
period_start | string | the starting date that this invoice covers | "01/01/2014" |
platform_total | integer | total platform charges on this invoice | 50000 |
state | integer | payment status for this invoice (pending, successful, failed) | 1 |
total | integer | combined total of charges and credits on this invoice | 100000 |
updated_at | date-time | when invoice was updated | "2012-01-01T12:00:00Z" |
weighted_dyno_hours | number | The total amount of hours consumed across dyno types. | 1488 |
Team Invoice Info
Info for existing invoice.
GET /teams/{team_name_or_id}/invoices/{team_invoice_number}
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/invoices/$TEAM_INVOICE_NUMBER \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addons_total": 25000,
"database_total": 25000,
"charges_total": 0,
"created_at": "2012-01-01T12:00:00Z",
"credits_total": 100000,
"dyno_units": 1.92,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"number": 9403943,
"payment_status": "Paid",
"period_end": "01/31/2014",
"period_start": "01/01/2014",
"platform_total": 50000,
"state": 1,
"total": 100000,
"updated_at": "2012-01-01T12:00:00Z",
"weighted_dyno_hours": 1488
}
Team Invoice List
List existing invoices.
The only acceptable order value for the Range header is number
.
GET /teams/{team_name_or_id}/invoices
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/invoices \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: number
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addons_total": 25000,
"database_total": 25000,
"charges_total": 0,
"created_at": "2012-01-01T12:00:00Z",
"credits_total": 100000,
"dyno_units": 1.92,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"number": 9403943,
"payment_status": "Paid",
"period_end": "01/31/2014",
"period_start": "01/01/2014",
"platform_total": 50000,
"state": 1,
"total": 100000,
"updated_at": "2012-01-01T12:00:00Z",
"weighted_dyno_hours": 1488
}
]
Team Member
Stability: development
A team member is an individual with access to a team.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when the membership record was created | "2012-01-01T12:00:00Z" |
string | email address of the team member | "someone@example.org" |
|
federated | boolean | whether the user is federated and belongs to an Identity Provider | false |
id | uuid | unique identifier of the team member | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider | nullable object | Identity Provider information the member is federated with | null |
identity_provider:id | uuid | unique identifier of this identity provider | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:name | string | name of the identity provider | "acme" |
identity_provider:owner:id | uuid | unique identifier of the owner | "01234567-89ab-cdef-0123-456789abcdef" |
identity_provider:owner:name | string | name of the owner | "acme" |
identity_provider:owner:type | string | type of the owner one of: "team" or "enterprise-account" |
"team" |
identity_provider:redacted | boolean | whether the identity_provider information is redacted or not | false |
role | nullable string | role in the team one of: "admin" or "collaborator" or "member" or "owner" or null |
"admin" |
two_factor_authentication | boolean | whether the team member has two factor authentication enabled | true |
updated_at | date-time | when the membership record was updated | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
user:name | nullable string | full name of the account owner | "Tina Edmonds" |
Team Member Create or Update
Create a new team member, or update their role.
PUT /teams/{team_name_or_id}/members
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
string | email address of the team member | "someone@example.org" |
|
role | string | role in the team one of: "admin" or "viewer" or "member" |
"admin" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
federated | boolean | whether the user is federated and belongs to an Identity Provider | false |
Curl Example
$ curl -n -X PUT https://api.heroku.com/teams/$TEAM_NAME_OR_ID/members \
-d '{
"email": "someone@example.org",
"federated": false,
"role": "admin"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"email": "someone@example.org",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"role": "admin",
"two_factor_authentication": true,
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
Team Member Create
Create a new team member.
POST /teams/{team_name_or_id}/members
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
string | email address of the team member | "someone@example.org" |
|
role | string | role in the team one of: "admin" or "viewer" or "member" |
"admin" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
federated | boolean | whether the user is federated and belongs to an Identity Provider | false |
Curl Example
$ curl -n -X POST https://api.heroku.com/teams/$TEAM_NAME_OR_ID/members \
-d '{
"email": "someone@example.org",
"federated": false,
"role": "admin"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"email": "someone@example.org",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"role": "admin",
"two_factor_authentication": true,
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
Team Member Update
Update a team member.
PATCH /teams/{team_name_or_id}/members
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
string | email address of the team member | "someone@example.org" |
|
role | string | role in the team one of: "admin" or "viewer" or "member" |
"admin" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
federated | boolean | whether the user is federated and belongs to an Identity Provider | false |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/teams/$TEAM_NAME_OR_ID/members \
-d '{
"email": "someone@example.org",
"federated": false,
"role": "admin"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"email": "someone@example.org",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"role": "admin",
"two_factor_authentication": true,
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
Team Member Delete
Remove a member from the team.
DELETE /teams/{team_name_or_id}/members/{team_member_email_or_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/teams/$TEAM_NAME_OR_ID/members/$TEAM_MEMBER_EMAIL_OR_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"email": "someone@example.org",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"role": "admin",
"two_factor_authentication": true,
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
Team Member List
List members of the team.
The only acceptable order value for the Range header is email
.
GET /teams/{team_name_or_id}/members
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/members \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: email
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"email": "someone@example.org",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"redacted": false,
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"role": "admin",
"two_factor_authentication": true,
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Tina Edmonds"
}
}
]
Team Member List By Member
List the apps of a team member.
Acceptable order values for the Range header are email
or id
.
GET /teams/{team_name_or_id}/members/{team_member_email_or_id}/apps
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/members/$TEAM_MEMBER_EMAIL_OR_ID/apps \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: email, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"internal_routing": false,
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-18"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
Team Monthly Usage
Stability: development
Usage for an enterprise team at a monthly resolution.
Attributes
Name | Type | Description | Example |
---|---|---|---|
addons | number | total add-on credits used | 250.0 |
apps | array | app usage in the team | [{"addons":250.0,"app_name":"example","data":34.89,"dynos":1.548,"partner":12.34}] |
connect | number | max connect rows synced | 15000 |
data | number | total add-on credits used for first party add-ons | 34.89 |
dynos | number | dynos used | 1.548 |
id | uuid | team identifier | "01234567-89ab-cdef-0123-456789abcdef" |
month | string | year and month of the usage pattern: ^[0-9]{4}-[0-9]{2}$ |
"2019-01" |
name | string | name of the team | "ops" |
partner | number | total add-on credits used for third party add-ons | 12.34 |
space | number | space credits used | 1.548 |
Team Monthly Usage Info
Retrieves usage for an enterprise team for a range of months. Start and end dates can be specified as query parameters using the date, YYYY-MM. If no end date is specified, one month of usage is returned. The team identifier can be found from the team list endpoint.
GET /teams/{team_id}/usage/monthly
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
start | string | range start date pattern: ^[0-9]{4}-[0-9]{2}$ |
"2019-01" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
end | string | range end date pattern: ^[0-9]{4}-[0-9]{2}$ |
"2019-02" |
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_ID/usage/monthly \
-G \
-d start=2019-01 \
-d end=2019-02 \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addons": 250.0,
"apps": [
{
"addons": 250.0,
"app_name": "example",
"data": 34.89,
"dynos": 1.548,
"partner": 12.34
}
],
"connect": 15000,
"data": 34.89,
"dynos": 1.548,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"month": "2019-01",
"name": "ops",
"partner": 12.34,
"space": 1.548
}
]
Team Preferences
Stability: development
Tracks a Team’s Preferences
Attributes
Name | Type | Description | Example |
---|---|---|---|
addons-controls | nullable boolean | Whether add-on service rules should be applied to add-on installations | true |
default-permission | nullable string | The default permission used when adding new members to the team one of: "admin" or "member" or "viewer" or null |
"member" |
Team Preferences List
Retrieve Team Preferences
GET /teams/{team_preferences_name_or_id}/preferences
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_PREFERENCES_NAME_OR_ID/preferences \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"default-permission": "member",
"addons-controls": true
}
Team Preferences Update
Update Team Preferences
PATCH /teams/{team_preferences_name_or_id}/preferences
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
addons-controls | nullable boolean | Whether add-on service rules should be applied to add-on installations | true |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/teams/$TEAM_PREFERENCES_NAME_OR_ID/preferences \
-d '{
"addons-controls": true
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"default-permission": "member",
"addons-controls": true
}
Team Space
Stability: prototype
A space is an isolated, highly available, secure app execution environment.
Team Space List
List spaces owned by the team
GET /teams/{team_name_or_id}/spaces
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/spaces \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"organization": {
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"shield": true,
"state": "allocated",
"updated_at": "2012-01-01T12:00:00Z",
"cidr": "172.20.20.30/16",
"data_cidr": "10.2.0.0/16"
}
]
Test Case
Stability: prototype
A single test case belonging to a test run
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when test case was created | "2015-01-01T12:00:00Z" |
description | string | description of the test case | "example" |
diagnostic | string | meta information about the test case | "example" |
directive | string | special note about the test case e.g. skipped, todo | "example" |
id | uuid | unique identifier of a test case | "01234567-89ab-cdef-0123-456789abcdef" |
number | integer | the test number | 42 |
passed | boolean | whether the test case was successful | true |
test_node:id | string | unique identifier of a test node | "01234567-89ab-cdef-0123-456789abcdef" |
test_run:id | string | unique identifier of a test run | |
updated_at | date-time | when test case was updated | "2015-01-01T12:00:00Z" |
Test Case List
List test cases
The only acceptable order value for the Range header is id
.
GET /test-runs/{test_run_id}/test-cases
Curl Example
$ curl -n https://api.heroku.com/test-runs/$TEST_RUN_ID/test-cases \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2015-01-01T12:00:00Z",
"updated_at": "2015-01-01T12:00:00Z",
"description": "example",
"diagnostic": "example",
"directive": "example",
"passed": true,
"number": 42,
"test_node": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"test_run": {
"id": null
}
}
]
Test Node
Stability: prototype
A single test node belonging to a test run
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when test node was created | "2015-01-01T12:00:00Z" |
dyno | nullable object | the dyno which belongs to this test node | null |
dyno:attach_url | nullable string | a URL to stream output from for debug runs or null for non-debug runs | "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}" |
dyno:id | string | unique identifier or the name of this process on this dyno | "01234567-89ab-cdef-0123-456789abcdef" or "run.1" |
error_status | nullable string | the status of the test run when the error occured | null |
exit_code | nullable integer | the exit code of the test script | null |
id | string | unique identifier of a test node | "01234567-89ab-cdef-0123-456789abcdef" |
index | integer | The index of the test node | 42 |
message | nullable string | human friendly message indicating reason for an error | null |
output_stream_url | string | the streaming output for the test node | "https://example.com/output.log" |
pipeline:id | string | unique identifier or name of pipeline | "01234567-89ab-cdef-0123-456789abcdef" or "example" |
setup_stream_url | string | the streaming test setup output for the test node | "https://example.com/test-setup.log" |
status | string | current state of the test run one of: "pending" or "cancelled" or "creating" or "building" or "running" or "succeeded" or "failed" or "errored" or "debugging" |
"pending" |
test_run:id | string | unique identifier of a test run | |
updated_at | date-time | when test node was updated | "2015-01-01T12:00:00Z" |
Test Node List
List test nodes
The only acceptable order value for the Range header is id
.
GET /test-runs/{test_run_id}/test-nodes
Curl Example
$ curl -n https://api.heroku.com/test-runs/$TEST_RUN_ID/test-nodes \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2015-01-01T12:00:00Z",
"dyno": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"attach_url": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}"
},
"error_status": "example",
"exit_code": 42,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"index": 42,
"message": "example",
"output_stream_url": "https://example.com/output.log",
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"setup_stream_url": "https://example.com/test-setup.log",
"status": "pending",
"updated_at": "2015-01-01T12:00:00Z",
"test_run": {
"id": null
}
}
]
Test Run
Stability: prototype
An execution or trial of one or more tests
Attributes
Name | Type | Description | Example |
---|---|---|---|
actor_email | the email of the actor triggering the test run | "username@example.com" |
|
app_setup | nullable object | the app setup for the test run | null |
clear_cache | nullable boolean | whether the test was run with an empty cache | null |
commit_branch | string | the branch of the repository that the test run concerns | "example" |
commit_message | string | the message for the commit under test | "example" |
commit_sha | string | the SHA hash of the commit under test | "example" |
created_at | date-time | when test run was created | "2015-01-01T12:00:00Z" |
debug | boolean | whether the test run was started for interactive debugging | true |
dyno | nullable object | the type of dynos used for this test-run | null |
dyno:size | string | dyno size | "standard-1X" |
id | uuid | unique identifier of a test run | "01234567-89ab-cdef-0123-456789abcdef" |
message | nullable string | human friendly message indicating reason for an error | null |
number | integer | the auto incrementing test run number | 42 |
organization | nullable object | the team that owns this test-run | null |
organization:name | string | unique name of team | "example" |
pipeline:id | string | unique identifier or name of pipeline | "01234567-89ab-cdef-0123-456789abcdef" or "example" |
source_blob_url | string | The download location for the source code to be tested | "example" |
status | string | current state of the test run one of: "pending" or "cancelled" or "creating" or "building" or "running" or "succeeded" or "failed" or "errored" or "debugging" |
"pending" |
updated_at | date-time | when test-run was updated | "2015-01-01T12:00:00Z" |
user:allow_tracking | boolean | whether to allow third party web activity tracking default: true |
true |
user:beta | boolean | whether allowed to utilize beta Heroku features | false |
user:country_of_residence | nullable string | country where account owner resides | "United States" |
user:created_at | date-time | when account was created | "2012-01-01T12:00:00Z" |
user:default_organization | nullable object | team selected by default | null |
user:default_organization:id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
user:default_organization:name | string | unique name of team | "example" |
user:default_team | nullable object | team selected by default | null |
user:default_team:id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
user:default_team:name | string | unique name of team | "example" |
user:delinquent_at | nullable date-time | when account became delinquent | "2012-01-01T12:00:00Z" |
user:email | unique email address | "username@example.com" |
|
user:federated | boolean | whether the user is federated and belongs to an Identity Provider | false |
user:id | uuid | identifier of an account | "01234567-89ab-cdef-0123-456789abcdef" |
user:identity_provider | nullable object | Identity Provider details for federated users. | null |
user:identity_provider:id | uuid | unique identifier of this identity provider | "01234567-89ab-cdef-0123-456789abcdef" |
user:identity_provider:name | string | user-friendly unique identifier for this identity provider | "acme-sso" |
user:identity_provider:organization:name | string | unique name of team | "example" |
user:identity_provider:owner:id | uuid | unique identifier of the owner | "01234567-89ab-cdef-0123-456789abcdef" |
user:identity_provider:owner:name | string | name of the owner | "acme" |
user:identity_provider:owner:type | string | type of the owner one of: "team" or "enterprise-account" |
"team" |
user:identity_provider:team:name | string | unique name of team | "example" |
user:last_login | nullable date-time | when account last authorized with Heroku | "2012-01-01T12:00:00Z" |
user:name | nullable string | full name of the account owner | "Tina Edmonds" |
user:sms_number | nullable string | SMS number of account | "+1 ***-***-1234" |
user:suspended_at | nullable date-time | when account was suspended | "2012-01-01T12:00:00Z" |
user:two_factor_authentication | boolean | whether two-factor auth is enabled on the account | false |
user:updated_at | date-time | when account was updated | "2012-01-01T12:00:00Z" |
user:verified | boolean | whether account has been verified with billing information | false |
warning_message | nullable string | human friently warning emitted during the test run | null |
Test Run Create
Create a new test-run.
POST /test-runs
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
commit_branch | string | the branch of the repository that the test run concerns | "example" |
commit_message | string | the message for the commit under test | "example" |
commit_sha | string | the SHA hash of the commit under test | "example" |
pipeline | string | unique identifier or name of pipeline | "01234567-89ab-cdef-0123-456789abcdef" or "example" |
source_blob_url | string | The download location for the source code to be tested | "example" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
debug | boolean | whether the test run was started for interactive debugging | true |
organization | string | unique name or identifier of team | "example" or "01234567-89ab-cdef-0123-456789abcdef" |
Curl Example
$ curl -n -X POST https://api.heroku.com/test-runs \
-d '{
"commit_branch": "example",
"commit_message": "example",
"commit_sha": "example",
"debug": true,
"organization": "01234567-89ab-cdef-0123-456789abcdef",
"pipeline": "01234567-89ab-cdef-0123-456789abcdef",
"source_blob_url": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actor_email": "username@example.com",
"clear_cache": true,
"commit_branch": "example",
"commit_message": "example",
"commit_sha": "example",
"debug": true,
"app_setup": null,
"created_at": "2015-01-01T12:00:00Z",
"dyno": {
"size": "standard-1X"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"message": "example",
"number": 42,
"organization": {
"name": "example"
},
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"source_blob_url": "example",
"updated_at": "2015-01-01T12:00:00Z",
"user": {
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"warning_message": "example"
}
Test Run Info
Info for existing test-run.
GET /test-runs/{test_run_id}
Curl Example
$ curl -n https://api.heroku.com/test-runs/$TEST_RUN_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actor_email": "username@example.com",
"clear_cache": true,
"commit_branch": "example",
"commit_message": "example",
"commit_sha": "example",
"debug": true,
"app_setup": null,
"created_at": "2015-01-01T12:00:00Z",
"dyno": {
"size": "standard-1X"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"message": "example",
"number": 42,
"organization": {
"name": "example"
},
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"source_blob_url": "example",
"updated_at": "2015-01-01T12:00:00Z",
"user": {
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"warning_message": "example"
}
Test Run List
List existing test-runs for a pipeline.
The only acceptable order value for the Range header is id
.
GET /pipelines/{pipeline_id}/test-runs
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/test-runs \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actor_email": "username@example.com",
"clear_cache": true,
"commit_branch": "example",
"commit_message": "example",
"commit_sha": "example",
"debug": true,
"app_setup": null,
"created_at": "2015-01-01T12:00:00Z",
"dyno": {
"size": "standard-1X"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"message": "example",
"number": 42,
"organization": {
"name": "example"
},
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"source_blob_url": "example",
"updated_at": "2015-01-01T12:00:00Z",
"user": {
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"warning_message": "example"
}
]
Test Run Info By Pipeline
Info for existing test-run by Pipeline
GET /pipelines/{pipeline_id}/test-runs/{test_run_number}
Curl Example
$ curl -n https://api.heroku.com/pipelines/$PIPELINE_ID/test-runs/$TEST_RUN_NUMBER \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actor_email": "username@example.com",
"clear_cache": true,
"commit_branch": "example",
"commit_message": "example",
"commit_sha": "example",
"debug": true,
"app_setup": null,
"created_at": "2015-01-01T12:00:00Z",
"dyno": {
"size": "standard-1X"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"message": "example",
"number": 42,
"organization": {
"name": "example"
},
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"source_blob_url": "example",
"updated_at": "2015-01-01T12:00:00Z",
"user": {
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"warning_message": "example"
}
Test Run Update
Update a test-run’s status.
PATCH /test-runs/{test_run_number}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
message | nullable string | human friendly message indicating reason for an error | null |
status | string | current state of the test run one of: "pending" or "cancelled" or "creating" or "building" or "running" or "succeeded" or "failed" or "errored" or "debugging" |
"pending" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/test-runs/$TEST_RUN_NUMBER \
-d '{
"status": "pending",
"message": "example"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actor_email": "username@example.com",
"clear_cache": true,
"commit_branch": "example",
"commit_message": "example",
"commit_sha": "example",
"debug": true,
"app_setup": null,
"created_at": "2015-01-01T12:00:00Z",
"dyno": {
"size": "standard-1X"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"message": "example",
"number": 42,
"organization": {
"name": "example"
},
"pipeline": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"status": "pending",
"source_blob_url": "example",
"updated_at": "2015-01-01T12:00:00Z",
"user": {
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-sso",
"team": {
"name": "example"
},
"organization": {
"name": "example"
},
"owner": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme",
"type": "team"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"country_of_residence": "United States",
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"default_team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
},
"warning_message": "example"
}
User Preferences
Stability: production
Tracks a user’s preferences and message dismissals
Attributes
Name | Type | Description | Example |
---|---|---|---|
default-organization | nullable string | User’s default team | "sushi-inc" |
dismissed-getting-started | nullable boolean | Whether the user has dismissed the getting started banner | true |
dismissed-github-banner | nullable boolean | Whether the user has dismissed the GitHub link banner | true |
dismissed-org-access-controls | nullable boolean | Whether the user has dismissed the Organization Access Controls banner | true |
dismissed-org-wizard-notification | nullable boolean | Whether the user has dismissed the Organization Wizard | true |
dismissed-pipelines-banner | nullable boolean | Whether the user has dismissed the Pipelines banner | true |
dismissed-pipelines-github-banner | nullable boolean | Whether the user has dismissed the GitHub banner on a pipeline overview | true |
dismissed-pipelines-github-banners | nullable array | Which pipeline uuids the user has dismissed the GitHub banner for | ["96c68759-f310-4910-9867-e0b062064098"] |
dismissed-sms-banner | nullable boolean | Whether the user has dismissed the 2FA SMS banner | true |
timezone | nullable string | User’s default timezone | "UTC" |
User Preferences List
Retrieve User Preferences
GET /users/{user_preferences_self}/preferences
Curl Example
$ curl -n https://api.heroku.com/users/$USER_PREFERENCES_SELF/preferences \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"timezone": "UTC",
"default-organization": "sushi-inc",
"dismissed-github-banner": true,
"dismissed-getting-started": true,
"dismissed-org-access-controls": true,
"dismissed-org-wizard-notification": true,
"dismissed-pipelines-banner": true,
"dismissed-pipelines-github-banner": true,
"dismissed-pipelines-github-banners": [
"96c68759-f310-4910-9867-e0b062064098"
],
"dismissed-sms-banner": true
}
User Preferences Update
Update User Preferences
PATCH /users/{user_preferences_self}/preferences
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
default-organization | nullable string | User’s default team | "sushi-inc" |
dismissed-getting-started | nullable boolean | Whether the user has dismissed the getting started banner | true |
dismissed-github-banner | nullable boolean | Whether the user has dismissed the GitHub link banner | true |
dismissed-org-access-controls | nullable boolean | Whether the user has dismissed the Organization Access Controls banner | true |
dismissed-org-wizard-notification | nullable boolean | Whether the user has dismissed the Organization Wizard | true |
dismissed-pipelines-banner | nullable boolean | Whether the user has dismissed the Pipelines banner | true |
dismissed-pipelines-github-banner | nullable boolean | Whether the user has dismissed the GitHub banner on a pipeline overview | true |
dismissed-pipelines-github-banners | nullable array | Which pipeline uuids the user has dismissed the GitHub banner for | ["96c68759-f310-4910-9867-e0b062064098"] |
dismissed-sms-banner | nullable boolean | Whether the user has dismissed the 2FA SMS banner | true |
timezone | nullable string | User’s default timezone | "UTC" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/users/$USER_PREFERENCES_SELF/preferences \
-d '{
"timezone": "UTC",
"default-organization": "sushi-inc",
"dismissed-github-banner": true,
"dismissed-getting-started": true,
"dismissed-org-access-controls": true,
"dismissed-org-wizard-notification": true,
"dismissed-pipelines-banner": true,
"dismissed-pipelines-github-banner": true,
"dismissed-pipelines-github-banners": [
"96c68759-f310-4910-9867-e0b062064098"
],
"dismissed-sms-banner": true
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"timezone": "UTC",
"default-organization": "sushi-inc",
"dismissed-github-banner": true,
"dismissed-getting-started": true,
"dismissed-org-access-controls": true,
"dismissed-org-wizard-notification": true,
"dismissed-pipelines-banner": true,
"dismissed-pipelines-github-banner": true,
"dismissed-pipelines-github-banners": [
"96c68759-f310-4910-9867-e0b062064098"
],
"dismissed-sms-banner": true
}
Private Spaces VPN
Stability: production
VPN provides a way to connect your Private Spaces to your network via VPN.
Attributes
Name | Type | Description | Example |
---|---|---|---|
id | string | VPN ID | "123456789012" |
ike_version | integer | IKE Version | 1 |
name | string | VPN Name | "office" |
public_ip | string | Public IP of VPN customer gateway | "35.161.69.30" |
routable_cidrs | array | Routable CIDRs of VPN | ["172.16.0.0/16"] |
space_cidr_block | string | CIDR Block of the Private Space | "10.0.0.0/16" |
status | string | Status of the VPN one of: "pending" or "provisioning" or "active" or "deprovisioning" or "failed" |
"active" |
status_message | string | Details of the status | "supplied CIDR block already in use" |
tunnels | array | [{"last_status_change":"2016-10-25T22:09:05Z","ip":"52.44.146.197","customer_ip":"52.44.146.197","pre_shared_key":"secret","status":"UP","status_message":"status message"}] |
Private Spaces VPN Create
Create a new VPN connection in a private space.
POST /spaces/{space_id_or_name}/vpn-connections
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | VPN Name | "office" |
public_ip | string | Public IP of VPN customer gateway | "35.161.69.30" |
routable_cidrs | array | Routable CIDRs of VPN | ["172.16.0.0/16"] |
Curl Example
$ curl -n -X POST https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections \
-d '{
"name": "office",
"public_ip": "35.161.69.30",
"routable_cidrs": [
"172.16.0.0/16"
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "123456789012",
"name": "office",
"public_ip": "35.161.69.30",
"routable_cidrs": [
"172.16.0.0/16"
],
"space_cidr_block": "10.0.0.0/16",
"tunnels": [
{
"last_status_change": "2016-10-25T22:09:05Z",
"ip": "52.44.146.197",
"customer_ip": "52.44.146.197",
"pre_shared_key": "secret",
"status": "UP",
"status_message": "status message"
}
],
"ike_version": 1,
"status": "active",
"status_message": "supplied CIDR block already in use"
}
Private Spaces VPN Destroy
Destroy existing VPN Connection
DELETE /spaces/{space_id_or_name}/vpn-connections/{vpn_connection_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections/$VPN_CONNECTION_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
Private Spaces VPN List
List VPN connections for a space.
Acceptable order values for the Range header are id
or name
.
GET /spaces/{space_id_or_name}/vpn-connections
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "123456789012",
"name": "office",
"public_ip": "35.161.69.30",
"routable_cidrs": [
"172.16.0.0/16"
],
"space_cidr_block": "10.0.0.0/16",
"tunnels": [
{
"last_status_change": "2016-10-25T22:09:05Z",
"ip": "52.44.146.197",
"customer_ip": "52.44.146.197",
"pre_shared_key": "secret",
"status": "UP",
"status_message": "status message"
}
],
"ike_version": 1,
"status": "active",
"status_message": "supplied CIDR block already in use"
}
]
Private Spaces VPN Info
Info for an existing vpn-connection.
GET /spaces/{space_id_or_name}/vpn-connections/{vpn_connection_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections/$VPN_CONNECTION_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "123456789012",
"name": "office",
"public_ip": "35.161.69.30",
"routable_cidrs": [
"172.16.0.0/16"
],
"space_cidr_block": "10.0.0.0/16",
"tunnels": [
{
"last_status_change": "2016-10-25T22:09:05Z",
"ip": "52.44.146.197",
"customer_ip": "52.44.146.197",
"pre_shared_key": "secret",
"status": "UP",
"status_message": "status message"
}
],
"ike_version": 1,
"status": "active",
"status_message": "supplied CIDR block already in use"
}
Private Spaces VPN Update
Update a VPN connection in a private space.
PATCH /spaces/{space_id_or_name}/vpn-connections/{vpn_connection_id_or_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
routable_cidrs | array | Routable CIDRs of VPN | ["172.16.0.0/16"] |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/vpn-connections/$VPN_CONNECTION_ID_OR_NAME \
-d '{
"routable_cidrs": [
"172.16.0.0/16"
]
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "123456789012",
"name": "office",
"public_ip": "35.161.69.30",
"routable_cidrs": [
"172.16.0.0/16"
],
"space_cidr_block": "10.0.0.0/16",
"tunnels": [
{
"last_status_change": "2016-10-25T22:09:05Z",
"ip": "52.44.146.197",
"customer_ip": "52.44.146.197",
"pre_shared_key": "secret",
"status": "UP",
"status_message": "status message"
}
],
"ike_version": 1,
"status": "active",
"status_message": "supplied CIDR block already in use"
}