logo

Environments

Endpoints related to managing an environment.

List Environments

Requires the environments-view capability.

SecuritybearerAuth and hubAuth
Request
query Parameters
meta
Array of strings

A comma separated list 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.

Items Enum: "containers" "containers_count" "instances_count"
include
Array of strings

A comma separated list 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.

Items Enum: "creators" "stacks"
object

Filter Field

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.

sort
Array of strings

An array of sort values. To sort descending, put a - in front of the value, e.g. -id.

object

In a list return, the data associated with the page number and size returned. 20 results per page, page 2 would be page[size]=20&page[number]=2

Responses
200

Returns a list of Environments.

default

General error response from the platform

get/v1/environments
Response samples
application/json
{
  • "data": [
    ],
  • "includes": {
    }
}

Create Environment

Requires the environments-create capability.

SecuritybearerAuth and hubAuth
Request
Request Body schema: application/json
name
required
string

A user defined name for the Environment.

identifier
string (Identifier)

A human-readable identifier used to refer to a resource, where using the official ID may be inconvenient. The identifier is automatically tokenized from the name/relevant field of the resource if one is not provided. For example, a container named "My Container" will have the identifier of my-container and is automatically created by the platform.

The identifier does not have to be unique.

ACL (object) or null
cluster
required
string

The cluster this Environment is associated with.

required
object

Contains details regarding the Environment.

required
object (EnvironmentFeatures)

An object representing specialized features configured for this environment.

Responses
201

Returns an Environment.

default

General error response from the platform

post/v1/environments
Request samples
application/json
{
  • "name": "string",
  • "identifier": "string",
  • "acl": {
    },
  • "cluster": "string",
  • "about": {
    },
  • "features": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Get Environment Monitoring Tiers

Gets all the available monitoring tiers that can be enabled for an environment.

SecuritybearerAuth and hubAuth
Responses
200

A list of monitoring tiers.

default

General error response from the platform

get/v1/environments/monitoring-tiers
Response samples
application/json
{
  • "data": {
    }
}

Get Environment

Requires the environments-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
environmentId
required
string

The ID of the requested environment.

query Parameters
meta
Array of strings

A comma separated list 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.

Items Enum: "containers" "containers_count" "instances_count"
include
Array of strings

A comma separated list 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.

Items Enum: "creators" "stacks"
Responses
200

Returns an Environment.

default

General error response from the platform

get/v1/environments/{environmentId}
Response samples
application/json
{
  • "data": {
    },
  • "includes": {
    }
}

Update Environment

Updates the specificed Environment.

Requires the environments-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
environmentId
required
string

The ID of the requested Environment.

Request Body schema: application/json

Parameters for updating an Environment.

name
string or null
identifier
string or null
version
string or null
EnvironmentAbout (object) or null
object or null

The level of monitoring to enable for this environment. There is a cost associated with higher levels of monitoring.

Responses
200

Returns an Environment.

default

General error response from the platform

patch/v1/environments/{environmentId}
Request samples
application/json
{
  • "name": "string",
  • "identifier": "string",
  • "version": "string",
  • "about": {
    },
  • "monitoring": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Delete Environment

Requires the environments-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
environmentId
required
string

The ID of the requested Environment.

Responses
202

Returns a Job Descriptor.

default

General error response from the platform

delete/v1/environments/{environmentId}
Response samples
application/json
{
  • "data": {
    }
}

Update Environment Access

Updates the specificed Environment.

Requires the environments-manage capability. If an ACL is present, requires the manage privilege.

SecuritybearerAuth and hubAuth
Request
path Parameters
environmentId
required
string

The ID of the requested Environment.

Request Body schema: application/json

Parameters for updating an Environment.

ACL (object) or null
Responses
200

Returns an Environment.

default

General error response from the platform

patch/v1/environments/{environmentId}/access
Request samples
application/json
{
  • "acl": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Create Environment Job

Create a job for an Environment, such as 'start' or 'stop'.

Requires the environments-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
environmentId
required
string

The ID of the requested Environment.

Request Body schema: application/json

Parameters for creating a new Environment job.

action
required
string

The name of the action to perform.

Responses
202

Returns a Job Descriptor.

default

General error response from the platform

post/v1/environments/{environmentId}/tasks
Request samples
application/json
{
  • "action": "start"
}
Response samples
application/json
{
  • "data": {
    }
}

Get Environment Summary

Gets the summary of an Environment. Contains useful and relevant data/statistics that would otherwise be several separate API calls.

Requires the environments-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
environmentId
required
string

The ID of the requested environment.

Responses
200

Returns an environment summary object.

default

General error response from the platform

get/v1/environments/{environmentId}/summary
Response samples
application/json
{
  • "data": {
    }
}

Export As Stack

Exports an environment as a stack file for reuse.

Requires the environments-manage capability. You must also have management permissions on the target environment ACL.

SecuritybearerAuth and hubAuth
Request
path Parameters
environmentId
required
string

The ID of the target environment.

Request Body schema: application/json
deployment_tags
Array of strings

Defines which deployment containers to include in the stack export. By default, no containers tagged in a deployment are exported. This option includes all containers with the specific, comma separated deployment tags in the final output in addition to the containers that are not part of any deployment.

resolve_origins
boolean
Default: false

When set to true, Cycle will resolve image origins and inline them into the stack, essentially making this stack portable outside the hub it's currently used in. By default, this is set to false, and the export will just reference existing image sources used by this stack in your hub by ID.

Responses
200

Returns a stack spec file.

default

General error response from the platform

post/v1/environments/{environmentId}/export/stack
Request samples
application/json
{
  • "deployment_tags": [
    ],
  • "resolve_origins": false
}
Response samples
application/json
{
  • "data": {
    }
}
➔ Next to Deployments