heroku-client
Version:
A wrapper for the Heroku v3 API
1,274 lines (1,254 loc) • 71.4 kB
JavaScript
module.exports = {
"description": "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 Heroku toolbelt or dashboard. For details on getting started, see the [quickstart](https://devcenter.heroku.com/articles/platform-api-quickstart).",
"overview": {
"Authentication": [
"HTTP basic authentication must be constructed from email address and [api token](https://devcenter.heroku.com/articles/authentication) as `{email-address}:{api-token}`, base64 encoded and passed as the Authorization header for each request, for example `Authorization: Basic 0123456789ABCDEF=`.",
"API token authentication works well for personal scripts, but is not recommended for third party services. We plan to deliver OAuth later in the beta to provide better granularity and control when providing access to third party services."
],
"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.",
"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:",
"```\nmachine api.heroku.com\n login {your-email}\n password {your-api-token}\n```"
],
"Custom Types": [
{ "Name": "datetime", "JSON Type": "string", "Description": "timestamp in iso8601 format" },
{ "Name": "uuid", "JSON Type": "string", "Description": "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](#statuses) and a JSON body.",
"Error Attributes": [
{ "Name": "id", "Type": "string", "Description": "id of error raised", "Example": "<code>\"rate_limit\"</code>" },
{ "Name": "message", "Type": "string", "Description": "end user message of error raised ", "Example": "<code>\"Your account reached the API limit. Please wait a few minutes before making new requests\"</code>" }
],
"Error Response": "```\nHTTP/1.1 429 Too Many Requests\n```\n```javascript\n{\n \"id\": \"rate_limit\",\n \"message\": \"Your account reached the API rate limit\\nPlease wait a few minutes before making new requests\"\n}\n```",
"Legacy API": "Those utilizing the legacy, v2 API should instead consult [legacy-api-docs.heroku.com](https://legacy-api-docs.heroku.com)",
"Methods": [
{ "Method": "DELETE", "Usage": "used for destroying existing objects" },
{ "Method": "GET", "Usage": "used for retrieving lists and individual objects" },
{ "Method": "HEAD", "Usage": "used for retrieving metadata about existing objects" },
{ "Method": "PATCH", "Usage": "used for updating existing objects" },
{ "Method": "PUT", "Usage": "used for replacing existing objects" },
{ "Method": "POST", "Usage": "used for creating new objects" }
],
"Method Override": "When using a client that does not support all of the [methods](#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 a `Next-Range` header with a value to help identify the sequence of the next range. To retrieve the next range, repeat the request with the `Range` header set to the contents of `Next-Range` from the previous request.",
"The general format of an API `Range` looks like `<attribute> [<start>]..[<end>][; param1=value1, ...]`. Furthermore, the `<start>` value can be prefixed with a closing square bracket (`]`) to indicate that the start of the range should be exclusive, and likewise the `<end>` value can be suffixed with an opening square bracket (`[`) to indicate that the end of the range should be exclusive.",
"The number of values returned in a range can be controlled using a `max` key in the list of `Range` header parameters. 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.",
"Ordering of results is also controlled with the `Range` header. Any list endpoint will respond with an `Accept-Ranges` header that indicates on what attributes its results can be ordered. One of these ranges can then be used while making a request with `Range`. For example, `GET /apps` will respond with `Accept-Ranges: id, name`. To request sorting on `name`, craft a request to the endpoint with the header `Range: name ..`."
],
"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 1200 tokens. Each API call removes one token from the pool. Tokens are added to the account pool at a rate of 1200 per hour, up to a maximum of 1200. 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](#rate-limits) 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": "RateLimit-Remaining", "Description": "allowed requests remaining in current interval" }
],
"Statuses": [
{ "Code": 200, "Culprit": "Both", "Id": "OK", "Message": "request succeeded" },
{ "Code": 201, "Culprit": "Both", "Id": "Created", "Message": "resource created, for example a new app was created or an add-on was provisioned" },
{ "Code": 202, "Culprit": "Both", "Id": "Accepted", "Message": "request accepted, but the processing has not been completed" },
{ "Code": 206, "Culprit": "Both", "Id": "Partial Content", "Message": "request succeeded, but this is only a partial response, see <a href='#ranges'>ranges</a>" },
{ "Code": 400, "Culprit": "Client", "Id": "Bad Request", "Message": "request invalid, validate usage and try again" },
{ "Code": 401, "Culprit": "Client", "Id": "Unauthorized", "Message": "request not authenticated, validate credentials and try again" },
{ "Code": 402, "Culprit": "Client", "Id": "Payment Required", "Message": "request could not be billed, validate billing information and try again" },
{ "Code": 403, "Culprit": "Client", "Id": "Forbidden", "Message": "request not authorized, provided credentials do not provide access to specified resource" },
{ "Code": 404, "Culprit": "Client", "Id": "Not Found", "Message": "request failed, the specified resource does not exist" },
{ "Code": 406, "Culprit": "Client", "Id": "Not Acceptable", "Message": "request failed, set <code>Accept: application/vnd.heroku+json; version=3</code> header and try again" },
{ "Code": 416, "Culprit": "Client", "Id": "Requested Range Not Satisfiable", "Message": "request failed, validate <code>Content-Range</code> header and try again" },
{ "Code": 422, "Culprit": "Client", "Id": "Unprocessable Entity", "Message": "request failed, validate parameters try again" },
{ "Code": 429, "Culprit": "Client", "Id": "Too Many Requests", "Message": "request failed, wait for rate limits to reset and try again, see <a href='#rate-limits'>rate limits</a>" },
{ "Code": 500, "Culprit": "Heroku", "Id": "Internal Server Error", "Message": "error occurred, we are notified, but contact <a href='https://help.heroku.com'>support</a> if the issue persists" },
{ "Code": 503, "Culprit": "Heroku", "Id": "Service Unavailable", "Message": "API is unavailable, check response body or <a href='https://status.heroku.com'>Heroku status</a> for details" }
],
"Versioning": "The beta and release of the api will all occur within version 3. We will provide warning and migration strategies for any backwards incompatible changes we might make during the beta and will commit to no backwards incompatible changes to version 3 after the release.",
"Warnings": "Responses with warnings will have add headers describing the warning.",
"Warning Headers": [
{ "Header": "id", "Description": "id of warning", "Example": "<code>\"stack_deprecated\"</code>" },
{ "Header": "message", "Description": "end user message for warning", "Example": "<code>\"This stack is deprecated.\"</code>" }
]
},
"resources": {
"Account": {
"actions": {
"Info": {
"method": "GET",
"path": "/account",
"statuses": [200]
},
"Update": {
"attributes": {
"optional": [
"allow_tracking",
"email"
]
},
"method": "PATCH",
"path": "/account",
"statuses": [200]
}
},
"attributes": {
"allow_tracking": {
"description": "whether to allow web activity tracking with third-party services like Google Analytics",
"example": true,
"serialized": true,
"type": "boolean"
},
"beta": {
"description": "whether to utilize beta Heroku features",
"example": false,
"serialized": true,
"type": "boolean"
},
"created_at": {
"description": "when account was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"email": {
"description": "email address of account",
"example": "username@example.com",
"serialized": true,
"type": "string"
},
"id": {
"description": "unique identifier of account",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"last_login": {
"description": "when account last authorized with Heroku",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"updated_at": {
"description": "when account was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"verified": {
"description": "whether the account has been verified with billing information",
"example": false,
"serialized": true,
"type": "boolean"
}
},
"description": "An account represents you on Heroku."
},
"Account Feature": {
"actions": {
"List": {
"method": "GET",
"path": "/account/features",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/account/features/{feature_id_or_name}",
"statuses": [200]
},
"Update": {
"attributes": {
"required": [
"enabled"
]
},
"method": "PATCH",
"path": "/account/features/{feature_id_or_name}",
"statuses": [200]
}
},
"attributes": {
"created_at": {
"description": "when account feature was created",
"example": "2012-01-01T12:00:00-00:00",
"serialized": true,
"type": "datetime"
},
"description": {
"description": "description of account feature",
"example": "Causes account to example.",
"serialized": true,
"type": "string"
},
"doc_url": {
"description": "documentation URL of account feature",
"example": "http://devcenter.heroku.com/articles/example",
"serialized": true,
"type": "string"
},
"enabled": {
"description": "whether or not account feature has been enabled",
"example": true,
"serialized": true,
"type": "boolean"
},
"id": {
"description": "unique identifier of account feature",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"name": {
"description": "unique name of account feature",
"example": "example",
"serialized": true,
"type": "string"
},
"updated_at": {
"description": "when account feature was updated",
"example": "2012-01-01T12:00:00-00:00",
"serialized": true,
"type": "datetime"
}
},
"description": "An account feature represents a Heroku labs capability that can be enabled or disabled for an account on Heroku."
},
"Account Password": {
"actions": {
"Update": {
"attributes": {
"required": [
"current_password",
"password"
]
},
"method": "PUT",
"path": "/account/password",
"statuses": [200]
}
},
"attributes": {
"current_password": {
"description": "existing password value",
"example": "0123456789abcdef",
"serialized": false,
"type": "string"
},
"password": {
"description": "new password value",
"example": "abcdef0123456789",
"serialized": false,
"type": "string"
}
}
},
"Add-on": {
"actions": {
"Create": {
"attributes": {
"optional": [
"config",
"plan:id",
"plan:name"
]
},
"method": "POST",
"path": "/apps/{app_id_or_name}/addons",
"statuses": [201]
},
"List": {
"method": "GET",
"path": "/apps/{app_id_or_name}/addons",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/apps/{app_id_or_name}/addons/{addon_id}",
"statuses": [200]
},
"Update": {
"attributes": {
"optional": [
"config",
"plan:id",
"plan:name"
]
},
"method": "PATCH",
"path": "/apps/{app_id_or_name}/addons/{addon_id}",
"statuses": [200]
},
"Delete": {
"method": "DELETE",
"path": "/apps/{app_id_or_name}/addons/{addon_id}",
"statuses": [200]
}
},
"attributes": {
"config": {
"description": "additional add-on service specific configuration",
"example": {},
"serialized": false,
"type": "object"
},
"created_at": {
"description": "when add-on was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"id": {
"description": "unique identifier of this add-on",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"plan:id": {
"description": "unique identifier for plan",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"plan:name": {
"description": "unique name for plan",
"example": "heroku-postgresql:dev",
"serialized": true,
"type": "string"
},
"updated_at": {
"description": "when add-on was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
}
},
"description": "Add-ons represent add-ons that have been provisioned for an app."
},
"Add-on Service": {
"actions": {
"List": {
"method": "GET",
"path": "/addon-services",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/addon-services/{addon_service_id_or_name}",
"statuses": [200]
}
},
"attributes": {
"created_at": {
"description": "when add-on service was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"id": {
"description": "unique identifier of service",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"name": {
"description": "unique name for add-on service",
"example": "heroku-postgresql",
"serialized": true,
"type": "string"
},
"updated_at": {
"description": "when add-on service was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
}
},
"description": "Add-on services represent add-ons that may be provisioned for apps."
},
"App": {
"actions": {
"Create": {
"attributes": {
"optional": [
"name",
"region:id",
"region:name",
"stack"
]
},
"method": "POST",
"path": "/apps",
"statuses": [201]
},
"List": {
"method": "GET",
"path": "/apps",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/apps/{app_id_or_name}",
"statuses": [200]
},
"Update": {
"attributes": {
"optional": [
"maintenance",
"name"
]
},
"method": "PATCH",
"path": "/apps/{app_id_or_name}",
"statuses": [200]
},
"Delete": {
"method": "DELETE",
"path": "/apps/{app_id_or_name}",
"statuses": [200]
}
},
"attributes": {
"archived_at": {
"description": "when app was archived",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"buildpack_provided_description": {
"description": "description from buildpack of app",
"example": "Ruby/Rack",
"serialized": true,
"type": "string"
},
"created_at": {
"description": "when app was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"git_url": {
"description": "git repo URL of app",
"example": "git@heroku.com/example.git",
"serialized": true,
"type": "string"
},
"id": {
"description": "unique identifier of app",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"maintenance": {
"description": "maintenance status of app",
"example": false,
"serialized": true,
"type": "boolean"
},
"name": {
"description": "unique name of app",
"example": "example",
"serialized": true,
"type": "string"
},
"owner:email": {
"description": "email address of app owner",
"example": "username@example.com",
"serialized": true,
"type": "string"
},
"owner:id": {
"description": "unique identifier of app owner",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"region:id": {
"description": "unique identifier of app region",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"region:name": {
"description": "name of app region",
"example": "us",
"serialized": true,
"type": "string"
},
"released_at": {
"description": "when app was last released",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"repo_size": {
"description": "app git repo size in bytes",
"example": 1024,
"serialized": true,
"type": "number"
},
"slug_size": {
"description": "app slug size in bytes",
"example": 512,
"serialized": true,
"type": "number"
},
"stack": {
"description": "stack of app",
"example": "cedar",
"serialized": true,
"type": "string"
},
"updated_at": {
"description": "when app was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"web_url": {
"description": "web URL of app",
"example": "http://example.herokuapp.com",
"serialized": true,
"type": "string"
}
},
"description": "An app represents the program that you would like to deploy and run on Heroku."
},
"App Feature": {
"actions": {
"List": {
"method": "GET",
"path": "/apps/{app_id_or_name}/features",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/apps/{app_id_or_name}/features/{feature_id_or_name}",
"statuses": [200]
},
"Update": {
"attributes": {
"required": [
"enabled"
]
},
"method": "PATCH",
"path": "/apps/{app_id_or_name}/features/{feature_id_or_name}",
"statuses": [200]
}
},
"attributes": {
"created_at": {
"description": "when app feature was created",
"example": "2012-01-01T12:00:00-00:00",
"serialized": true,
"type": "datetime"
},
"description": {
"description": "description of app feature",
"example": "Causes app to example.",
"serialized": true,
"type": "string"
},
"doc_url": {
"description": "documentation URL of app feature",
"example": "http://devcenter.heroku.com/articles/example",
"serialized": true,
"type": "string"
},
"enabled": {
"description": "whether or not app feature has been enabled",
"example": true,
"serialized": true,
"type": "boolean"
},
"id": {
"description": "unique identifier of app feature",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"name": {
"description": "unique name of app feature",
"example": "example",
"serialized": true,
"type": "string"
},
"updated_at": {
"description": "when app feature was updated",
"example": "2012-01-01T12:00:00-00:00",
"serialized": true,
"type": "datetime"
}
},
"description": "An app feature represents a Heroku labs capability that can be enabled or disabled for an app on Heroku."
},
"App Transfer": {
"actions": {
"Create": {
"attributes": {
"optional": [
"app:id",
"app:name",
"recipient:email",
"recipient:id"
]
},
"method": "POST",
"path": "/account/app-transfers",
"statuses": [201]
},
"List": {
"method": "GET",
"path": "/account/app-transfers",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/account/app-transfers/{transfer_id}",
"statuses": [200]
},
"Update": {
"attributes": {
"required": [
"state"
]
},
"method": "PATCH",
"path": "/account/app-transfers/{transfer_id}",
"statuses": [200]
},
"Delete": {
"method": "DELETE",
"path": "/account/app-transfers/{transfer_id}",
"statuses": [200]
}
},
"attributes": {
"created_at": {
"description": "when the transfer was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"app:id": {
"description": "unique identifier of the app being transferred",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "string"
},
"app:name": {
"description": "name of the app being transferred",
"example": "example",
"serialized": true,
"type": "string"
},
"id": {
"description": "unique identifier of this transfer",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"owner:id": {
"description": "unique identifier of the sending user",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "string"
},
"owner:email": {
"description": "email of the sending user",
"example": "username@example.com",
"serialized": true,
"type": "string"
},
"recipient:id": {
"description": "unique identifier of the receiving user",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "string"
},
"recipient:email": {
"description": "email of the receiving user",
"example": "username@example.com",
"serialized": true,
"type": "string"
},
"state": {
"description": "new state of the transfer; accepted/declined/pending",
"example": "pending",
"serialized": true,
"type": "string"
},
"updated_at": {
"description": "when the transfer was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
}
},
"description": "[Transfers](https://devcenter.heroku.com/articles/transferring-apps) allow a user to transfer ownership of their app to another user. Apps being transferred may be free or have paid resources, but if they are paid, the receiving user must have a [verified account](https://devcenter.heroku.com/articles/account-verification)."
},
"Collaborator": {
"actions": {
"Create": {
"attributes": {
"optional": [
"silent",
"user:email",
"user:id"
]
},
"method": "POST",
"path": "/apps/{app_id_or_name}/collaborators",
"statuses": [201]
},
"List": {
"method": "GET",
"path": "/apps/{app_id_or_name}/collaborators",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/apps/{app_id_or_name}/collaborators/{collaborator_id_or_email}",
"statuses": [200]
},
"Delete": {
"method": "DELETE",
"path": "/apps/{app_id_or_name}/collaborators/{collaborator_id_or_email}",
"statuses": [200]
}
},
"attributes": {
"created_at": {
"description": "when collaborator was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"id": {
"description": "unique identifier of this collaborator",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"silent": {
"description": "when true, suppresses the invitation to collaborate e-mail",
"example": false,
"serialized": false,
"type": "boolean"
},
"updated_at": {
"description": "when collaborator was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"user:email": {
"description": "collaborator email address",
"example": "collaborator@example.com",
"serialized": true,
"type": "string"
},
"user:id": {
"description": "unique identifier of the user",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
}
},
"description": "Collaborators are other users who have been given access to an app on Heroku."
},
"Config Var": {
"actions": {
"Info": {
"method": "GET",
"path": "/apps/{app_id_or_name}/config-vars",
"serialization": {
"FOO": "bar",
"BAZ": "qux",
"QUUX": "corge"
},
"statuses": [200]
},
"Update": {
"attributes": {
"FOO": null,
"BAZ": "grault"
},
"method": "PATCH",
"path": "/apps/{app_id_or_name}/config-vars",
"serialization": {
"BAZ": "grault",
"QUUX": "corge"
},
"statuses": [200]
}
},
"attributes": {
"{key}": {
"description": "key/value pair for dyno env",
"example": "{value}",
"serialized": true,
"type": "string"
}
},
"description": "Config Vars allow you to manage the configuration information provided to an app on Heroku."
},
"Domain": {
"actions": {
"Create": {
"attributes": {
"required": [
"hostname"
]
},
"method": "POST",
"path": "/apps/{app_id_or_name}/domains",
"statuses": [201]
},
"List": {
"method": "GET",
"path": "/apps/{app_id_or_name}/domains",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/apps/{app_id_or_name}/domains/{domain_id_or_hostname}",
"statuses": [200]
},
"Delete": {
"method": "DELETE",
"path": "/apps/{app_id_or_name}/domains/{domain_id_or_hostname}",
"statuses": [200]
}
},
"attributes": {
"created_at": {
"description": "when domain was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"hostname": {
"description": "full hostname",
"example": "subdomain.example.com",
"serialized": true,
"type": "string"
},
"id": {
"description": "unique identifier of this domain",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"updated_at": {
"description": "when domain was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
}
},
"description": "Domains define what web routes should be routed to an app on Heroku."
},
"Dyno": {
"actions": {
"Create": {
"attributes": {
"optional": [
"attach",
"size"
],
"required": [
"command"
]
},
"method": "POST",
"path": "/apps/{app_id_or_name}/dynos",
"statuses": [201]
},
"List": {
"method": "GET",
"path": "/apps/{app_id_or_name}/dynos",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/apps/{app_id_or_name}/dynos/{dyno_id_or_name}",
"statuses": [200]
},
"Delete": {
"method": "DELETE",
"path": "/apps/{app_id_or_name}/dynos/{dyno_id_or_name}",
"statuses": [200]
}
},
"attributes": {
"attach": {
"description": "whether to stream output or not",
"example": true,
"serialized": false,
"type": "boolean"
},
"attach_url": {
"description": "a URL to stream output from for attached processes or null for non-attached processes",
"example": "rendezvous://rendezvous.runtime.heroku.com:5000/{rendezvous-id}",
"serialized": true,
"type": "string"
},
"command": {
"description": "command used to start this process",
"example": "bash",
"serialized": true,
"type": "string"
},
"created_at": {
"description": "when domain was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"id": {
"description": "unique identifier of this dyno",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"name": {
"description": "the name of this process on this app",
"example": "run.1",
"serialized": true,
"type": "string"
},
"release:id": {
"description": "the unique identifier of the release this process was started with",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"release:version": {
"description": "the unique version of the release this process was started with",
"example": 456,
"serialized": true,
"type": "number"
},
"size": {
"description": "dyno size (default: 1)",
"example": 1,
"serialized": true,
"type": "number"
},
"state": {
"description": "current status of process (either: crashed, down, idle, starting, or up)",
"example": "up",
"serialized": true,
"type": "string"
},
"type": {
"description": "type of process",
"example": "run",
"serialized": true,
"type": "string"
},
"updated_at": {
"description": "when process last changed state",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
}
},
"description": "Dynos encapsulate running processes of an app on Heroku."
},
"Formation": {
"actions": {
"List": {
"method": "GET",
"path": "/apps/{app_id_or_name}/formation",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/apps/{app_id_or_name}/formation/{formation_id_or_type}",
"statuses": [200]
},
"Update": {
"attributes": {
"optional": [
"quantity",
"size"
]
},
"method": "PATCH",
"path": "/apps/{app_id_or_name}/formation/{formation_id_or_type}",
"statuses": [200]
}
},
"attributes": {
"command": {
"description": "command to use for process type",
"example": "bundle exec rails server -p $PORT",
"serialized": true,
"type": "string"
},
"created_at": {
"description": "when domain was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"id": {
"description": "unique identifier of this process type",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"quantity": {
"description": "number of processes to maintain",
"example": 1,
"serialized": true,
"type": "number"
},
"size": {
"description": "dyno size (default: 1)",
"example": 1,
"serialized": true,
"type": "number"
},
"type": {
"description": "type of process to maintain",
"example": "web",
"serialized": true,
"type": "string"
},
"updated_at": {
"description": "when dyno type was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
}
},
"description": "The formation of processes that should be maintained for your application. Commands and types are defined by the Procfile uploaded with an app."
},
"Key": {
"actions": {
"Create": {
"attributes": {
"required": [
"public_key"
]
},
"method": "POST",
"path": "/account/keys",
"statuses": [201]
},
"List": {
"method": "GET",
"path": "/account/keys",
"statuses": [200]
},
"Info": {
"method": "GET",
"path": "/account/keys/{key_id_or_fingerprint}",
"statuses": [200]
},
"Delete": {
"method": "DELETE",
"path": "/account/keys/{key_id_or_fingerprint}",
"statuses": [200]
}
},
"attributes": {
"created_at": {
"description": "when key was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"email": {
"description": "email address provided in key contents",
"example": "username@example.com",
"serialized": true,
"type": "string"
},
"fingerprint": {
"description": "a unique identifying string based on contents",
"example": "17:63:a4:ba:24:d3:7f:af:17:c8:94:82:7e:80:56:bf",
"serialized": true,
"type": "string"
},
"id": {
"description": "unique identifier of this key",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"public_key": {
"description": "full public_key as uploaded",
"example": "ssh-rsa AAAAB3NzaC1ycVc/../839Uv username@example.com",
"serialized": true,
"type": "string"
},
"updated_at": {
"description": "when key was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
}
},
"description": "Keys represent public SSH keys associated with an account and are used to authorize users as they are performing git operations."
},
"Log Drain": {
"actions": {
"Create": {
"attributes": {
"required": [
"url"
]
},
"method": "POST",
"path": "/apps/{app_id_or_name}/log-drains",
"statuses": [201]
},
"List": {
"method": "GET",
"path": "/apps/{app_id_or_name}/log-drains",
"statuses": [200]
},
"Info": {
"method": "GET",
"path": "/apps/{app_id_or_name}/log-drains/{drain_id_or_url}",
"statuses": [200]
},
"Delete": {
"method": "DELETE",
"path": "/apps/{app_id_or_name}/log-drains/{drain_id_or_url}",
"statuses": [200]
}
},
"attributes": {
"addon:id": {
"description": "unique identifier of the addon that provides the drain",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"created_at": {
"description": "when log drain was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"id": {
"description": "unique identifier of this log drain",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"updated_at": {
"description": "when log session was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"url": {
"description": "url associated with the log drain",
"example": "https://example.com/drain",
"serialized": true,
"type": "string"
}
},
"description": "[Log drains](https://devcenter.heroku.com/articles/logging#syslog-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."
},
"Log Session": {
"actions": {
"Create": {
"attributes": {
"optional": [
"dyno",
"lines",
"source",
"tail"
]
},
"method": "POST",
"path": "/apps/{app_id_or_name}/log-sessions",
"statuses": [201]
}
},
"attributes": {
"created_at": {
"description": "when log connection was created",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
},
"dyno": {
"description": "dyno to limit results to",
"example": "web.1",
"serialized": false,
"type": "string"
},
"id": {
"description": "unique identifier of this log session",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"serialized": true,
"type": "uuid"
},
"lines": {
"description": "number of log lines to stream at once",
"example": 10,
"serialized": false,
"type": "number"
},
"logplex_url": {
"description": "URL for log streaming session",
"example": "https://logplex.heroku.com/sessions/01234567-89ab-cdef-0123-456789abcdef?srv=1325419200",
"serialized": true,
"type": "string"
},
"source": {
"description": "log source to limit results to",
"example": "app",
"serialized": false,
"type": "string"
},
"tail": {
"description": "whether to stream ongoing logs",
"example": true,
"serialized": false,
"type": "boolean"
},
"updated_at": {
"description": "when log session was updated",
"example": "2012-01-01T12:00:00Z",
"serialized": true,
"type": "datetime"
}
},
"description": "Log sessions provide a URL to stream data from your app logs. Streaming is performed by doing an HTTP GET method on the provided Logplex URL and then repeatedly reading from the socket. Sessions remain available for about 5 minutes after creation or about one hour after connecting. For continuous access to an app's log, you should set up a [log drain](https://devcenter.heroku.com/articles/logging#syslog-drains)."
},
"OAuth Authorization": {
"actions": {
"Create": {
"attributes": {
"optional": [
"client:id",
"description"
],
"required": [
"scope"
]
},
"method": "POST",
"path": "/oauth/authorizations",
"statuses": [201]
},
"List": {
"method": "GET",
"path": "/oauth/authorizations",
"statuses": [200, 206]
},
"Info": {
"method": "GET",
"path": "/oauth/authorizations/{authorization_id}",