Cycle Platform API (1.0.0)
Download OpenAPI specification:Download
The Cycle Platform API is a REST-based, resource-oriented API designed to be easy to use and understand. Using this API, you are able to fully interact with the Cycle Platform.
All API responses return JSON, including errors. There is also support for cross-origin resource sharing, so this API can be used in a client-side web application as well.
Every API request much have an accompanying API key in the Authorization header. For more informaiton on generating an API key head over to the Portal Docs.
Your API key should never be made publicly available, published to a public repository, or used on a client side web app. If you would like to use the API from a web app, you should create a thin-client service that acts as a passthrough for your API requests.
Every response follows the same structure, known as the root document. The main data structure, known as a resource, is nested under a data field. If you request a collection of resources, the data field will be an array of those resources. If you request a single resource, the data field will be equal to that resource.
If there is an error, the error field will be present, and the data field will be present and null.
The root resource. If fetching a collection, this will be an array of resource objects.
Includes fields - the key will be the name of the included item passed. All values of include fields will be a full resource structure. (i.e. including environments will embed full environment objects by ID)
Meta Fields - the key will be equal to the name of the meta field provided. Values of meta fields will vary based on the resource. These values are injected into the data object(s).
In order to fetch resources that are part of a hub (containers, environments, etc.), you will need to pass an X-Hub-ID header. When fetching collections of resources, this will limit the response to contain only resources from the specified hub. Most requests require this header.
When trying to gather more complete or specific data you can use query parameters to supplement the normal return (metas, includes) and you can also add specificity to the format and the order (sort, filter). It's worth understanding that sort & filter should only be used on collections.
Sort - An array of sort values. To sort descending, put a -n front of the value, i.e. -id.
Include - An array of include values. Included resources will show up under the root document's include field, with the key being the id
of the included resource. In the case of applying an include to a collection of resources, if two resources share the same
include, it will only appear once in the return.
Meta - An array of meta values. Meta values will show up under a resource's meta field. In the case of applying a meta to a
collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to
individual resources, and may appear in the root document. These will be clearly labeled.
Filter - The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for.