Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Get Started
    • Node.js
    • Ruby
    • Java
    • PHP
    • Python
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
  • Documentation

    • Heroku Architecture
    • Deployment
    • Command Line
    • Language Support
    • Monitoring & Metrics
    • Databases & Data Management
    • App Performance
    • Add-ons
    • Collaboration
    • Security
    • Heroku Enterprise
    • Heroku Labs
    • Extending Heroku
    • Accounts & Billing
    • Troubleshooting & Support
Extending Heroku › Platform API

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"
email email unique email address of account "username@example.com"
federated boolean whether the user is federated and belongs to an Identity Provider false
id uuid unique identifier of an account "01234567-89ab-cdef-0123-456789abcdef"
identity_provider nullable object Identity Provider details for federated users. null
identity_provider:id uuid unique identifier of this identity provider "01234567-89ab-cdef-0123-456789abcdef"
identity_provider: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 reached
one of:"notify" or "sync"
"notify"
updated_at date-time when the webhook was updated "2015-01-01T12:00:00Z"
url uri the URL where the webhook’s notification requests are sent

Add-on Webhook Create

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

POST /addons/{add_on_id_or_name}/webhooks

Required Parameters

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

Optional Parameters

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

Curl Example

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

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Add-on Webhook Delete

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

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Add-on Webhook Info

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

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Add-on Webhook List

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

GET /addons/{add_on_id_or_name}/webhooks

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "addon": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "acme-inc-primary-database"
    },
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": [
      "api:release"
    ],
    "level": "notify",
    "updated_at": "2015-01-01T12:00:00Z",
    "url": "example"
  }
]

Add-on Webhook Update

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

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

Optional Parameters

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "addon": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "acme-inc-primary-database"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Add-on Webhook Delivery

Stability: production

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

Add-on Webhook Delivery Info

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

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "created_at": "2015-01-01T12:00:00Z",
  "event": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": "api:release"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "num_attempts": 42,
  "next_attempt_at": "2015-01-01T12:00:00Z",
  "last_attempt": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "code": 42,
    "error_class": "example",
    "status": "scheduled",
    "created_at": "2015-01-01T12:00:00Z",
    "updated_at": "2015-01-01T12:00:00Z"
  },
  "status": "pending",
  "updated_at": "2015-01-01T12:00:00Z",
  "webhook": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "level": "notify"
  }
}

Add-on Webhook Delivery List

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

GET /addons/{add_on_id_or_name}/webhook-deliveries

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "event": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "include": "api:release"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "num_attempts": 42,
    "next_attempt_at": "2015-01-01T12:00:00Z",
    "last_attempt": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "code": 42,
      "error_class": "example",
      "status": "scheduled",
      "created_at": "2015-01-01T12:00:00Z",
      "updated_at": "2015-01-01T12:00:00Z"
    },
    "status": "pending",
    "updated_at": "2015-01-01T12:00:00Z",
    "webhook": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "level": "notify"
    }
  }
]

Add-on Webhook Event

Stability: production

Represents a webhook event that occurred.

Add-on Webhook Event Info

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

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": "api:release",
  "payload": {
    "action": "create",
    "actor": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "data": null,
    "previous_data": null,
    "resource": "release",
    "version": "1"
  },
  "updated_at": "2015-01-01T12:00:00Z"
}

Add-on Webhook Event List

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

GET /addons/{add_on_id_or_name}/webhook-events

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": "api:release",
    "payload": {
      "action": "create",
      "actor": {
        "email": "username@example.com",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      },
      "data": null,
      "previous_data": null,
      "resource": "release",
      "version": "1"
    },
    "updated_at": "2015-01-01T12:00:00Z"
  }
]

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 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 email unique email address of account "username@example.com"
owner:id uuid unique identifier of an account "01234567-89ab-cdef-0123-456789abcdef"
recipient:email email unique email address of account "username@example.com"
recipient:id uuid unique identifier of an account "01234567-89ab-cdef-0123-456789abcdef"
state string the current state of an app transfer
one of:"pending" or "accepted" or "declined"
"pending"
updated_at date-time when app transfer was updated "2012-01-01T12:00:00Z"

