Last updated 13 July 2020

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 auth with the add-on id (e.g. heroku-redis) as the username and the password specified in your 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://<username>:<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://<username>:<password>@api.heroku.com/vendor/apps/:provider_id

Where the identifier used can be one of (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-ons 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 contain a hash of vars to set.

PUT https://{username}:{password}@api.heroku.com/vendor/apps/{provider_id}

Curl Example

$ curl -n -X PUT https://$USERNAME:$PASSWORD@api.heroku.com/vendor/apps/$PROVIDER_ID \
-H "Content-Type: application/json" \
-d '{
  "config": {
    "MYADDON_URL": "http://myaddon.com/ABC123"
  }
}'

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

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