Skip to content
Terrateam

Stacks API

Stacks represent logical groupings of Terraform/OpenTofu resources that are managed together. The Stacks API allows you to retrieve stack information for pull requests.

What are Stacks?

Section titled “What are Stacks?”

Stacks in Terrateam allow you to organize your infrastructure into logical groups that can be planned and applied together. This is particularly useful for:

  • Managing dependencies between infrastructure components
  • Coordinating changes across multiple directories
  • Implementing layered infrastructure patterns
  • Ensuring consistent ordering of operations

Learn more in the Stacks documentation.

Get Pull Request Stacks

Section titled “Get Pull Request Stacks”

Retrieve stack configuration and status for a specific pull request.

Endpoint: GET /api/v1/{vcs}/installations/{installation_id}/repos/{repo_id}/prs/{pull_request_id}/stacks

Path Parameters:

NameTypeRequiredDescription
vcsstringYesVCS provider: github or gitlab
installation_idstringYesThe installation identifier
repo_idstringYesThe repository identifier
pull_request_idstringYesThe pull request identifier

Responses:

  • 200: Success - Returns stacks information
  • 403: Forbidden

Response Schema (200):

Schema: stacks

The response includes information about:

  • Stack definitions and dependencies
  • Current stack states
  • Plan/apply status for each stack
  • Ordering information based on dependencies

Example Request:

Terminal window
curl -X GET \
  "https://app.terrateam.io/api/v1/github/installations/{installation_id}/repos/{repo_id}/prs/{pull_request_id}/stacks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Use Cases:

  1. CI/CD Integration: Retrieve stack information to coordinate deployments
  2. Status Dashboards: Display stack status across pull requests
  3. Dependency Visualization: Build tooling to visualize stack dependencies
  4. Custom Automation: Trigger actions based on stack states

Understanding Stack Responses

Section titled “Understanding Stack Responses”

The stacks endpoint returns detailed information about how Terrateam will process the infrastructure changes in a pull request:

Key Information Included:

  • Stack Graph: The dependency graph showing execution order
  • Dirspaces: Which directory-workspace pairs belong to each stack
  • Status: Current state of each stack (pending, running, completed, failed)
  • Dependencies: Which stacks must complete before others can start

This information is essential for understanding the execution plan and coordinating complex infrastructure changes.

Authentication

Section titled “Authentication”

All endpoints require authentication using a short-lived access token:

Authorization: Bearer YOUR_ACCESS_TOKEN

To get an access token:

  1. Create an API key in Settings > API Access in the Terrateam dashboard
  2. Call POST /api/v1/access-token/refresh with your API key to get an access token
  3. Use the access token for API requests

See the Authentication guide for detailed instructions.