App Transfer Create

Create a new app transfer.

POST /account/app-transfers

Required Parameters

Name Type Description Example
app string unique identifier or name of app "01234567-89ab-cdef-0123-456789abcdef" or "example"
recipient string unique email address, identifier of an account or Implicit reference to currently authorized user "username@example.com" or "01234567-89ab-cdef-0123-456789abcdef" or "~"

Optional Parameters

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

Curl Example

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

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "recipient": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "state": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

App Transfer Delete

Delete an existing app transfer

DELETE /account/app-transfers/{app_transfer_id_or_name}

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "recipient": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "state": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

App Transfer Info

Info for existing app transfer.

GET /account/app-transfers/{app_transfer_id_or_name}

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "recipient": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "state": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

App Transfer List

List existing apps transfers.

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

GET /account/app-transfers

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id, name
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "app": {
      "name": "example",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "owner": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "recipient": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "state": "pending",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

App Transfer Update

Update an existing app transfer.

PATCH /account/app-transfers/{app_transfer_id_or_name}

Required Parameters

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "app": {
    "name": "example",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "recipient": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "state": "pending",
  "updated_at": "2012-01-01T12:00:00Z"
}

App Webhook

Stability: production

Represents the details of a webhook subscription

App Webhook Create

Create an app webhook subscription.

POST /apps/{app_id_or_name}/webhooks

Required Parameters

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

Optional Parameters

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

Curl Example

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

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

App Webhook Delete

Removes an app webhook subscription.

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

App Webhook Info

Returns the info for an app webhook subscription.

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

App Webhook List

List all webhook subscriptions for a particular app.

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

GET /apps/{app_id_or_name}/webhooks

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": [
      "api:release"
    ],
    "level": "notify",
    "updated_at": "2015-01-01T12:00:00Z",
    "url": "example"
  }
]

App Webhook Update

Updates the details of an app webhook subscription.

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

Optional Parameters

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

App Webhook Delivery

Stability: production

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

Attributes

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

App Webhook Delivery Info

Returns the info for an existing delivery.

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "created_at": "2015-01-01T12:00:00Z",
  "event": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": "api:release"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "num_attempts": 42,
  "next_attempt_at": "2015-01-01T12:00:00Z",
  "last_attempt": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "code": 42,
    "error_class": "example",
    "status": "scheduled",
    "created_at": "2015-01-01T12:00:00Z",
    "updated_at": "2015-01-01T12:00:00Z"
  },
  "status": "pending",
  "updated_at": "2015-01-01T12:00:00Z",
  "webhook": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "level": "notify"
  }
}

App Webhook Delivery List

Lists existing deliveries for an app.

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

GET /apps/{app_id_or_name}/webhook-deliveries

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "event": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "include": "api:release"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "num_attempts": 42,
    "next_attempt_at": "2015-01-01T12:00:00Z",
    "last_attempt": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "code": 42,
      "error_class": "example",
      "status": "scheduled",
      "created_at": "2015-01-01T12:00:00Z",
      "updated_at": "2015-01-01T12:00:00Z"
    },
    "status": "pending",
    "updated_at": "2015-01-01T12:00:00Z",
    "webhook": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "level": "notify"
    }
  }
]

App Webhook Event

Stability: production

Represents a webhook event that occurred.

Attributes

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

App Webhook Event Info

Returns the info for a specified webhook event.

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

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": "api:release",
  "payload": {
    "action": "create",
    "actor": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "data": null,
    "previous_data": null,
    "resource": "release",
    "version": "1"
  },
  "updated_at": "2015-01-01T12:00:00Z"
}

App Webhook Event List

