Last updated October 03, 2022

This is a reference document for the API calls you can use to query information about your add-on installations. In these examples you are issuing the requests and Heroku is providing the response. All calls should use HTTP basic authorization, where the username must be set to the add-on manifest’s id (also known as slug) and the password to the one specified in the add-on manifest.

Get All Apps

Get a list of apps that have installed your add-on. The resource.uuid value corresponds with the uuid field sent during provision requests.

GET https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/apps

Response Example

[
  {
    "callback_url": "https://api.heroku.com/vendor/apps/01234567-89ab-cdef-0123-456789abcdef",
    "heroku_id": "app123@heroku.com",
    "plan": "test",
    "provider_id": "1",
    "resource": {
      "uuid": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "addon-fluffy-6756"
    }
  },
  {
    "callback_url": "https://api.heroku.com/vendor/apps/abcdef12-3456-7890-abcd-ef1234567890",
    "heroku_id": "app456@heroku.com",
    "plan": "premium",
    "provider_id": "3",
    "resource": {
      "uuid": "abcdef12-3456-7890-abcd-ef1234567890",
      "name": "addon-vertical-9873"
    }
  }
]

Result Pagination

Results larger than 4000 will be paginated. Pagination information is passed via the Link HTTP header. Use those URIs to navigate the pagination rather than constructing them in your client code.

Example

Link: <https://api.heroku.com/vendor/apps?offset=100>; rel="prev", <https://api.heroku.com/vendor/apps?offset=1000>; rel="next"

The possible rel values within that header are:

• next: Shows the URL of the immediate next page of results.
• prev: Shows the URL of the immediate previous page of results.

Get App Info

Get details on any of your add-on instances, including the name of the app, plan, and owner email. This is the endpoint that should be used to find the app name for communication with customers (do not use heroku_id as that will not be recognized by customers).

This endpoint will only return a 200 response after provisioning has completed. Trying to access App Info during a provisioning request will return a 404 response. Some fields are dependent on your add-on manifest and may be omitted.

GET https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/apps/<app_identifier>

Where the app_identifier used must be one of the following (in descending order of preference):

• provider_id
• resource.uuid
• heroku_id - note, we advise that you stop using this identifier for future compatibility with shareable add-on features.

Response Example

{
  "id": "app123@heroku.com",
  "callback_url": "https://api.heroku.com/vendor/apps/01234567-89ab-cdef-0123-456789abcdef",
  "config": {
    "MYADDON_URL": "http://myaddon.com/52e82f5d73"
  },
  "domains": [ "www.the-consumer.com", "the-consumer.com" ],
  "log_input_url": "https://token:t.abcdef12-3456-7890-abcd-ef1234567890@1.us.logplex.io/logs"
  "name": "myapp",
  "plan": "test",
  "owner_email": "glenn@heroku.com",
  "owner": {
    "uuid":  "31e71f4d-b0f6-4250-8c1a-f914b99adba2",
    "email": "glenn@heroku.com"
  },
  "region": "amazon-web-services::us-east-1",
  "resource": {
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "addon-fluffy-6756"
  }
}

Update Config Vars

Update config vars that were previously set for an application during provisioning.

The body should be a JSON string consisting on an object with only one config key set to an object of key-value pairs. Each pair must have the config var name as the key and the new value that should be assigned.

PUT https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/apps/<provider_id>

Curl Example

$ curl -n -X PUT https://$MANIFEST_ID:$MANIFEST_PASSWORD@api.heroku.com/vendor/apps/$PROVIDER_ID \
-H "Content-Type: application/json" \
-d '{
  "config": {
    "MYADDON_URL": "https://myaddon.com/ABC123",
    "MYADDON_API_KEY": "0123456789abcdef"
  }
}'

Log Drain Info

Get details on an existing log drain URL set for an application during provisioning.

GET https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/log-drains/<log_drain_token>

Where the log_drain_token is the token sent with the original provision request.

Response Example

{
  "url": "https://example.com/drain"
}

Log Drain Update

Update the log drain URL that was previously set for an application during provisioning.

The body should be a JSON string consisting of an object with only one url key set to the updated Log Drain URL.

PUT https://<manifest_id>:<manifest_password>@api.heroku.com/vendor/log-drains/<log_drain_token>

Curl Example

$ curl -n -X PUT https://$MANIFEST_ID:$MANIFEST_PASSWORD@api.heroku.com/vendor/log-drains/$LOG_DRAIN_TOKEN \
-H "Content-Type: application/json" \
-d '{
  "url": "https://example.com/new-drain"
}‘

Error responses

The following response codes will be returned depending on the underlying cause of the error:

401: An invalid username and password combination has been supplied and you have not been successfully authenticated. This error will also be returned if you try to use any of the Log Drain endpoints and your add-on has not been manually enabled to access them.

404: The requested app doesn’t exist (e.g., it has been deleted) or the add-on has been deprovisioned for this app.

Counting add-on beta users

Before an add-on can progress to the general availability stage, add-on providers are required to have at least 100 unique beta users testing the add-on.

To obtain your beta user count, follow these steps:

1. Get all apps that have your add-on currently installed by using the Get All Apps endpoint and build a list of provider_ids.
2. Using the Get App Info endpoint, once for each provider_id, build a list of app owner emails (attribute owner.email).
3. Remove duplicate app owner emails to get a unique count.

Example implementation

This is an example Bash script using curl and standard *nix tools.

#!/bin/bash

MANIFEST_ID="<manifest_id>"
MANIFEST_PASSWORD="<manifest_password>"

function app_list {
  curl -s -X GET https://${MANIFEST_ID}:${MANIFEST_PASSWORD}@api.heroku.com/vendor/apps
}

function extract_app_provider_id {
  sed -n '/provider_id/! { d; }; /.*"provider_id":"\(.*\)"/ { s//\1/; p; }'
}

function app_info() {
  curl -s -X GET https://${MANIFEST_ID}:${MANIFEST_PASSWORD}@api.heroku.com/vendor/apps/$1
}

function extract_owner_email {
  sed -n '/owner_email/! { d; }; /.*\"owner_email\":"\(.*\)".*/ { s//\1/; p; }'
}

echo "Unique app owners for '${MANIFEST_ID}': $(for i in $(app_list | extract_app_provider_id); do app_info $i | extract_owner_email; done | sort -u | wc -l)"