PowerDown API v1 Overview
PowerDown provides a beta API sufficient for minimal remote control of the PowerDown service. The API is a simple RESTful API secured via private tokens generated via the PowerDown App.
While in beta, the API is subject to change based on user feedback. Please wrap the API to minimize the impact of any breaking changes. Over time, this API will be expanded to cover all facets of the PowerDown service.
The PowerDown CLI uses the API and is a good example of its use. See the PowerDown CLI GitHub Repository for details.
The API is available over TLS only. The base URL is:
Where the version will be a sequential number for subsequent API releases. Initially VERSION is 1.
The API supports the "resource" RESTful resource only. The following routes are provided:
POST /resource/find Find matching resources. GET /resource/ID Get resource by ID. POST /resource/ID/ACTION Invoke a resource action.
To be accepted, API requests must include an authentication token in the HTTP Authorization header.
Authentication tokens are generated via the Create Token page in the PowerDown App and are associated with the logged in user creating the token. When an API request is made with the token, actions are performed on behalf of the user with the user's authorized capabilities.
Tokens can have an expiry and multiple tokens can be active at any one time for an account. It is good practice to rotate tokens regularly.
Some routes use a fuzzy search for matching resources based on the supplied search criteria. The "search" field is used to match either:
- the resource long name
- the resource ID
- the resource "Name" tag
The match will be successful only if the search pattern matches exactly and only one entry.
The API supports GET, POST and DELETE methods. GET requests may take query parameters to modify the returned results.
POST requests will have body data with the following properties:
- keys — object hash of key/value pairs
- params — object hash of request parameters
- options — object hash of query options
The keys are used to select matching items and will vary by request. The parameters are the arguments used for actions. The options are used to filter responses.
Standard options are:
- limit — numeric limit of the number of returned items.
- offset — numeric offset into a set of returned items.
- fields — array of properties to return in the results.
- filter — return results with text matching the filter.
Successful responses will have an HTTP status code of 200 with a response payload. The payload will be JSON and have the following top level fields:
- data -- array of objects
- error -- set to true if the request failed
- message -- set to a response message or error message
- severity -- guidance as to the severity of the message for errors