Lists existing webhook events for an app.

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

GET /apps/{app_id_or_name}/webhook-events

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": "api:release",
    "payload": {
      "action": "create",
      "actor": {
        "email": "username@example.com",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      },
      "data": null,
      "previous_data": null,
      "resource": "release",
      "version": "1"
    },
    "updated_at": "2015-01-01T12:00:00Z"
  }
]

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 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 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 email unique email address "username@example.com"
id uuid unique identifier of an inbound-ruleset "01234567-89ab-cdef-0123-456789abcdef"
rules array [{"action":"allow","source":"1.1.1.1/1"}]

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"
email string deprecated. Please refer to ‘comment’ instead "username@host"
fingerprint string a unique identifying string based on contents "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf"
id uuid unique identifier of this key "01234567-89ab-cdef-0123-456789abcdef"
public_key string full public_key as uploaded "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com"
updated_at date-time when key was updated "2012-01-01T12:00:00Z"

Key Info

Info for existing key.

GET /account/keys/{key_id_or_fingerprint}

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "comment": "username@host",
  "created_at": "2012-01-01T12:00:00Z",
  "email": "username@host",
  "fingerprint": "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "public_key": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com",
  "updated_at": "2012-01-01T12:00:00Z"
}

Key List

List existing keys.

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

GET /account/keys

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: fingerprint, id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "comment": "username@host",
    "created_at": "2012-01-01T12:00:00Z",
    "email": "username@host",
    "fingerprint": "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "public_key": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Log Drain

Stability: production

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

Attributes

Name Type Description Example
addon nullable object add-on that created the drain {"id":"01234567-89ab-cdef-0123-456789abcdef","name":"singing-swiftly-1242"}
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 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 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 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 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 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
email email 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"
email 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 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
email 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
email 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
email 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 email 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 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
email email unique email address "username@example.com"

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "created_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

PasswordReset Complete Reset Password

Complete password reset.

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

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 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 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 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 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 email unique email address "username@example.com"
invited_by:id uuid identifier of an account "01234567-89ab-cdef-0123-456789abcdef"
invited_by:name nullable string full name of the account owner "Tina Edmonds"
role nullable string role in the team
one of:"admin" or "collaborator" or "member" or "owner" or null
"admin"
team:id uuid unique identifier of team "01234567-89ab-cdef-0123-456789abcdef"
team:name string unique name of team "example"
updated_at date-time when invitation was updated "2012-01-01T12:00:00Z"
user:email email unique email address "username@example.com"
user:id uuid identifier of an account "01234567-89ab-cdef-0123-456789abcdef"
user:name nullable string full name of the account owner "Tina Edmonds"

Team Invitation List

Get a list of a team’s Identity Providers

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

GET /teams/{team_name}/invitations

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "created_at": "2012-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "invited_by": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Tina Edmonds"
    },
    "team": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "role": "admin",
    "updated_at": "2012-01-01T12:00:00Z",
    "user": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Tina Edmonds"
    }
  }
]

Team Invitation Create

Create Team Invitation

PUT /teams/{team_name_or_id}/invitations

Required Parameters

Name Type Description Example
email email unique email address "username@example.com"
role nullable string role in the team
one of:"admin" or "collaborator" or "member" or "owner" or null
"admin"

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "invited_by": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  }
}

Team Invitation Revoke

Revoke a team invitation.

DELETE /teams/{team_name_or_id}/invitations/{team_invitation_id}

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "invited_by": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  }
}

Team Invitation Get

Get an invitation by its token

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

GET /teams/invitations/{team_invitation_token}

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "created_at": "2012-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "invited_by": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  },
  "team": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "role": "admin",
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  }
}

Team Invitation Accept

Accept Team Invitation

POST /teams/invitations/{team_invitation_token}/accept

Curl Example

