Containers

Endpoints related to managing containers, such as starting/stopping/reconfiguring and telemetry.

List Containers

Requires the containers-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: "instances_count" "domains" "ips"
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" "images" "stack_builds" "stacks" "environments"
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 Containers.

default

General error response from the platform

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

Create Container

Requires the containers-deploy capability.

SecuritybearerAuth and hubAuth
Request
Request Body schema: application/json

Parameters for creating a new Container.

name
required
string

A user defined name for the Container.

Identifier (string) or null
environment_id
required
string

An identifier for the Environment this Container will be deployed to.

image_id
required
string

An identifier for the Image used to create this Container.

stateful
required
boolean

A boolean where true represents this Container is stateful.

required
object (Config)

A container configuration.

lock
boolean

When set to true, prevents this Container from being deleted.

Deployment (object) or null
Array of objects (ContainerVolume)
object or null

Custom meta data. Not utilized by Cycle.

Responses
201

Returns a Container.

default

General error response from the platform

post/v1/containers
Request samples
application/json
{
  • "name": "string",
  • "identifier": "string",
  • "environment_id": "string",
  • "image_id": "string",
  • "stateful": true,
  • "config": {
    },
  • "lock": true,
  • "deployment": {
    },
  • "volumes": [
    ],
  • "annotations": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Get Container

Gets a Container.

Requires the containers-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested Container.

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: "instances_count" "domains" "ips"
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" "images" "stack_builds" "stacks" "environments"
Responses
200

Returns a Container.

default

General error response from the platform

get/v1/containers/{containerId}
Response samples
application/json
{
  • "data": {
    },
  • "includes": {
    }
}

Update Container

Updates the specified Container.

Requires the containers-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the Container.

Request Body schema: application/json

Parameters for updating a Container.

name
string

The name for the Container.

identifier
string

The name for the identifier.

deprecate
boolean

Sets whether Container should be deprecated.

lock
boolean

When set to true, prevents this Container from being deleted.

object

User meta data for the Container.

Responses
200

Returns the updated Container.

default

General error response from the platform

patch/v1/containers/{containerId}
Request samples
application/json
{
  • "name": "string",
  • "identifier": "string",
  • "deprecate": true,
  • "lock": true,
  • "annotation": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Delete Container

Requires the containers-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested Container.

Responses
202

Returns a Job Descriptor.

default

General error response from the platform

delete/v1/containers/{containerId}
Response samples
application/json
{
  • "data": {
    }
}

Get Container Summary

Requires the containers-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested container.

Responses
200

Returns an Container summary resource.

default

General error response from the platform

get/v1/containers/{containerId}/summary
Response samples
application/json
{
  • "data": {
    }
}

Create Container Job

Used to perform different actions on a given Container.

Requires the following capabilities based on the task: start: containers-manage stop: containers-manage reconfigure: containers-manage volumes.reconfigure: containers-volumes-manage reimage: containers-manage scale: containers-manage

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested container.

Request Body schema: application/json

Parameters for creating a new container 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/containers/{containerId}/tasks
Request samples
application/json
{
  • "action": "start"
}
Response samples
application/json
{
  • "data": {
    }
}

List Container Servers

Lists all Servers that currently have an Instance of this Container deployed to them.

Requires the containers-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested container.

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 Value: "primary_ip"
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 an array of Server IDs / number of Instances of this Container deployed to them.

default

General error response from the platform

get/v1/containers/{containerId}/servers
Response samples
application/json
{
  • "data": {
    }
}

List Compatible Servers

Gets a list of servers that are compatible with the specified Container and its restrictions (tags, etc).

Requires the containers-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested container.

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: "node" "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: "location" "models" "integrations"
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 Servers.

default

General error response from the platform

get/v1/containers/{containerId}/servers/usable
Response samples
application/json
{
  • "data": [
    ],
  • "includes": {
    }
}

Get Compatible Images

Returns a list of Images that are compatible with the specified Container. Used to quickly find Images that can be used for reimaging the Container.

Requires the containers-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested Container.

query Parameters
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 compatible Images.

default

General error response from the platform

get/v1/containers/{containerId}/compatible-images
Response samples
application/json
{
  • "data": [
    ]
}

Create Instances

Manually create Instances of a Container.

Requires the containers-update capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the Container this Instance is created from.

Request Body schema: application/json
Array
server_id
required
string

The ID of the Server the new Instance(s) should be deployed to.

new_instances
required
integer

The number of new Instances to be created on the given Server.

Responses
202

Returns a Job Descriptor.

default

General error response from the platform

post/v1/containers/{containerId}/instances
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "data": {
    }
}

Delete Container Instance

Requires the containers-update capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested container.

instanceId
required
string

The ID for the container instance.

Responses
202

Returns a Job Descriptor.

default

General error response from the platform

delete/v1/containers/{containerId}/instances/{instanceId}
Response samples
application/json
{
  • "data": {
    }
}

Expire SSH Credentials

Instantly expires any SSH credentials generated for this Instance.

Requires the containers-ssh capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested container.

instanceId
required
string

The ID for the container instance.

Responses
200

Returns the number of tokens removed.

default

General error response from the platform

delete/v1/containers/{containerId}/instances/{instanceId}/ssh
Response samples
application/json
{
  • "data": {
    }
}

Create Function Job

Used to perform different actions on a given Function Container.

Requires the containers-functions-trigger capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the requested container.

Request Body schema: application/json

Parameters for creating a new container function job.

action
required
string

The name of the action to perform.

required
object
Responses
202

Returns a Job Descriptor.

default

General error response from the platform

post/v1/containers/{containerId}/functions/tasks
Request samples
application/json
{
  • "action": "trigger",
  • "contents": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Delete Container Backup

Requires the containers-backups-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
containerId
required
string

The ID of the container.

backupId
required
string

The ID of the container backup.

Responses
202

Returns a Job Descriptor.

default

General error response from the platform

delete/v1/containers/{containerId}/backups/{backupId}
Response samples
application/json
{
  • "data": {
    }
}