logo

Stacks

Endpoints for managing Cycle stacks.

List Stacks

Requires the stacks-view permission.

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_count" "builds_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 Value: "creators"
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 Stacks.

default

General error response from the platform

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

Create Stack

Requires the stacks-manage capability.

SecuritybearerAuth and hubAuth
Request
Request Body schema: application/json

Parameters for creating a new Stack.

name
required
string

A name for the Stack.

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
object

A map of default variable values used when building this Stack. A variable can be added anywhere in a Stack using the format {{var}} where var would be a key in this map.

required
StackSource (object) or StackSource (object) (StackSource)
Responses
201

Returns a Stack.

default

General error response from the platform

post/v1/stacks
Request samples
application/json
{
  • "name": "string",
  • "identifier": "string",
  • "acl": {
    },
  • "variables": {
    },
  • "source": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Get Stack

Requires the stacks-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
stackId
required
string

The ID of the Stack

Responses
200

Returns a Stack resource.

default

General error response from the platform

get/v1/stacks/{stackId}
Response samples
application/json
{
  • "data": {
    }
}

Update Stack

Requires the stacks-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
stackId
required
string

The ID of the Stack

Request Body schema: application/json

Parameters for updating a Stack.

name
string

A name for the Stack.

object

A map of default variable values used when building this Stack. A variable can be added anywhere in a Stack using the format {{var}} where var would be a key in this map.

StackSource (object) or StackSource (object) (StackSource)
Responses
200

Returns the updated Stack.

default

General error response from the platform

patch/v1/stacks/{stackId}
Request samples
application/json
{
  • "name": "string",
  • "variables": {
    },
  • "source": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Delete Stack

Requires the stacks-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
stackId
required
string

The ID of the Stack

Responses
202

Returns a Job Descriptor.

default

General error response from the platform

delete/v1/stacks/{stackId}
Response samples
application/json
{
  • "data": {
    }
}

Update Stack Access

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

SecuritybearerAuth and hubAuth
Request
path Parameters
stackId
required
string

The ID of the Stack

Request Body schema: application/json

Parameters for updating a Stack.

ACL (object) or null
Responses
200

Returns the updated Stack.

default

General error response from the platform

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

Create Stack Job

Requires the stacks-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
stackId
required
string

The ID of the Stack

Request Body schema: application/json

Parameters for creating a new Stack Job.

action
required
string

The Job to do.

Value: "prune"
Responses
202

Returns a Job Descriptor.

default

General error response from the platform

post/v1/stacks/{stackId}/tasks
Request samples
application/json
{
  • "action": "prune"
}
Response samples
application/json
{
  • "data": {
    }
}

Get Stack Build Log

Requests the log generated during a stack build. The response log includes log entries for the stack build process, but individual image build logs must be fetched from the generated image. When a stack build fails due to an invalid spec, the incorrect spec, with populated variables, will be included in the log.

Requires the stacks-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
stackId
required
string

The ID of the stack.

buildId
required
string

The ID of the stack build.

Responses
200

Returns the stack build's log.

default

General error response from the platform

get/v1/stacks/{stackId}/builds/{buildId}/build-log
Response samples
application/json
{
  • "data": {
    }
}
➔ Next to Stack Builds