Creating Stacks

The Stack Creation API

POST /stacks

This single call creates a stack, one workspace per environment, and dependency edges for the promotion graph — all in one transaction.

Required Fields

Shared Configuration

These fields apply to all workspaces created by the stack:

Environment Configuration

Each environment in the environments array:

Complete Example

{
  "name": "myapp",
  "project_id": "proj-uuid",
  "source_repo_url": "https://github.com/org/infra",
  "source_branch": "main",
  "source_root": "/environments",
  "vcs_integration_id": "vcs-uuid",
  "credential_config_id": "cred-uuid",
  "state_backend_config_id": "state-uuid",
  "execution_target": 0,
  "environments": [
    {
      "name": "dev",
      "var_files": ["env/dev.tfvars"],
      "promote_to": ["staging"]
    },
    {
      "name": "staging",
      "var_files": ["env/staging.tfvars"],
      "promote_to": ["prod"]
    },
    {
      "name": "prod",
      "var_files": ["env/prod.tfvars"],
      "promote_to": []
    }
  ]
}

This creates:

• Workspaces: myapp-dev, myapp-staging, myapp-prod
• State keys: myapp/dev, myapp/staging, myapp/prod
• Dependency edges: myapp-dev → myapp-staging → myapp-prod (with auto_promote: true)

Workspace Naming

Workspaces are automatically named {stack}-{env}. You cannot customize individual workspace names — the convention ensures consistency.

State Key Generation

State keys are automatically generated as {stack}/{env}. This prevents collisions between environments sharing the same state backend bucket.

Response

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

Environment Immutability

Stack environments are immutable after creation. You cannot add, remove, or reorder environments on an existing stack. This is by design — environments map 1:1 to workspaces and state files, which cannot be safely renamed or reordered.

To change the environment composition:

1. Delete the existing stack (this unlinks workspaces but does not delete them)
2. Create a new stack with the desired environments
3. Manually clean up or reassign orphaned workspaces from the old stack

Plan your environment structure carefully before creating a stack. The name, project_id, and environment list are set once at creation.

Related API Endpoints

• POST /stacks — Create a stack
• GET /stacks — List all stacks
• GET /stacks/{id} — Get stack detail with environment status