[Legacy] Add-on Partner App Info API

Last updated 19 October 2018

This API will be deprecated in favor of a newer version. To learn about the current API, check out Add-on Partner API

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.

The callback_url and heroku_id attributes returned in App Info API endpoints are for compatibility purposes only. We discourage partners from using them. Instead, use the Get App Info endpoint and provider_id attribute.

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.

You can only update config vars that have been declared in your add-on manifest.

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.

Feedback

Log in to submit feedback.