Stack API reference

Stacks let you split your Terraform configuration into components and then deploy and manage those components across multiple deployments. You can manage the lifecycle of each deployment separately, roll out configuration changes across your deployments, and manage your Stack as a unit in HCP Terraform. To learn more, refer to the Stacks overview.

Overview

The scope of the API includes the following endpoints:

Method	Path	Action
`POST`	`/stacks`	Call this endpoint to create a Stack.
`GET`	`/organizations/:organization_name/ss`	Call this endpoint to list Stacks.
`GET`	`/stacks/:stack_id`	Call this endpoint to show a Stack.
`GET`	`/stacks/:stack_id/stack-configuration-summaries`	Call this endpoint to list Stack configuration summaries.
`PATCH`	`/stacks/:stack_id`	Call this endpoint to update a Stack.
`DELETE`	`/stacks/:stack_id`	Call this endpoint to delete a Stack.

Create a Stack

This endpoint creates a Stack for an organization.

POST /stacks

The ability to create Stacks is restricted to users with Maintain project permissions, teams with the Manage all projects permission, and the organization API token.

Status	Response	Reason
201	JSON API document	Successfully created a Stack.
404	JSON API error object	Not found, or the user is unauthorized to perform this action.
422	JSON API error object	Malformed request body (e.g., missing attributes, wrong types, etc.).
500	JSON API error object	Internal system failure.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`data.attributes.name`	string		The name of the Stack, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the project.
`data.attributes.description`	string	(nothing)	A description for the Stack.
`data.attributes.speculative-enabled`	boolean	`false`	Whether this Stack allows automatic speculative plans. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors.
`data.attributes.trigger-disabled`	boolean		When disabled, plan operations won't automatically start.
`data.attributes.service-provider`	string	(nothing)	The VCS provider being connected with. Valid options are `"github"`, `"github_enterprise"`, `"gitlab_hosted"`, `"gitlab_community_edition"`, `"gitlab_enterprise_edition"`, or `"ado_server"`.
`data.attributes.debugging-mode`	boolean	false	When enabled, plan and apply operations will generate debug level logs.
`data.attributes.vcs-repo`	object		Settings for the Stack's VCS repository.
`data.attributes.vcs-repo.branch`	string	(nothing)	The repository branch used by this Stack's configuration. If omitted or submitted as an empty string, this defaults to the repository's default branch, such as `main`.
`data.attributes.vcs-repo.tags-regex`	string	(previous value)	A regular expression used to match Git tags. HCP Terraform begins preparing a Stack configuration when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression.
`data.attributes.vcs-repo.identifier`	string		A reference to your VCS repository in the format `:org/:repo` where `:org` and `:repo` refer to the organization and repository in your VCS provider.
`data.attributes.vcs-repo.display-identifier`	string	(nothing)	The display identifier for the Stack's VCS repository. For most VCS providers outside of BitBucket Cloud and Azure DevOps, this will match the identifier string.
`data.attributes.vcs-repo.repository-http-url`	string		The HTTP URL for the repository.
`data.attributes.vcs-repo.github-app-installation-id`	string		The VCS connection GitHub App installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from Account Settings within HCP Terraform. You can not specify this value if `oauth-token-id` is specified.
`data.attributes.vcs-repo.oauth-token-id`	string		The VCS Connection (OAuth Connection + Token) to use. You can obtain this ID from the oauth-tokens endpoint.
`data.relationships.project.data.id`	string		The ID of the project to create the Stack in. You must have permission to manage the project, either by organization-level permissions or team admin access to a specific project.
`data.relationships.agent-pool.data.id`	string	(nothing)	The ID of the agent pool to use for Stack operations. If this is omitted, then the Stack will use the Global Agent Pool. The Agent Pool must be available within the project or oganization for the Stack to use.

Sample Payload

{
  "data": {
    "attributes": {
      "vcs-repo": {
        "identifier": "my-organization/basic-stack",
        "display-identifier": "my-organization/basic-stack",
        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
        "branch": "",
        "service-provider": "github",
        "repository-http-url": "https://github.com/my-organization/basic-stack",
        "trigger-disabled": false
      },
      "name": "basic-stack",
      "description": "Example Stack for documentation",
      "speculative-enabled": false
    },
    "relationships": {
      "project": {
        "data": {
          "type": "projects",
          "id": "prj-nG2MW392YZMp1txf"
        }
      }
    }
  }
}

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/stacks

Sample Response