$ curl -n -X POST https://api.heroku.com/teams/invitations/$TEAM_INVITATION_TOKEN/accept \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "created_at": "2012-01-01T12:00:00Z",
  "email": "someone@example.org",
  "federated": false,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "role": "admin",
  "two_factor_authentication": true,
  "updated_at": "2012-01-01T12:00:00Z",
  "user": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Tina Edmonds"
  }
}

Team Invoice

Stability: development

A Team Invoice is an itemized bill of goods for a team which includes pricing and charges.

Attributes

Name Type Description Example
addons_total integer total add-ons charges in on this invoice 25000
charges_total integer total charges on this invoice 0
created_at date-time when invoice was created "2012-01-01T12:00:00Z"
credits_total integer total credits on this invoice 100000
database_total integer total database charges on this invoice 25000
dyno_units number total amount of dyno units consumed across dyno types. 1.92
id uuid unique identifier of this invoice "01234567-89ab-cdef-0123-456789abcdef"
number integer human readable invoice number 9403943
payment_status string status of the invoice payment "Paid"
period_end string the ending date that the invoice covers "01/31/2014"
period_start string the starting date that this invoice covers "01/01/2014"
platform_total integer total platform charges on this invoice 50000
state integer payment status for this invoice (pending, successful, failed) 1
total integer combined total of charges and credits on this invoice 100000
updated_at date-time when invoice was updated "2012-01-01T12:00:00Z"
weighted_dyno_hours number The total amount of hours consumed across dyno types. 1488

Team Invoice Info

Info for existing invoice.

GET /teams/{team_name_or_id}/invoices/{team_invoice_number}

Curl Example

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

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
{
  "addons_total": 25000,
  "database_total": 25000,
  "charges_total": 0,
  "created_at": "2012-01-01T12:00:00Z",
  "credits_total": 100000,
  "dyno_units": 1.92,
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "number": 9403943,
  "payment_status": "Paid",
  "period_end": "01/31/2014",
  "period_start": "01/01/2014",
  "platform_total": 50000,
  "state": 1,
  "total": 100000,
  "updated_at": "2012-01-01T12:00:00Z",
  "weighted_dyno_hours": 1488
}

Team Invoice List

List existing invoices.

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

GET /teams/{team_name_or_id}/invoices

Curl Example

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

Response Example

HTTP/1.1 200 OK
Accept-Ranges: number
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 4500
[
  {
    "addons_total": 25000,
    "database_total": 25000,
    "charges_total": 0,
    "created_at": "2012-01-01T12:00:00Z",
    "credits_total": 100000,
    "dyno_units": 1.92,
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "number": 9403943,
    "payment_status": "Paid",
    "period_end": "01/31/2014",
    "period_start": "01/01/2014",
    "platform_total": 50000,
    "state": 1,
    "total": 100000,
    "updated_at": "2012-01-01T12:00:00Z",
    "weighted_dyno_hours": 1488
  }
]

Team Member

Stability: development

A team member is an individual with access to a team.

Attributes

Name Type Description Example
created_at date-time when the membership record was created "2012-01-01T12:00:00Z"
email string email address of the team member "someone@example.org"
federated boolean whether the user is federated and belongs to an Identity Provider false
id uuid unique identifier of the team member "01234567-89ab-cdef-0123-456789abcdef"
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 email unique email address "username@example.com"
user:id uuid identifier of an account "01234567-89ab-cdef-0123-456789abcdef"
user:name nullable string full name of the account owner "Tina Edmonds"

Team Member Create or Update

Create a new team member, or update their role.

PUT /teams/{team_name_or_id}/members

Required Parameters

Name Type Description Example
email string email address of the team member "someone@example.org"
role 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
email 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
email 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"
}

Keep reading

  • Platform API
  • API Compatibility Policy
  • OAuth
  • Getting Started with the Platform API

Feedback

Log in to submit feedback.

Pipelines Using the Platform APISetting Up Apps Using the Platform API

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
Heroku is acompany

© Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies