Platform API Reference
Last updated 30 January 2018
Table of Contents
- Overview
- Account
- 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
- App
- App Feature
- Application Formation Set
- App Setup
- App Transfer
- App Webhook
- App Webhook Delivery
- App Webhook Event
- Build
- Build Result
- Buildpack Installations
- Collaborator
- Config Vars
- Credit
- Domain
- Dyno
- Dyno Size
- Filters
- Formation
- Identity Provider
- Inbound Ruleset
- Invoice
- Invoice Address
- Key
- Log Drain
- Log Session
- OAuth Authorization
- OAuth Client
- OAuth Grant
- OAuth Token
- Organization
- Organization Add-on
- Organization App
- Organization App Collaborator
- Organization App Permission
- Organization Feature
- Organization Invitation
- Organization Invoice
- Organization Member
- Organization Preferences
- Outbound Ruleset
- PasswordReset
- Pipeline
- Pipeline Coupling
- Pipeline Promotion
- Pipeline Promotion Target
- Plan
- Rate Limit
- Region
- Release
- Slug
- SMS Number
- SNI Endpoint
- Source
- Space
- Space Access
- Space Network Address Translation
- SSL Endpoint
- Stack
- Team
- Team App
- Team App Collaborator
- Team App Permission
- Team Feature
- Team Invitation
- Team Invoice
- Team Member
- Team Preferences
- User Preferences
- Whitelisted Entity
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"
}
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 |
created_at | date-time | when account was created | "2012-01-01T12:00:00Z" |
default_organization | nullable object | organization selected by default | null |
default_organization:id | uuid | unique identifier of organization | "01234567-89ab-cdef-0123-456789abcdef" |
default_organization:name | string | unique name of organization | "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:organization:name | string | unique name of organization | "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",
"organization": {
"name": "example"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Update
Update account.
PATCH /account
Optional Parameters
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",
"organization": {
"name": "example"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Delete
Delete account. Note that this action cannot be undone.
DELETE /account
Curl Example
$ curl -n -X DELETE https://api.heroku.com/account \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"organization": {
"name": "example"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Info By User
Info for account.
GET /users/{account_email_or_id_or_self}
Curl Example
$ curl -n https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"organization": {
"name": "example"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Update By User
Update account.
PATCH /users/{account_email_or_id_or_self}
Optional Parameters
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",
"organization": {
"name": "example"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Delete By User
Delete account. Note that this action cannot be undone.
DELETE /users/{account_email_or_id_or_self}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"allow_tracking": true,
"beta": false,
"created_at": "2012-01-01T12:00:00Z",
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"identity_provider": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"organization": {
"name": "example"
}
},
"last_login": "2012-01-01T12:00:00Z",
"name": "Tina Edmonds",
"sms_number": "+1 ***-***-1234",
"suspended_at": "2012-01-01T12:00:00Z",
"delinquent_at": "2012-01-01T12:00:00Z",
"two_factor_authentication": false,
"updated_at": "2012-01-01T12:00:00Z",
"verified": false,
"default_organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
}
}
Account Feature
Stability: production
An account feature represents a Heroku labs capability that can be enabled or disabled for an account on Heroku.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when account feature was created | "2012-01-01T12:00:00Z" |
description | string | description of account feature | "Causes account to example." |
display_name | string | user readable feature name | "My Feature" |
doc_url | string | documentation URL of account feature | "http://devcenter.heroku.com/articles/example" |
enabled | boolean | whether or not account feature has been enabled | true |
feedback_email | string | e-mail to send feedback about the feature | "feedback@heroku.com" |
id | uuid | unique identifier of account feature | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name of account feature | "name" |
state | string | state of account feature | "public" |
updated_at | date-time | when account feature was updated | "2012-01-01T12:00:00Z" |
Account Feature Info
Info for an existing account feature.
GET /account/features/{account_feature_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/account/features/$ACCOUNT_FEATURE_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
Account Feature List
List existing account features.
Acceptable order values for the Range header are id
or name
.
GET /account/features
Curl Example
$ curl -n https://api.heroku.com/account/features \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
]
Account Feature Update
Update an existing account feature.
PATCH /account/features/{account_feature_id_or_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
enabled | boolean | whether or not account feature has been enabled | true |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/account/features/$ACCOUNT_FEATURE_ID_OR_NAME \
-d '{
"enabled": true
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"created_at": "2012-01-01T12:00:00Z",
"description": "Causes account to example.",
"doc_url": "http://devcenter.heroku.com/articles/example",
"enabled": true,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "name",
"state": "public",
"updated_at": "2012-01-01T12:00:00Z",
"display_name": "My Feature",
"feedback_email": "feedback@heroku.com"
}
Add-on
Stability: production
Add-ons represent add-ons that have been provisioned and attached to one or more apps.
Attributes
Name | Type | Description | Example |
---|---|---|---|
actions:action | string | identifier of the action to take that is sent via SSO | "example" |
actions:id | uuid | a unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
actions:label | string | the display text shown in Dashboard | "Example" |
actions:requires_owner | boolean | if the action requires the user to own the app | true |
actions:url | string | absolute URL to use instead of an action | "http://example.com?resource_id=:resource_id" |
addon_service:id | uuid | unique identifier of this add-on-service | "01234567-89ab-cdef-0123-456789abcdef" |
addon_service:name | string | unique name of this add-on-service | "heroku-postgresql" |
app:id | uuid | unique identifier of app | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | unique name of app pattern: ^[a-z][a-z0-9-]{2,29}$
|
"example" |
billed_price | nullable object | billed price | null |
billed_price:cents | integer | price in cents per unit of plan | 0 |
billed_price:unit | string | unit of price for plan | "month" |
config_vars | array | config vars exposed to the owning app by this add-on | ["FOO","BAZ"] |
created_at | date-time | when add-on was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of add-on | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | globally unique name of the add-on pattern: ^[a-zA-Z][A-Za-z0-9_-]+$
|
"acme-inc-primary-database" |
plan:id | uuid | unique identifier of this plan | "01234567-89ab-cdef-0123-456789abcdef" |
plan:name | string | unique name of this plan | "heroku-postgresql:dev" |
provider_id | string | id of this add-on with its provider | "abcd1234" |
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"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Info
Info for an existing add-on.
GET /addons/{add_on_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Create
Create a new add-on.
POST /apps/{app_id_or_name}/addons
Required Parameters
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 |
---|---|---|---|
confirm | string | name of owning app for confirmation | "example" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/addons \
-d '{
"attachment": {
"name": "DATABASE_FOLLOWER"
},
"config": {
"db-version": "1.2.3"
},
"confirm": "example",
"plan": "01234567-89ab-cdef-0123-456789abcdef"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Delete
Delete an existing add-on.
DELETE /apps/{app_id_or_name}/addons/{add_on_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADD_ON_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Info By App
Info for an existing add-on.
GET /apps/{app_id_or_name}/addons/{add_on_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADD_ON_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on List By App
List existing add-ons for an app.
Acceptable order values for the Range header are id
or name
.
GET /apps/{app_id_or_name}/addons
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addons \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Update
Change add-on plan. Some add-ons may not support changing plans. In that case, an error will be returned.
PATCH /apps/{app_id_or_name}/addons/{add_on_id_or_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
plan | string | unique identifier or name of this plan |
"01234567-89ab-cdef-0123-456789abcdef" or "heroku-postgresql:dev"
|
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/addons/$ADD_ON_ID_OR_NAME \
-d '{
"plan": "01234567-89ab-cdef-0123-456789abcdef"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on List By User
List all existing add-ons a user has access to
Acceptable order values for the Range header are id
or name
.
GET /users/{account_email_or_id_or_self}/addons
Curl Example
$ curl -n https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF/addons \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on List By Team
List add-ons used across all Team apps
Acceptable order values for the Range header are id
or name
.
GET /teams/{team_name_or_id}/addons
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/addons \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Action
Stability: development
Add-on Actions are lifecycle operations for add-on provisioning and deprovisioning. They allow whitelisted add-on providers to (de)provision add-ons in the background and then report back when (de)provisioning is complete.
Add-on Action Provision
Mark an add-on as provisioned for use.
POST /addons/{add_on_id_or_name}/actions/provision
Curl Example
$ curl -n -X POST https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/actions/provision \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Action Deprovision
Mark an add-on as deprovisioned.
POST /addons/{add_on_id_or_name}/actions/deprovision
Curl Example
$ curl -n -X POST https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/actions/deprovision \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"actions": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"label": "Example",
"action": "example",
"url": "http://example.com?resource_id=:resource_id",
"requires_owner": true
},
"addon_service": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Attachment
Stability: prototype
An add-on attachment represents a connection between an app and an add-on that it has been given access to.
Attributes
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-]{2,29}$
|
"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" |
addon:plan:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
addon:plan:name | string | name of this plan | "heroku-postgresql:dev" |
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-]{2,29}$
|
"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" |
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"
},
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Attachment Delete
Delete an existing add-on attachment.
DELETE /addon-attachments/{add_on_attachment_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/addon-attachments/$ADD_ON_ATTACHMENT_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Attachment Info
Info for existing add-on attachment.
GET /addon-attachments/{add_on_attachment_id}
Curl Example
$ curl -n https://api.heroku.com/addon-attachments/$ADD_ON_ATTACHMENT_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Attachment List
List existing add-on attachments.
The only acceptable order value for the Range header is id
.
GET /addon-attachments
Curl Example
$ curl -n https://api.heroku.com/addon-attachments \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Attachment List by Add-on
List existing add-on attachments for an add-on.
The only acceptable order value for the Range header is id
.
GET /addons/{add_on_id_or_name}/addon-attachments
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/addon-attachments \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Attachment List by App
List existing add-on attachments for an app.
The only acceptable order value for the Range header is id
.
GET /apps/{app_id_or_name}/addon-attachments
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addon-attachments \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Add-on Attachment Info by App
Info for existing add-on attachment for an app.
GET /apps/{app_id_or_name}/addon-attachments/{add_on_attachment_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/addon-attachments/$ADD_ON_ATTACHMENT_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
}
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "DATABASE",
"namespace": "role:analytics",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
Add-on Config
Stability: development
Configuration of an Add-on
Attributes
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 | "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"
}
]
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 | "cedar-14" |
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" |
maintenance | boolean | maintenance status of app | false |
name | string | name of app pattern: ^[a-z][a-z0-9-]{2,29}$
|
"example" |
organization | nullable object | identity of organization | null |
organization:id | uuid | unique identifier of organization | "01234567-89ab-cdef-0123-456789abcdef" |
organization:name | string | unique name of organization | "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]$` |
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 | "cedar-14" |
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 | uri | web URL of app pattern: ^https?://[a-z][a-z0-9-]{3,30}\.herokuapp\.com/$
|
"https://example.herokuapp.com/" |
App Create
Create a new app.
POST /apps
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | name of app pattern: ^[a-z][a-z0-9-]{2,29}$
|
"example" |
region | string | unique identifier or name of region |
"01234567-89ab-cdef-0123-456789abcdef" or "us"
|
stack | string | unique name or identifier of stack |
"cedar-14" 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"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Delete
Delete an existing app.
DELETE /apps/{app_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Info
Info for existing app.
GET /apps/{app_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App List
List existing apps.
Acceptable order values for the Range header are id
, name
or updated_at
.
GET /apps
Curl Example
$ curl -n https://api.heroku.com/apps \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name, updated_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
App List Owned and Collaborated
List owned and collaborated apps (excludes team apps).
Acceptable order values for the Range header are id
, name
or updated_at
.
GET /users/{account_email_or_id_or_self}/apps
Curl Example
$ curl -n https://api.heroku.com/users/$ACCOUNT_EMAIL_OR_ID_OR_SELF/apps \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name, updated_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
App Update
Update an existing app.
PATCH /apps/{app_id_or_name}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
build_stack | string | unique name or identifier of stack |
"cedar-14" or "01234567-89ab-cdef-0123-456789abcdef"
|
maintenance | boolean | maintenance status of app | false |
name | string | name of app pattern: ^[a-z][a-z0-9-]{2,29}$
|
"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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Enable ACM
Enable ACM flag for an app
POST /apps/{app_id_or_name}/acm
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/acm \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Disable ACM
Disable ACM flag for an app
DELETE /apps/{app_id_or_name}/acm
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/acm \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Refresh ACM
Refresh ACM for an app
PATCH /apps/{app_id_or_name}/acm
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/acm \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm": false,
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"maintenance": false,
"name": "example",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"organization": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"team": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa",
"shield": true
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
App Feature
Stability: production
An app feature represents a Heroku labs capability that can be enabled or disabled for an app on Heroku.
Attributes
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"
}
Application Formation Set
Stability: development
App formation set describes the combination of process types with their quantities and sizes as well as application process tier
Attributes
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-]{2,29}$
|
"example" |
description | string | a string representation of the formation set | "web@2:Standard-2X worker@3:Performance-M" |
process_tier | string | application process tier one of: "production" or "free" or "hobby" or "private"
|
"production" |
updated_at | date-time | last time fomation-set was updated | "2012-01-01T12:00:00Z" |
App Setup
Stability: production
An app setup represents an app on Heroku that is setup using an environment, addons, and scripts described in an app.json manifest file.
Attributes
Name | Type | Description | Example |
---|---|---|---|
app:id | uuid | unique identifier | "01234567-89ab-cdef-0123-456789abcdef" |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{2,29}$
|
"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 organization members forbidden from joining this app. | false |
app:name | string | name of app pattern: ^[a-z][a-z0-9-]{2,29}$
|
"example" |
app:organization | string | unique name of organization | "example" |
app:personal | boolean | force creation of the app in the user account even if a default org is set. | false |
app:region | string | name of region | "us" |
app:space | string | unique name of space pattern: `^[a-z0-9](?:[a-z0-9] |
-(?!-))+[a-z0-9]$` |
app:stack | string | unique name | "cedar-14" |
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": "cedar-14"
},
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0"
},
"overrides": {
"buildpacks": [
{
"url": "https://example.com/buildpack.tgz"
}
],
"env": {
"FOO": "bar",
"BAZ": "qux"
}
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T12:00:00Z",
"status": "failed",
"failure_message": "invalid app.json",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"build": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"status": "succeeded",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
},
"manifest_errors": [
"config var FOO is required"
],
"postdeploy": {
"output": "assets precompiled",
"exit_code": 1
},
"resolved_success_url": "https://example.herokuapp.com/welcome"
}
App Setup Info
Get the status of an app setup.
GET /app-setups/{app_setup_id}
Curl Example
$ curl -n https://api.heroku.com/app-setups/$APP_SETUP_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T12:00:00Z",
"status": "failed",
"failure_message": "invalid app.json",
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"build": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"status": "succeeded",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
},
"manifest_errors": [
"config var FOO is required"
],
"postdeploy": {
"output": "assets precompiled",
"exit_code": 1
},
"resolved_success_url": "https://example.herokuapp.com/welcome"
}
App Transfer
Stability: production
An app transfer represents a two party interaction for transferring ownership of an app.
Attributes
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-]{2,29}$
|
"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"
}
]
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/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" |
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" |
stack | string | stack of build | "heroku-16" |
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" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
buildpacks | nullable array | buildpacks executed for this build, in order | null |
buildpacks/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" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/builds \
-d '{
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby"
}
],
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0"
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby"
}
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stack": "heroku-16",
"status": "succeeded",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
}
}
Build Info
Info for existing build.
GET /apps/{app_id_or_name}/builds/{build_id}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/builds/$BUILD_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby"
}
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stack": "heroku-16",
"status": "succeeded",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
}
}
Build List
List existing build.
Acceptable order values for the Range header are id
or started_at
.
GET /apps/{app_id_or_name}/builds
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/builds \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, started_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"buildpacks": [
{
"url": "https://github.com/heroku/heroku-buildpack-ruby"
}
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef",
"source_blob": {
"checksum": "SHA256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://example.com/source.tgz?token=xyz",
"version": "v1.3.0"
},
"release": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"slug": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"stack": "heroku-16",
"status": "succeeded",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com"
}
}
]
Build Delete cache
Destroy a build cache.
DELETE /apps/{app_id_or_name}/build-cache
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/build-cache \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 202 Accepted
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
Build Result
Stability: deprecation
A build result contains the output from a build.
Attributes
Name | Type | Description | Example |
---|---|---|---|
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" |
exit_code | number | status from the build | 0 |
lines | array | A list of all the lines of a build’s output. This has been replaced by the output_stream_url attribute on the build resource. |
[{"line":"-----\u003e Ruby app detected\n","stream":"STDOUT"}] |
Build Result Info
Info for existing result.
GET /apps/{app_id_or_name}/builds/{build_id}/result
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/builds/$BUILD_ID/result \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"build": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"status": "succeeded",
"output_stream_url": "https://build-output.heroku.com/streams/01234567-89ab-cdef-0123-456789abcdef"
},
"exit_code": 0,
"lines": [
{
"line": "-----> Ruby app detected\n",
"stream": "STDOUT"
}
]
}
Buildpack Installations
Stability: production
A buildpack installation represents a buildpack that will be run against an app.
Attributes
Name | Type | Description | Example |
---|---|---|---|
buildpack:name | string | either the shorthand name (heroku official buildpacks) or url (unofficial buildpacks) 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-]{2,29}$
|
"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-]{2,29}$
|
"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" |
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" |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/domains \
-d '{
"hostname": "subdomain.example.com"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm_status": "pending",
"acm_status_reason": "Failing CCA check",
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"cname": "example.herokudns.com",
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"kind": "custom",
"updated_at": "2012-01-01T12:00:00Z",
"status": "pending"
}
Domain Delete
Delete an existing domain
DELETE /apps/{app_id_or_name}/domains/{domain_id_or_hostname}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/domains/$DOMAIN_ID_OR_HOSTNAME \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm_status": "pending",
"acm_status_reason": "Failing CCA check",
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"cname": "example.herokudns.com",
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"kind": "custom",
"updated_at": "2012-01-01T12:00:00Z",
"status": "pending"
}
Domain Info
Info for existing domain.
GET /apps/{app_id_or_name}/domains/{domain_id_or_hostname}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/domains/$DOMAIN_ID_OR_HOSTNAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"acm_status": "pending",
"acm_status_reason": "Failing CCA check",
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"cname": "example.herokudns.com",
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"kind": "custom",
"updated_at": "2012-01-01T12:00:00Z",
"status": "pending"
}
Domain List
List existing domains.
Acceptable order values for the Range header are hostname
or id
.
GET /apps/{app_id_or_name}/domains
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/domains \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: hostname, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"acm_status": "pending",
"acm_status_reason": "Failing CCA check",
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"cname": "example.herokudns.com",
"created_at": "2012-01-01T12:00:00Z",
"hostname": "subdomain.example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"kind": "custom",
"updated_at": "2012-01-01T12:00:00Z",
"status": "pending"
}
]
Dyno
Stability: production
Dynos encapsulate running processes of an app on Heroku. Detailed information about dyno sizes can be found at: https://devcenter.heroku.com/articles/dyno-types.
Attributes
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-]{2,29}$
|
"example" |
attach_url | nullable string | a URL to stream output from for attached processes or null for non-attached processes | "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}" |
command | string | command used to start this process | "bash" |
created_at | date-time | when dyno was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of this dyno | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | the name of this process on this dyno | "run.1" |
release:id | uuid | unique identifier of release | "01234567-89ab-cdef-0123-456789abcdef" |
release:version | integer | unique version assigned to the release | 11 |
size | string | dyno size (default: “standard-1X”) | "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 (default: “standard-1X”) | "standard-1X" |
time_to_live | integer | seconds until dyno expires, after which it will soon be killed | 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 |
dyno_units | integer | unit of consumption for Heroku Enterprise customers | 0 |
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 | "free" |
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,
"dyno_units": 0,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"memory": 0.5,
"name": "free",
"private_space_only": false
}
Dyno Size List
List existing dyno sizes.
Acceptable order values for the Range header are id
or name
.
GET /dyno-sizes
Curl Example
$ curl -n https://api.heroku.com/dyno-sizes \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"compute": 1,
"cost": null,
"dedicated": false,
"dyno_units": 0,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"memory": 0.5,
"name": "free",
"private_space_only": false
}
]
Filters
Stability: development
Filters are special endpoints to allow for API consumers to specify a subset of resources to consume in order to reduce the number of requests that are performed. Each filter endpoint endpoint is responsible for determining its supported request format. The endpoints are over POST in order to handle large request bodies without hitting request uri query length limitations, but the requests themselves are idempotent and will not have side effects.
Filters Apps
Request an apps list filtered by app id.
Acceptable order values for the Range header are id
, name
or updated_at
.
POST /filters/apps
Curl Example
$ curl -n -X POST https://api.heroku.com/filters/apps \
-d '{
"in": {
"id": [
"01234567-89ab-cdef-0123-456789abcdef"
]
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name, updated_at
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
Formation
Stability: production
The formation of processes that should be maintained for an app. Update the formation to scale processes or change dyno sizes. Available process type names and commands are defined by the process_types
attribute for the slug currently released on an app.
Attributes
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-]{2,29}$
|
"example" |
command | string | command to use to launch this process | "bundle exec rails server -p $PORT" |
created_at | date-time | when process type was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of this process type | "01234567-89ab-cdef-0123-456789abcdef" |
quantity | integer | number of processes to maintain | 1 |
size | string | dyno size (default: “standard-1X”) | "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 (default: “standard-1X”) | "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 an Organization.
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 | organization associated with this identity provider | null |
organization:name | string | unique name of organization | "example" |
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 Organization
Get a list of an organization’s Identity Providers
GET /organizations/{organization_name}/identity-providers
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_NAME/identity-providers \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z"
}
]
Identity Provider Create By Organization
Create an Identity Provider for an organization
POST /organizations/{organization_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/organizations/$ORGANIZATION_NAME/identity-providers \
-d '{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"entity_id": "https://customer-domain.idp.com",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Identity Provider Update By Organization
Update an organization’s Identity Provider
PATCH /organizations/{organization_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/organizations/$ORGANIZATION_NAME/identity-providers/$IDENTITY_PROVIDER_ID \
-d '{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"entity_id": "https://customer-domain.idp.com",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Identity Provider Delete By Organization
Delete an organization’s Identity Provider
DELETE /organizations/{organization_name}/identity-providers/{identity_provider_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/organizations/$ORGANIZATION_NAME/identity-providers/$IDENTITY_PROVIDER_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Identity Provider List By Team
Get a list of a team’s Identity Providers
GET /teams/{team_name_or_id}/identity-providers
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/identity-providers \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z"
}
]
Identity Provider Create By Team
Create an Identity Provider for a team
POST /teams/{team_name_or_id}/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_OR_ID/identity-providers \
-d '{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"entity_id": "https://customer-domain.idp.com",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z"
}
Identity Provider Update By Team
Update a team’s Identity Provider
PATCH /teams/{team_name_or_id}/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_OR_ID/identity-providers/$IDENTITY_PROVIDER_ID \
-d '{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"entity_id": "https://customer-domain.idp.com",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login"
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"certificate": "-----BEGIN CERTIFICATE----- ...",
"created_at": "2012-01-01T12:00:00Z",
"entity_id": "https://customer-domain.idp.com",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"slo_target_url": "https://example.com/idp/logout",
"sso_target_url": "https://example.com/idp/login",
"organization": {
"name": "example"
},
"updated_at": "2012-01-01T12:00:00Z"
}
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"
}
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"}] |
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",
"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",
"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",
"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",
"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"} |
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" |
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"
},
"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"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain Delete
Delete an existing log drain. Log drains added by add-ons can only be removed by removing the add-on.
DELETE /apps/{app_id_or_name}/log-drains/{log_drain_id_or_url_or_token}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL_OR_TOKEN \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain Info
Info for existing log drain.
GET /apps/{app_id_or_name}/log-drains/{log_drain_id_or_url_or_token}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains/$LOG_DRAIN_ID_OR_URL_OR_TOKEN \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
Log Drain List By Add-on
List existing log drains for an add-on.
The only acceptable order value for the Range header is url
.
GET /addons/{add_on_id_or_name}/log-drains
Curl Example
$ curl -n https://api.heroku.com/addons/$ADD_ON_ID_OR_NAME/log-drains \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: url
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
]
Log Drain List
List existing log drains.
The only acceptable order value for the Range header is url
.
GET /apps/{app_id_or_name}/log-drains
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/log-drains \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: url
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"addon": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "singing-swiftly-1242"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "d.01234567-89ab-cdef-0123-456789abcdef",
"updated_at": "2012-01-01T12:00:00Z",
"url": "https://example.com/drain"
}
]
Log Session
Stability: production
A log session is a reference to the http based log stream for an app.
Attributes
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 | "01234567-89ab-cdef-0123-456789abcdef" |
client | nullable object | identifier of the client that obtained this authorization, if any | null |
client:id | uuid | unique identifier of this OAuth client | "01234567-89ab-cdef-0123-456789abcdef" |
client:name | string | OAuth client name | "example" |
client:redirect_uri | string | endpoint for redirection after authorization with OAuth client | "https://example.com/auth/heroku/callback" |
created_at | date-time | when OAuth authorization was created | "2012-01-01T12:00:00Z" |
grant | nullable object | this authorization’s grant | null |
grant:code | string | grant code received from OAuth web application authorization | "01234567-89ab-cdef-0123-456789abcdef" |
grant:expires_in | integer | seconds until OAuth grant expires | 2592000 |
grant:id | uuid | unique identifier of OAuth grant | "01234567-89ab-cdef-0123-456789abcdef" |
id | uuid | unique identifier of OAuth authorization | "01234567-89ab-cdef-0123-456789abcdef" |
refresh_token | nullable object | refresh token for this authorization | null |
refresh_token:expires_in | nullable integer | seconds until OAuth token expires; may be null for tokens with indefinite lifetime |
2592000 |
refresh_token:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
refresh_token:token | string | contents of the token to be used for authorization | "01234567-89ab-cdef-0123-456789abcdef" |
scope | array | The scope of access OAuth authorization allows | ["global"] |
updated_at | date-time | when OAuth authorization was updated | "2012-01-01T12:00:00Z" |
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": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
OAuth Authorization Delete
Delete OAuth authorization.
DELETE /oauth/authorizations/{oauth_authorization_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
OAuth Authorization Info
Info for an OAuth authorization.
GET /oauth/authorizations/{oauth_authorization_id}
Curl Example
$ curl -n https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
OAuth Authorization List
List OAuth authorizations.
The only acceptable order value for the Range header is id
.
GET /oauth/authorizations
Curl Example
$ curl -n https://api.heroku.com/oauth/authorizations \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
]
OAuth Authorization Regenerate
Regenerate OAuth tokens. This endpoint is only available to direct authorizations or privileged OAuth clients.
POST /oauth/authorizations/{oauth_authorization_id}/actions/regenerate-tokens
Curl Example
$ curl -n -X POST https://api.heroku.com/oauth/authorizations/$OAUTH_AUTHORIZATION_ID/actions/regenerate-tokens \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"redirect_uri": "https://example.com/auth/heroku/callback"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"scope": [
"global"
],
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"email": "username@example.com",
"full_name": "Tina Edmonds"
}
}
OAuth Client
Stability: production
OAuth clients are applications that Heroku users can authorize to automate, customize or extend their usage of the platform. For more information please refer to the Heroku OAuth documentation.
Attributes
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
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 | "01234567-89ab-cdef-0123-456789abcdef" |
authorization:id | uuid | unique identifier of OAuth authorization | "01234567-89ab-cdef-0123-456789abcdef" |
client | nullable object | OAuth client secret used to obtain token | null |
client:secret | string | secret used to obtain OAuth authorizations under this client | "01234567-89ab-cdef-0123-456789abcdef" |
created_at | date-time | when OAuth token was created | "2012-01-01T12:00:00Z" |
grant:code | string | grant code received from OAuth web application authorization | "01234567-89ab-cdef-0123-456789abcdef" |
grant:type | string | type of grant requested, one of authorization_code or refresh_token
|
"authorization_code" |
id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
refresh_token:expires_in | nullable integer | seconds until OAuth token expires; may be null for tokens with indefinite lifetime |
2592000 |
refresh_token:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
refresh_token:token | string | contents of the token to be used for authorization | "01234567-89ab-cdef-0123-456789abcdef" |
session:id | uuid | unique identifier of OAuth token | "01234567-89ab-cdef-0123-456789abcdef" |
updated_at | date-time | when OAuth token was updated | "2012-01-01T12:00:00Z" |
user:id | uuid | 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 | "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": "01234567-89ab-cdef-0123-456789abcdef"
}
}' \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"authorization": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"secret": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"type": "authorization_code"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"session": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
OAuth Token Delete
Revoke OAuth access token.
DELETE /oauth/tokens/{oauth_token_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/oauth/tokens/$OAUTH_TOKEN_ID \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"access_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"authorization": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"client": {
"secret": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"grant": {
"code": "01234567-89ab-cdef-0123-456789abcdef",
"type": "authorization_code"
},
"id": "01234567-89ab-cdef-0123-456789abcdef",
"refresh_token": {
"expires_in": 2592000,
"id": "01234567-89ab-cdef-0123-456789abcdef",
"token": "01234567-89ab-cdef-0123-456789abcdef"
},
"session": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Organization
Stability: prototype
Deprecated: Organizations allow you to manage access to a shared group of applications across your development team.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when the organization was created | "2012-01-01T12:00:00Z" |
credit_card_collections | boolean | whether charges incurred by the org are paid by credit card. | true |
default | boolean | whether to use this organization when none is specified | true |
id | uuid | unique identifier of organization | "01234567-89ab-cdef-0123-456789abcdef" |
membership_limit | nullable number | upper limit of members allowed in an organization. | 25 |
name | string | unique name of organization | "example" |
provisioned_licenses | boolean | whether the org is provisioned licenses by salesforce. | true |
role | nullable string | role in the organization one of: "admin" or "collaborator" or "member" or "owner" or null
|
"admin" |
type | string | type of organization. one of: "enterprise" or "team"
|
"team" |
updated_at | date-time | when the organization was updated | "2012-01-01T12:00:00Z" |
Organization List
List organizations in which you are a member.
Acceptable order values for the Range header are id
or name
.
GET /organizations
Curl Example
$ curl -n https://api.heroku.com/organizations \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"created_at": "2012-01-01T12:00:00Z",
"credit_card_collections": true,
"default": true,
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Organization Info
Info for an organization.
GET /organizations/{organization_name_or_id}
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_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,
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
Organization Update
Update organization properties.
PATCH /organizations/{organization_name_or_id}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
default | boolean | whether to use this organization when none is specified | true |
name | string | unique name of organization | "example" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/organizations/$ORGANIZATION_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,
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
Organization Create
Create a new organization.
POST /organizations
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
name | string | unique name of organization | "example" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
address_1 | string | street address line 1 | "40 Hickory Lane" |
address_2 | string | street address line 2 | "Suite 103" |
card_number | string | encrypted card number of payment method | "encrypted-card-number" |
city | string | city | "San Francisco" |
country | string | country | "US" |
cvv | string | card verification value | "123" |
expiration_month | string | expiration month | "11" |
expiration_year | string | expiration year | "2014" |
first_name | string | the first name for payment method | "Jason" |
last_name | string | the last name for payment method | "Walker" |
other | 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/organizations \
-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"
}' \
-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,
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
Organization Delete
Delete an existing organization.
DELETE /organizations/{organization_name_or_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/organizations/$ORGANIZATION_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,
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
Organization Add-on
Stability: production
Deprecated: A list of add-ons the Organization uses across all apps
Organization Add-on List For Organization
List add-ons used across all Organization apps
GET /organizations/{organization_name_or_id}/addons
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_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"
},
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"billed_price": {
"cents": 0,
"unit": "month"
},
"config_vars": [
"FOO",
"BAZ"
],
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "acme-inc-primary-database",
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
"provider_id": "abcd1234",
"state": "provisioned",
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://postgres.heroku.com/databases/01234567-89ab-cdef-0123-456789abcdef"
}
]
Organization App
Stability: prototype
Deprecated: An organization app encapsulates the organization specific functionality of Heroku apps.
Attributes
Name | Type | Description | Example |
---|---|---|---|
archived_at | nullable date-time | when app was archived | "2012-01-01T12:00:00Z" |
build_stack:id | uuid | identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
build_stack:name | string | unique name | "cedar-14" |
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" |
joined | boolean | is the current member a collaborator on this app. | false |
locked | boolean | are other organization members forbidden from joining this app. | false |
maintenance | boolean | maintenance status of app | false |
name | string | name of app pattern: ^[a-z][a-z0-9-]{2,29}$
|
"example" |
organization | nullable object | organization that owns this app | null |
organization:name | string | unique name of organization | "example" |
owner | nullable object | identity of app owner | null |
owner:email | 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]$` |
stack:id | uuid | identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
stack:name | string | unique name | "cedar-14" |
updated_at | date-time | when app was updated | "2012-01-01T12:00:00Z" |
web_url | uri | web URL of app pattern: ^https?://[a-z][a-z0-9-]{3,30}\.herokuapp\.com/$
|
"https://example.herokuapp.com/" |
Organization App Create
Create a new app in the specified organization, in the default organization if unspecified, or in personal account, if default organization is not set.
POST /organizations/apps
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
locked | boolean | are other organization members forbidden from joining this app. | false |
name | string | name of app pattern: ^[a-z][a-z0-9-]{2,29}$
|
"example" |
organization | string | unique name of organization | "example" |
personal | boolean | force creation of the app in the user account even if a default org is set. | false |
region | string | name of region | "us" |
space | string | unique name of space pattern: `^[a-z0-9](?:[a-z0-9] |
-(?!-))+[a-z0-9]$` |
stack | string | unique name | "cedar-14" |
Curl Example
$ curl -n -X POST https://api.heroku.com/organizations/apps \
-d '{
"locked": false,
"name": "example",
"organization": "example",
"personal": false,
"region": "us",
"space": "nasa",
"stack": "cedar-14"
}' \
-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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"organization": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Organization App List For Organization
List organization apps.
The only acceptable order value for the Range header is name
.
GET /organizations/{organization_name_or_id}/apps
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"organization": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
Organization App Info
Info for an organization app.
GET /organizations/apps/{organization_app_name}
Curl Example
$ curl -n https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"archived_at": "2012-01-01T12:00:00Z",
"buildpack_provided_description": "Ruby/Rack",
"build_stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"organization": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Organization App Update Locked
Lock or unlock an organization app.
PATCH /organizations/apps/{organization_app_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
locked | boolean | are other organization members forbidden from joining this app. | false |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME \
-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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"organization": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Organization App Transfer to Account
Transfer an existing organization app to another Heroku account.
PATCH /organizations/apps/{organization_app_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
owner | string | unique 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/organizations/apps/$ORGANIZATION_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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"organization": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Organization App Transfer to Organization
Transfer an existing organization app to another organization.
PATCH /organizations/apps/{organization_app_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
owner | string | unique name of organization | "example" |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME \
-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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"organization": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
Organization App Collaborator
Stability: prototype
Deprecated: An organization collaborator represents an account that has been given access to an organization 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-]{2,29}$
|
"example" |
created_at | date-time | when collaborator was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of collaborator | "01234567-89ab-cdef-0123-456789abcdef" |
role | nullable string | role in the organization 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" |
Organization App Collaborator Create
Create a new collaborator on an organization app. Use this endpoint instead of the /apps/{app_id_or_name}/collaborator
endpoint when you want the collaborator to be granted permissions according to their role in the organization.
POST /organizations/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/organizations/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",
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Organization App Collaborator Delete
Delete an existing collaborator from an organization app.
DELETE /organizations/apps/{organization_app_name}/collaborators/{organization_app_collaborator_email}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME/collaborators/$ORGANIZATION_APP_COLLABORATOR_EMAIL \
-H "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",
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Organization App Collaborator Info
Info for a collaborator on an organization app.
GET /organizations/apps/{organization_app_name}/collaborators/{organization_app_collaborator_email}
Curl Example
$ curl -n https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME/collaborators/$ORGANIZATION_APP_COLLABORATOR_EMAIL \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Organization App Collaborator Update
Update an existing collaborator from an organization app.
PATCH /organizations/apps/{organization_app_name}/collaborators/{organization_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/organizations/apps/$ORGANIZATION_APP_NAME/collaborators/$ORGANIZATION_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",
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
Organization App Collaborator List
List collaborators on an organization app.
The only acceptable order value for the Range header is email
.
GET /organizations/apps/{organization_app_name}/collaborators
Curl Example
$ curl -n https://api.heroku.com/organizations/apps/$ORGANIZATION_APP_NAME/collaborators \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: email
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"name": "example",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"role": "admin",
"updated_at": "2012-01-01T12:00:00Z",
"user": {
"email": "username@example.com",
"federated": false,
"id": "01234567-89ab-cdef-0123-456789abcdef"
}
}
]
Organization App Permission
Stability: prototype
Deprecated: An organization app permission is a behavior that is assigned to a user in an organization 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" |
Organization App Permission List
Lists permissions available to organizations.
The only acceptable order value for the Range header is name
.
GET /organizations/permissions
Curl Example
$ curl -n https://api.heroku.com/organizations/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."
}
]
Organization Feature
Stability: prototype
Deprecated: An organization feature represents a feature enabled on an organization account.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when organization feature was created | "2012-01-01T12:00:00Z" |
description | string | description of organization feature | "Causes account to example." |
display_name | string | user readable feature name | "My Feature" |
doc_url | string | documentation URL of organization feature | "http://devcenter.heroku.com/articles/example" |
enabled | boolean | whether or not organization feature has been enabled | true |
feedback_email | string | e-mail to send feedback about the feature | "feedback@heroku.com" |
id | uuid | unique identifier of organization feature | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name of organization feature | "name" |
state | string | state of organization feature | "public" |
updated_at | date-time | when organization feature was updated | "2012-01-01T12:00:00Z" |
Organization Feature Info
Info for an existing organization feature.
GET /organizations/{organization_name_or_id}/features/{organization_feature_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_NAME_OR_ID/features/$ORGANIZATION_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"
}
Organization Feature List
List existing organization features.
Acceptable order values for the Range header are id
or name
.
GET /organizations/{organization_name_or_id}/features
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_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"
}
]
Organization Feature Update
Update an existing organization feature.
PATCH /organizations/{organization_name_or_id}/features/{organization_feature_id_or_name}
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
enabled | boolean | whether or not organization feature has been enabled | true |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/organizations/$ORGANIZATION_NAME_OR_ID/features/$ORGANIZATION_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"
}
Organization Invitation
Stability: prototype
Deprecated: An organization invitation represents an invite to an organization.
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" |
organization:id | uuid | unique identifier of organization | "01234567-89ab-cdef-0123-456789abcdef" |
organization:name | string | unique name of organization | "example" |
role | nullable string | role in the organization one of: "admin" or "collaborator" or "member" or "owner" or null
|
"admin" |
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" |
Organization Invitation List
Get a list of an organization’s Identity Providers
The only acceptable order value for the Range header is id
.
GET /organizations/{organization_name}/invitations
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_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"
},
"organization": {
"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"
}
}
]
Organization Invitation Create
Create Organization Invitation
PUT /organizations/{organization_name_or_id}/invitations
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
unique email address | "username@example.com" |
||
role | nullable string | role in the organization one of: "admin" or "collaborator" or "member" or "owner" or null
|
"admin" |
Curl Example
$ curl -n -X PUT https://api.heroku.com/organizations/$ORGANIZATION_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"
},
"organization": {
"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"
}
}
Organization Invitation Revoke
Revoke an organization invitation.
DELETE /organizations/{organization_name_or_id}/invitations/{organization_invitation_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/organizations/$ORGANIZATION_NAME_OR_ID/invitations/$ORGANIZATION_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"
},
"organization": {
"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"
}
}
Organization Invitation Get
Get an invitation by its token
The only acceptable order value for the Range header is id
.
GET /organizations/invitations/{organization_invitation_token}
Curl Example
$ curl -n https://api.heroku.com/organizations/invitations/$ORGANIZATION_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"
},
"organization": {
"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"
}
}
Organization Invitation Accept
Accept Organization Invitation
POST /organizations/invitations/{organization_invitation_token}/accept
Curl Example
$ curl -n -X POST https://api.heroku.com/organizations/invitations/$ORGANIZATION_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",
"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"
}
}
Organization Invoice
Stability: prototype
Deprecated: An organization invoice is an itemized bill of goods for an organization 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 | The 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 |
Organization Invoice Info
Info for existing invoice.
GET /organizations/{organization_name_or_id}/invoices/{organization_invoice_number}
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_NAME_OR_ID/invoices/$ORGANIZATION_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
}
Organization Invoice List
List existing invoices.
The only acceptable order value for the Range header is number
.
GET /organizations/{organization_name_or_id}/invoices
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_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
}
]
Organization Member
Stability: prototype
Deprecated: An organization member is an individual with access to an organization.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when the membership record was created | "2012-01-01T12:00:00Z" |
string | email address of the organization member | "someone@example.org" |
|
federated | boolean | whether the user is federated and belongs to an Identity Provider | false |
id | uuid | unique identifier of organization member | "01234567-89ab-cdef-0123-456789abcdef" |
role | nullable string | role in the organization one of: "admin" or "collaborator" or "member" or "owner" or null
|
"admin" |
two_factor_authentication | boolean | whether the Enterprise organization 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" |
Organization Member Create or Update
Create a new organization member, or update their role.
PUT /organizations/{organization_name_or_id}/members
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
string | email address of the organization member | "someone@example.org" |
|
role | nullable string | role in the organization one of: "admin" or "collaborator" or "member" or "owner" or null
|
"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/organizations/$ORGANIZATION_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",
"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"
}
}
Organization Member Create
Create a new organization member.
POST /organizations/{organization_name_or_id}/members
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
string | email address of the organization member | "someone@example.org" |
|
role | nullable string | role in the organization one of: "admin" or "collaborator" or "member" or "owner" or null
|
"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/organizations/$ORGANIZATION_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",
"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"
}
}
Organization Member update
Update an organization member.
PATCH /organizations/{organization_name_or_id}/members
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
string | email address of the organization member | "someone@example.org" |
|
role | nullable string | role in the organization one of: "admin" or "collaborator" or "member" or "owner" or null
|
"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/organizations/$ORGANIZATION_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",
"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"
}
}
Organization Member Delete
Remove a member from the organization.
DELETE /organizations/{organization_name_or_id}/members/{organization_member_email_or_id}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/organizations/$ORGANIZATION_NAME_OR_ID/members/$ORGANIZATION_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",
"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"
}
}
Organization Member List
List members of the organization.
The only acceptable order value for the Range header is email
.
GET /organizations/{organization_name_or_id}/members
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_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",
"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"
}
}
]
Organization Member App List
List the apps of a member.
Acceptable order values for the Range header are email
or id
.
GET /organizations/{organization_name_or_id}/members/{organization_member_email_or_id}/apps
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_NAME_OR_ID/members/$ORGANIZATION_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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"organization": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
Organization Preferences
Stability: prototype
Deprecated: Tracks an organization’s preferences
Attributes
Name | Type | Description | Example |
---|---|---|---|
default-permission | nullable string | The default permission used when adding new members to the organization one of: "admin" or "member" or "viewer" or null
|
"member" |
whitelisting-enabled | nullable boolean | Whether whitelisting rules should be applied to add-on installations | true |
Organization Preferences List
Retrieve Organization Preferences
GET /organizations/{organization_preferences_name_or_id}/preferences
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_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",
"whitelisting-enabled": true
}
Organization Preferences Update
Update Organization Preferences
PATCH /organizations/{organization_preferences_name_or_id}/preferences
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
whitelisting-enabled | nullable boolean | Whether whitelisting rules should be applied to add-on installations | true |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/organizations/$ORGANIZATION_PREFERENCES_NAME_OR_ID/preferences \
-d '{
"whitelisting-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
{
"default-permission": "member",
"whitelisting-enabled": true
}
Outbound Ruleset
Stability: prototype
An outbound-ruleset is a collection of rules that specify what hosts Dynos are allowed to communicate with.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when outbound-ruleset was created | "2012-01-01T12:00:00Z" |
created_by | unique email address | "username@example.com" |
|
id | uuid | unique identifier of an outbound-ruleset | "01234567-89ab-cdef-0123-456789abcdef" |
rules | array | [{"target":"1.1.1.1/1","from_port":80,"to_port":80,"protocol":"tcp"}] |
Outbound Ruleset Current
Current outbound ruleset for a space
GET /spaces/{space_id_or_name}/outbound-ruleset
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/outbound-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",
"created_at": "2012-01-01T12:00:00Z",
"rules": [
{
"target": "1.1.1.1/1",
"from_port": 80,
"to_port": 80,
"protocol": "tcp"
}
],
"created_by": "username@example.com"
}
Outbound Ruleset Info
Info on an existing Outbound Ruleset
GET /spaces/{space_id_or_name}/outbound-rulesets/{outbound_ruleset_id}
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/outbound-rulesets/$OUTBOUND_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",
"created_at": "2012-01-01T12:00:00Z",
"rules": [
{
"target": "1.1.1.1/1",
"from_port": 80,
"to_port": 80,
"protocol": "tcp"
}
],
"created_by": "username@example.com"
}
Outbound Ruleset List
List all Outbound Rulesets for a space
The only acceptable order value for the Range header is id
.
GET /spaces/{space_id_or_name}/outbound-rulesets
Curl Example
$ curl -n https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/outbound-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",
"created_at": "2012-01-01T12:00:00Z",
"rules": [
{
"target": "1.1.1.1/1",
"from_port": 80,
"to_port": 80,
"protocol": "tcp"
}
],
"created_by": "username@example.com"
}
]
Outbound Ruleset Create
Create a new outbound ruleset
PUT /spaces/{space_id_or_name}/outbound-ruleset
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
rules | array | [{"target":"1.1.1.1/1","from_port":80,"to_port":80,"protocol":"tcp"}] |
Curl Example
$ curl -n -X PUT https://api.heroku.com/spaces/$SPACE_ID_OR_NAME/outbound-ruleset \
-d '{
"rules": [
{
"target": "1.1.1.1/1",
"from_port": 80,
"to_port": 80,
"protocol": "tcp"
}
]
}' \
-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",
"rules": [
{
"target": "1.1.1.1/1",
"from_port": 80,
"to_port": 80,
"protocol": "tcp"
}
],
"created_by": "username@example.com"
}
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
Optional 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
Optional 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"
}
}
Pipeline
Stability: prototype
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" |
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"
}' \
-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",
"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",
"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",
"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",
"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",
"updated_at": "2012-01-01T12:00:00Z"
}
]
Pipeline Coupling
Stability: prototype
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
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 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 app 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 Promotion
Stability: prototype
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: prototype
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"
}
]
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: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,
"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,
"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,
"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 | "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-]{2,29}$
|
"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"
}
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 | "cedar-14" |
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": "cedar-14"
},
"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 |
"cedar-14" 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": "cedar-14"
},
"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 |
---|---|---|---|
certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
cname | string | deprecated; refer to GET /apps/:id/domains for valid CNAMEs for this app | "example.herokussl.com" |
created_at | date-time | when endpoint was created | "2012-01-01T12:00:00Z" |
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" |
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----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
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----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
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----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
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----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
]
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----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
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: prototype
A space is an isolated, highly available, secure app execution environments, running in the modern VPC substrate.
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" |
name | string | unique name of space pattern: `^[a-z0-9](?:[a-z0-9] |
-(?!-))+[a-z0-9]$` |
organization:name | string | unique name of organization | "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"
}
]
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"
}
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]$` |
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"
}
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"
}
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]$` |
team | string | unique name of team | "example" |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
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
}' \
-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"
}
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-]{2,29}$
|
"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}
Optional 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"
}
SSL Endpoint
Stability: production
SSL Endpoint is a public address serving custom SSL cert for HTTPS traffic to a Heroku app. Note that an app must have the ssl:endpoint
add-on installed before it can provision an SSL Endpoint using these APIs.
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-]{2,29}$
|
"example" |
certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
cname | string | canonical name record, the address to point a domain at | "example.herokussl.com" |
created_at | date-time | when endpoint was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of this SSL endpoint | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name for SSL endpoint pattern: ^[a-z][a-z0-9-]{2,29}$
|
"example" |
updated_at | date-time | when endpoint was updated | "2012-01-01T12:00:00Z" |
SSL Endpoint Create
Create a new SSL endpoint.
POST /apps/{app_id_or_name}/ssl-endpoints
Required Parameters
Name | Type | Description | Example |
---|---|---|---|
certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
private_key | string | contents of the private key (eg .key file) | "-----BEGIN RSA PRIVATE KEY----- ..." |
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
preprocess | boolean | allow Heroku to modify an uploaded public certificate chain if deemed advantageous by adding missing intermediaries, stripping unnecessary ones, etc. default: true
|
true |
Curl Example
$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints \
-d '{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"preprocess": true,
"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
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
SSL Endpoint Delete
Delete existing SSL endpoint.
DELETE /apps/{app_id_or_name}/ssl-endpoints/{ssl_endpoint_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints/$SSL_ENDPOINT_ID_OR_NAME \
-H "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"
},
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
SSL Endpoint Info
Info for existing SSL endpoint.
GET /apps/{app_id_or_name}/ssl-endpoints/{ssl_endpoint_id_or_name}
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints/$SSL_ENDPOINT_ID_OR_NAME \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
SSL Endpoint List
List existing SSL endpoints.
Acceptable order values for the Range header are id
or name
.
GET /apps/{app_id_or_name}/ssl-endpoints
Curl Example
$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints \
-H "Accept: application/vnd.heroku+json; version=3"
Response Example
HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
]
SSL Endpoint Update
Update an existing SSL endpoint.
PATCH /apps/{app_id_or_name}/ssl-endpoints/{ssl_endpoint_id_or_name}
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
certificate_chain | string | raw contents of the public certificate chain (eg: .crt or .pem file) | "-----BEGIN CERTIFICATE----- ..." |
preprocess | boolean | allow Heroku to modify an uploaded public certificate chain if deemed advantageous by adding missing intermediaries, stripping unnecessary ones, etc. default: true
|
true |
private_key | string | contents of the private key (eg .key file) | "-----BEGIN RSA PRIVATE KEY----- ..." |
rollback | boolean | indicates that a rollback should be performed | false |
Curl Example
$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/ssl-endpoints/$SSL_ENDPOINT_ID_OR_NAME \
-d '{
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"preprocess": true,
"private_key": "-----BEGIN RSA PRIVATE KEY----- ...",
"rollback": 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
{
"app": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example"
},
"certificate_chain": "-----BEGIN CERTIFICATE----- ...",
"cname": "example.herokussl.com",
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "example",
"updated_at": "2012-01-01T12:00:00Z"
}
Stack
Stability: production
Stacks are the different application execution environments available in the Heroku platform.
Attributes
Name | Type | Description | Example |
---|---|---|---|
created_at | date-time | when stack was introduced | "2012-01-01T12:00:00Z" |
id | uuid | identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
name | string | unique name | "cedar-14" |
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
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14",
"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
[
{
"created_at": "2012-01-01T12:00:00Z",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14",
"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 |
id | uuid | unique identifier of team | "01234567-89ab-cdef-0123-456789abcdef" |
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,
"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,
"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,
"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 | string | street address line 2 | "Suite 103" |
card_number | string | encrypted card number of payment method | "encrypted-card-number" |
city | string | city | "San Francisco" |
country | string | country | "US" |
cvv | string | card verification value | "123" |
expiration_month | string | expiration month | "11" |
expiration_year | string | expiration year | "2014" |
first_name | string | the first name for payment method | "Jason" |
last_name | string | the last name for payment method | "Walker" |
other | string | metadata | "Additional information for payment method" |
postal_code | string | postal code | "90210" |
state | string | state | "CA" |
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"
}' \
-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,
"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,
"membership_limit": 25,
"name": "example",
"provisioned_licenses": true,
"role": "admin",
"type": "team",
"updated_at": "2012-01-01T12:00:00Z"
}
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 | "cedar-14" |
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" |
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-]{2,29}$
|
"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]$` |
stack:id | uuid | identifier of stack | "01234567-89ab-cdef-0123-456789abcdef" |
stack:name | string | unique name | "cedar-14" |
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 | uri | web URL of app pattern: ^https?://[a-z][a-z0-9-]{3,30}\.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 |
---|---|---|---|
locked | boolean | are other team members forbidden from joining this app. | false |
name | string | name of app pattern: ^[a-z][a-z0-9-]{2,29}$
|
"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]$` |
stack | string | unique name | "cedar-14" |
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": "cedar-14"
}' \
-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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
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-]{2,29}$
|
"example" |
created_at | date-time | when collaborator was created | "2012-01-01T12:00:00Z" |
id | uuid | unique identifier of collaborator | "01234567-89ab-cdef-0123-456789abcdef" |
role | 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",
"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",
"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",
"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",
"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",
"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 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",
"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" |
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 Enterprise 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 | nullable string | role in the team one of: "admin" or "collaborator" or "member" or "owner" or null
|
"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",
"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 | nullable string | role in the team one of: "admin" or "collaborator" or "member" or "owner" or null
|
"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",
"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 | nullable string | role in the team one of: "admin" or "collaborator" or "member" or "owner" or null
|
"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",
"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",
"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",
"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": "cedar-14"
},
"created_at": "2012-01-01T12:00:00Z",
"git_url": "https://git.heroku.com/example.git",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"joined": false,
"locked": false,
"maintenance": false,
"name": "example",
"team": {
"name": "example"
},
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
"region": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "us"
},
"released_at": "2012-01-01T12:00:00Z",
"repo_size": 0,
"slug_size": 0,
"space": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "nasa"
},
"stack": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "cedar-14"
},
"updated_at": "2012-01-01T12:00:00Z",
"web_url": "https://example.herokuapp.com/"
}
]
Team Preferences
Stability: development
Tracks a Team’s Preferences
Attributes
Name | Type | Description | Example |
---|---|---|---|
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" |
whitelisting-enabled | nullable boolean | Whether whitelisting rules should be applied to add-on installations | true |
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",
"whitelisting-enabled": true
}
Team Preferences Update
Update Team Preferences
PATCH /teams/{team_preferences_name_or_id}/preferences
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
whitelisting-enabled | nullable boolean | Whether whitelisting 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 '{
"whitelisting-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
{
"default-permission": "member",
"whitelisting-enabled": true
}
User Preferences
Stability: production
Tracks a user’s preferences and message dismissals
Attributes
Name | Type | Description | Example |
---|---|---|---|
default-organization | nullable string | User’s default organization | "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 organization | "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
}
Whitelisted Entity
Stability: prototype
Entities that have been whitelisted to be used by an Organization
Attributes
Name | Type | Description | Example |
---|---|---|---|
added_at | date-time | when the add-on service was whitelisted | "2012-01-01T12:00:00Z" |
added_by:email | nullable email | unique email address | "username@example.com" |
added_by:id | nullable uuid | 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 whitelisting entity | "01234567-89ab-cdef-0123-456789abcdef" |
Whitelisted Entity List By Organization
List all whitelisted Add-on Services for an Organization
Acceptable order values for the Range header are id
or name
.
GET /organizations/{organization_name_or_id}/whitelisted-addon-services
Curl Example
$ curl -n https://api.heroku.com/organizations/$ORGANIZATION_NAME_OR_ID/whitelisted-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"
}
]
Whitelisted Entity Create By Organization
Whitelist an Add-on Service
POST /organizations/{organization_name_or_id}/whitelisted-addon-services
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
addon_service | string | name of the Add-on to whitelist | "heroku-postgresql" |
Curl Example
$ curl -n -X POST https://api.heroku.com/organizations/$ORGANIZATION_NAME_OR_ID/whitelisted-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"
}
]
Whitelisted Entity Delete By Organization
Remove a whitelisted entity
DELETE /organizations/{organization_name_or_id}/whitelisted-addon-services/{whitelisted_add_on_service_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/organizations/$ORGANIZATION_NAME_OR_ID/whitelisted-addon-services/$WHITELISTED_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"
}
Whitelisted Entity List By Team
List all whitelisted Add-on Services for a Team
Acceptable order values for the Range header are id
or name
.
GET /teams/{team_name_or_id}/whitelisted-addon-services
Curl Example
$ curl -n https://api.heroku.com/teams/$TEAM_NAME_OR_ID/whitelisted-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"
}
]
Whitelisted Entity Create By Team
Whitelist an Add-on Service
POST /teams/{team_name_or_id}/whitelisted-addon-services
Optional Parameters
Name | Type | Description | Example |
---|---|---|---|
addon_service | string | name of the Add-on to whitelist | "heroku-postgresql" |
Curl Example
$ curl -n -X POST https://api.heroku.com/teams/$TEAM_NAME_OR_ID/whitelisted-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"
}
]
Whitelisted Entity Delete By Team
Remove a whitelisted entity
DELETE /teams/{team_name_or_id}/whitelisted-addon-services/{whitelisted_add_on_service_id_or_name}
Curl Example
$ curl -n -X DELETE https://api.heroku.com/teams/$TEAM_NAME_OR_ID/whitelisted-addon-services/$WHITELISTED_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"
}