{
  "data": {
    "id": "st-kJcSJemafdBCPw3B",
    "type": "stacks",
    "attributes": {
      "name": "basic-stack",
      "description": "Example Stack for documentation",
      "vcs-repo": {
        "branch": "",
        "tags-regex": null,
        "sparse-checkout-pattern": "",
        "identifier": "my-organization/basic-stack",
        "display-identifier": "my-organization/basic-stack",
        "oauth-token-id": "ot-gRfG6EFP6DJMBKJx",
        "repository-http-url": "https://github.com/my-organization/basic-stack",
        "service-provider": "github",
        "trigger-disabled": false
      },
      "speculative-enabled": false,
      "linked-stack-connections": {
        "upstream-count": 0,
        "downstream-count": 0,
        "inputs-count": 0,
        "outputs-count": 0
      },
      "created-at": "2025-09-16T15:39:44.590Z",
      "updated-at": "2025-09-16T15:39:44.590Z"
    },
    "relationships": {
      "project": {
        "data": {
          "id": "prj-nG2MW392YZMp1txf",
          "type": "projects"
        }
      },
      "agent-pool": {
        "data": null
      },
      "stack-configurations": {
        "links": {
          "related": "/api/v2/stacks/st-kJcSJemafdBCPw3B/stack-configurations"
        }
      }
    },
    "links": {
      "self": "/api/v2/stacks/st-kJcSJemafdBCPw3B"
    },
    "meta": {
      "beta": false
    }
  }
}

List Stacks

This endpoint lists Stacks in the organization.

GET /organizations/:organization_name/stacks

Note

Stack read access is restricted to users or teams with the Read project role and an organization API token.

Parameter	Description
`:organization_name`	List all Stacks under the specified organization

Query Parameters

This endpoint supports pagination with standard URL query parameters; remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 Stacks per page.
`sort`	Optional. Allows sorting the returned Stacks. Valid values are "name" and "updated-at". Prepending a hyphen to the sort parameter reverses the order. For example, `"-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable.

This GET endpoint can optionally return related resources, if requested with the include query parameter. The following resource types are available:

Resource Name	Description
`project`	The full organization record.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/stacks

Sample Response

{
  "data": [
    {
      "id": "st-kJcSJemafdBCPw3B",
      "type": "stacks",
      "attributes": {
        "name": "basic-stack",
        "description": "Example Stack for documentation",
        "vcs-repo": {
          "branch": "",
          "tags-regex": null,
          "sparse-checkout-pattern": "",
          "identifier": "hashicorp-guides/pet-nulls-stack",
          "display-identifier": "hashicorp-guides/pet-nulls-stack",
          "oauth-token-id": "ot-gRfG6EFP6DJMBKJx",
          "repository-http-url": "https://github.com/hashicorp-guides/pet-nulls-stack",
          "service-provider": "github",
          "trigger-disabled": false
        },
        "speculative-enabled": false,
        "linked-stack-connections": {
          "upstream-count": 0,
          "downstream-count": 0,
          "inputs-count": 0,
          "outputs-count": 0
        },
        "created-at": "2025-09-16T15:39:44.590Z",
        "updated-at": "2025-09-16T15:39:44.590Z"
      },
      "relationships": {
        "project": {
          "data": {
            "id": "prj-nG2MW392YZMp1txf",
            "type": "projects"
          }
        },
        "agent-pool": {
          "data": null
        },
        "stack-configurations": {
          "links": {
            "related": "/api/v2/stacks/st-kJcSJemafdBCPw3B/stack-configurations"
          }
        }
      },
      "links": {
        "self": "/api/v2/stacks/st-kJcSJemafdBCPw3B"
      },
      "meta": {
        "beta": false
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/organizations/hashicorp/stacks?page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "first": "https://app.terraform.io/api/v2/organizations/hashicorp/stacks?page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "prev": null,
    "next": "https://app.terraform.io/api/v2/organizations/hashicorp/stacks?page%5Bnumber%5D=2&page%5Bsize%5D=1",
    "last": "https://app.terraform.io/api/v2/organizations/hashicorp/stacks?page%5Bnumber%5D=18&page%5Bsize%5D=1"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 1,
      "prev-page": null,
      "next-page": 2,
      "total-pages": 18,
      "total-count": 18
    }
  }
}

Show a Stack

GET /stacks/:stack_id

This endpoint returns details of the specified Stack.

Note

Stack read access is restricted to users or teams with the Read project role and an organization API token.

Parameter	Description
`:stack_id`	The Stack id.

This GET endpoint can optionally return related resources, if requested with the include query parameter. The following resource types are available:

Resource Name	Description
`latest_stack_configuration`	The latest Stack configuration for the Stack.
`latest_stack_configuration.stack_diagnostics`	The Stack diagnostics associated with the latest configuration.
`organization`	The full organization record.
`project`	The project record.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stacks/st-LSqektntTNJrAhCt

Sample Response

{
  "data": {
    "id": "st-kJcSJemafdBCPw3B",
    "type": "stacks",
    "attributes": {
      "name": "basic-stack",
      "description": "Example Stack for documentation",
      "vcs-repo": {
        "branch": "",
        "tags-regex": null,
        "sparse-checkout-pattern": "",
        "identifier": "hashicorp-guides/pet-nulls-stack",
        "display-identifier": "hashicorp-guides/pet-nulls-stack",
        "oauth-token-id": "ot-gRfG6EFP6DJMBKJx",
        "repository-http-url": "https://github.com/hashicorp-guides/pet-nulls-stack",
        "service-provider": "github",
        "trigger-disabled": false
      },
      "speculative-enabled": false,
      "linked-stack-connections": {
        "upstream-count": 0,
        "downstream-count": 0,
        "inputs-count": 0,
        "outputs-count": 0
      },
      "created-at": "2025-09-16T15:39:44.590Z",
      "updated-at": "2025-09-16T15:39:44.590Z",
      "deleteable": true
    },
    "relationships": {
      "project": {
        "data": {
          "id": "prj-nG2MW392YZMp1txf",
          "type": "projects"
        }
      },
      "agent-pool": {
        "data": null
      },
      "latest-stack-configuration": {
        "data": null
      },
      "stack-configurations": {
        "links": {
          "related": "/api/v2/stacks/st-kJcSJemafdBCPw3B/stack-configurations"
        }
      }
    },
    "links": {
      "self": "/api/v2/stacks/st-kJcSJemafdBCPw3B"
    },
    "meta": {
      "beta": false
    }
  }
}

List Stack configuration summaries

This endpoint lists configuration summaries for the specified Stack.

GET /stacks/:stack_id/stack-configuration-summaries

Parameter	Description
`:stack_id`	The Stack id to list configuration summaries for.

Query Parameters

This endpoint supports pagination with standard URL query parameters; remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 Stack configuration summaries per page.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
   https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96/stack-configuration-summaries

Sample Response

{
  "data": [
    {
      "id": "stc-jEvHkd8DXBK594WD-summary",
      "type": "stack-configuration-summaries",
      "attributes": {
        "status": "completed",
        "sequence-number": 1,
        "stack-deployment-group-status-summary": {
          "pending": 2,
          "deploying": 0,
          "succeeded": 0,
          "failed": 0,
          "abandoned": 0
        }
      },
      "relationships": {
        "stack-configuration": {
          "data": {
            "id": "stc-jEvHkd8DXBK594WD",
            "type": "stack-configurations"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stacks/st-MfwPNTsAEejHJtDw/stack-configuration-summaries?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stacks/st-MfwPNTsAEejHJtDw/stack-configuration-summaries?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stacks/st-MfwPNTsAEejHJtDw/stack-configuration-summaries?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Update a Stack

PATCH /stacks/:stack_id

This endpoint updates the specified Stack.

Parameter	Description
`:stack_id`	The Stack id.

Request Body

This endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`data.attributes.name`	string		The name of the Stack, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the project.
`data.attributes.description`	string	(nothing)	A description for the Stack.
`data.attributes.speculative-enabled`	boolean	`false`	Whether this Stack allows automatic speculative plans. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors.
`data.attributes.trigger-disabled`	boolean		When disabled, plan operations won't automatically start.
`data.attributes.service-provider`	string	(nothing)	The VCS provider being connected with. Valid options are `"github"`, `"github_enterprise"`, `"gitlab_hosted"`, `"gitlab_community_edition"`, `"gitlab_enterprise_edition"`, or `"ado_server"`.
`data.attributes.debugging-mode`	boolean	false	When enabled, plan and apply operations will generate debug level logs.
`data.attributes.vcs-repo`	object		Settings for the Stack's VCS repository.
`data.attributes.vcs-repo.branch`	string	(nothing)	The repository branch used by this Stack's configuration. If omitted or submitted as an empty string, this defaults to the repository's default branch (e.g. `main`).
`data.attributes.vcs-repo.tags-regex`	string	(previous value)	A regular expression used to match Git tags. HCP Terraform begins preparing a Stack configuration when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression.
`data.attributes.vcs-repo.identifier`	string		A reference to your VCS repository in the format `:org/:repo` where `:org` and `:repo` refer to the organization and repository in your VCS provider.
`data.attributes.vcs-repo.display-identifier`	string	(nothing)	The display identifier for the Stack's VCS repository. For most VCS providers outside of BitBucket Cloud and Azure DevOps, this will match the identifier string.
`data.attributes.vcs-repo.repository-http-url`	string		The HTTP URL for the repository.
`data.attributes.vcs-repo.github-app-installation-id`	string		The VCS Connection GitHub App Installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from Account Settings within HCP Terraform. You can not specify this value if `oauth-token-id` is specified.
`data.attributes.vcs-repo.oauth-token-id`	string		The VCS Connection (OAuth Connection + Token) to use. This ID can be obtained from the oauth-tokens endpoint.
`data.relationships.project.data.id`	string		The ID of the project to create the Stack in. You must have permission to manage the project, either by organization-level permissions or team admin access to a specific project.
`data.relationships.agent-pool.data.id`	string	(nothing)	The ID of the agent pool to use for Stack operations. If this is omitted, then the Stack will use the Global Agent Pool. The Agent Pool must be available within the project or oganization for the Stack to use.

Sample Payload

{
  "data": {
    "attributes": {
      "vcs-repo": {
        "identifier": "hashicorp/pet-nulls-stack-local",
        "display-identifier": "hashicorp/pet-nulls-stack-local",
        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
        "branch": "",
        "service-provider": "github",
        "repository-http-url":"https://github.com/hashicorp/pet-nulls-stack-local",
        "tags-regex": null,
        "trigger-disabled": false
      },
      "name": "pet-nulls-stack-local",
      "description": "testing patch",
      "speculative-enabled": false,
      "debugging-mode": false
    }
  }
}

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96

Sample Response

{
  "data": {
    "id": "st-MfwPNTsAEejHJtDw",
    "type": "stacks",
    "attributes": {
      "name": "betatest",
      "description": "testing patch",
      "vcs-repo": {
        "branch": "",
        "tags-regex": null,
        "sparse-checkout-pattern": "",
        "identifier": "hashicorp-guides/pet-nulls-stack",
        "display-identifier": "hashicorp-guides/pet-nulls-stack",
        "oauth-token-id": "ot-gRfG6EFP6DJMBKJx",
        "repository-http-url": "https://github.com/hashicorp-guides/pet-nulls-stack",
        "service-provider": "github",
        "trigger-disabled": false
      },
      "speculative-enabled": false,
      "linked-stack-connections": {
        "upstream-count": 0,
        "downstream-count": 0,
        "inputs-count": 0,
        "outputs-count": 0
      },
      "created-at": "2025-09-11T15:15:46.249Z",
      "updated-at": "2025-09-16T15:48:32.554Z"
    },
    "relationships": {
      "project": {
        "data": {
          "id": "prj-nG2MW392YZMp1txf",
          "type": "projects"
        }
      },
      "agent-pool": {
        "data": null
      },
      "stack-configurations": {
        "links": {
          "related": "/api/v2/stacks/st-MfwPNTsAEejHJtDw/stack-configurations"
        }
      }
    },
    "links": {
      "self": "/api/v2/stacks/st-MfwPNTsAEejHJtDw"
    },
    "meta": {
      "beta": false
    }
  }
}

Delete a Stack

DELETE /stacks/:stack_id

This endpoint deletes the specified Stack.

Parameter	Description
`:stack_id`	The ID of the Stack to delete. Refer to List Stacks for reference information about finding IDs.

Status	Response	Reason
204	No Content	Successfully deleted the Stack
404	JSON API error object	Stack not found, or user unauthorized to perform action

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/stacks/st-EJyw2MktbRjdsg96

Stack API reference

Overview

Create a Stack

Request Body

Sample Payload

Sample Request

Sample Response

List Stacks

Query Parameters

Available Related Resources

Sample Request

Sample Response

Show a Stack

Available Related Resources

Sample Request

Sample Response

List Stack configuration summaries

Query Parameters

Sample Request

Sample Response

Update a Stack

Request Body

Sample Payload

Sample Request

Sample Response

Delete a Stack

Sample Request