Managing Stacks

List, view, update, and delete stacks — and understand what happens to the underlying workspaces.

Listing Stacks

GET /stacks

Returns all stacks in the org. Each entry includes:

{
  "id": "stack-uuid",
  "name": "myapp",
  "project_id": "proj-uuid",
  "environment_count": 3,
  "created_at": "2026-01-15T10:00:00Z"
}

Viewing Stack Detail

GET /stacks/{id}

Returns the stack with environment status:

{
  "id": "stack-uuid",
  "name": "myapp",
  "project_id": "proj-uuid",
  "environment_count": 3,
  "created_at": "2026-01-15T10:00:00Z",
  "environments": [
    {
      "workspace_name": "myapp-dev",
      "environment_order": 0,
      "auto_promote": true,
      "latest_run_status": "completed"
    },
    {
      "workspace_name": "myapp-staging",
      "environment_order": 1,
      "auto_promote": true,
      "latest_run_status": "pending_approval"
    },
    {
      "workspace_name": "myapp-prod",
      "environment_order": 2,
      "auto_promote": true,
      "latest_run_status": null
    }
  ]
}

Updating a Stack

PATCH /stacks/{id}

Limited mutability. Only these fields can be changed:

Field	Type	Description
`name`	string	Rename the stack
`project_id`	UUID	Move the stack to a different project

Important: Environments cannot be added, removed, or modified after stack creation. To change environments, you must delete the stack and create a new one (workspaces are not deleted — they are unlinked).

Deleting a Stack

DELETE /stacks/{id}

Unlinks, does not cascade. When you delete a stack:

The stack record is deleted
All workspace stack_id fields are set to NULL
Workspaces are not deleted — they continue to exist as independent workspaces
Dependency edges created by the stack are not removed

This is a safety measure — deleting a stack should never accidentally destroy infrastructure.

What You Cannot Do

Add environments to an existing stack
Remove environments from an existing stack
Change an environment’s var_files through the stack API
Change the promotion graph through the stack API

To make these changes, you must:

Delete the stack (workspaces are preserved)
Create a new stack with the desired configuration
Or manage the individual workspaces directly using the workspace API

Managing Individual Workspaces

After stack creation, each workspace is a fully independent workspace. You can:

Modify its settings via PATCH /workspaces/{id}
Trigger runs independently
Add or remove dependencies
Change execution mode

The stack_id field on a workspace is a reference back to its parent stack, but the workspace operates independently.