Stack configurations API reference

A Stack configuration version is a snapshot of all of the pieces that make up your Stack. To learn more about what makes up a Stack configuration version, refer to Configuration versions.

Overview

The scope of the API includes the following endpoints:

Method	Path	Action
`POST`	`/stacks/:stack_id/stack-configurations`	Call this endpoint to create a Stack configuration.
`POST`	`/stacks/:stack_id/fetch-latest-from-vcs`	Call this endpoint to fetch the latest Stack configuration.
`GET`	`/stacks/:stack_id/stack-configurations`	Call this endpoint to list Stack configurations.
`GET`	`/stack-configurations/:stack_configuration_id`	Call this endpoint to show a Stack configuration.
`GET`	`/stack-configurations/:stack_configuration_id/stack-deployment-group-summaries`	Call this endpoint to list Deployment Group Summaries.
`GET`	`/stack-configurations/:stack_configuration_id/stack-diagnostics`	Call this endpoint to list Stack configuration diagnostics.
`GET`	`/stack-configurations/:stack_configuration_id/upload-url`	Call this endpoint to fetch Stack configuration upload url.
`GET`	`/stack-configurations/:stack_configuration_id/source-bundle`	Call this endpoint to fetch Stack configuration source bundle.

Create a Stack configuration

This endpoint creates an empty Stack configuration for the specified Stack. You will have to upload a configuration file to the Stack configurations upload URL to let the Stack prepare a job to run and generate plans. This endpoint cannot be used if the Stack is connected to a VCS repo.

POST /stacks/:stack_id/stack-configurations

Parameter	Description
`:stack_id`	The target Stack ID to create a configuration

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.speculative`	boolean	`false`	Specifies if this is a speculative configuration that HCP Terraform cannot converge past the plan step.

Status	Response	Reason
200	JSON API document	Successfully created a Stack configuration.
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.

Sample Payload

{
  "data": {
    "attributes": {
      "speculative": true
    }
  }
}

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/st-YwBzgFeeW6Mq4wkH/stack-configurations

Sample Response

{
  "data": {
    "id": "stc-4EWffseuNa1FpfDH",
    "type": "stack-configurations",
    "attributes": {
      "status": "pending",
      "sequence-number": 2,
      "preparing-event-stream-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6WTVtSkdnbE01anBlK3A2dEhWd3ZKYlB0M2hUSzFkNm9PdWhrcWo4QzdMMURIUnFNSTlOSFZGdkt6ZloxWjZlUUlYaEd2cnlVV3NoNnlweHNzNnZNQkRVSk9JS2R2NE80Q2ZWTHhsbGxwRzgyMnQrVWlEd3o2c2VueEs1ZGducmtmNG0rdmIzR1hxeGtmZThsTk1hUTJLNHJrSkZiUk5saEpad1lEelF1aEZ3MG8zTks2VlNldHRHV0YzUG0rUmdneUpsOXU2QlFaYk9EUjlEUWlTZUpQeUE4UEVwejczZmxxRFgrTGIwaDVzQmxwUHNuUWZycEtKZm9VQmZpemZCbSs0RWJxdC9BbFlpM216VXE3dk1GcnplbkxIQ2FyM3Q3Y0o5WGc1QjFLUElGRHRweXI4VE1JOWFHUm9iQ1NwSXJpR2pVdng4OHh1U0FLWXpYVUwvZTJuUSs2WURSd1FoMDNVUm5jYmhmWStGK3VVL3p3QmtYcG1laA",
      "created-at": "2025-09-16T16:29:22.855Z",
      "updated-at": "2025-09-16T16:29:22.855Z",
      "speculative": false,
      "components": []
    },
    "relationships": {
      "stack": {
        "data": {
          "id": "st-YwBzgFeeW6Mq4wkH",
          "type": "stacks"
        }
      },
      "stack-diagnostics": {
        "links": {
          "related": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH/stack-diagnostics"
        }
      },
      "stack-deployment-groups": {
        "links": {
          "related": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH/stack-deployment-groups"
        }
      }
    },
    "links": {
      "self": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH",
      "json-schemas": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH/json-schemas"
    },
    "meta": {
      "beta": false
    }
  }
}

Fetch a Stack configuration

This endpoint creates a Stack configuration for a VCS-backed Stack by pulling it from the head of the Stack's branch.

POST /stacks/:stack_id/fetch-latest-from-vcs

Parameter	Description
`:stack_id`	The target Stack ID to fetch a configuration for.

Status	Response	Reason
204	No Content	Successfully started the process of retrieving the latest configuration from VCS.
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" \
  https://app.terraform.io/api/v2/stack/st-SihZTyXKfNXUWuUa/fetch-latest-from-vcs

List Stack configurations

This endpoint lists configurations for the specified Stack.

GET /stacks/:stack_id/stack-configurations

Parameter	Description
`:stack_id`	The Stack id to list configurations 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 configurations per page.

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

Resource Name	Description
`ingress_attributes`	The vcs information associated with the Stack configurations.

Sample Request

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

Sample Response

{
  "data": [
    {
      "id": "stc-4EWffseuNa1FpfDH",
      "type": "stack-configurations",
      "attributes": {
        "status": "pending",
        "sequence-number": 2,
        "preparing-event-stream-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6N2JTaDVOcEVwbFZVR21vZTBkaEl4S1dOY0VRREMrdnB1L0hGUTFmWnNvdUZVaVpYWDdLZWJPMUhjRmdkdkJVY0gzc245VG9KMVpjTXFTbE9JWlJwQ2FzbTh0c3pUNFRzWW1OV1pIbjhTMVVEa0V3MVlCYVNLYXdsaUNLYU1QellZVzZDdFQ1ZStIczhnd1o4cnprd1hjZEJTaUZnMXJsRzF4aXFidXdaNHBXM0VLeFR6N3JiYkZpVEE5OU9jRTU2SVpaa29kSXJuWlowYW1La0FKL1VjT095eCtNUTRXMUJ0S3VydytWZ0Z3dWZtdHYrNkFwVDg0RmdVb1FGOTBIRS9JZjgvWk81QXgyOWl3U1pRa0pzVnByUWdIMFE4UTBNQzk5N2lkaWNzZmpVdVRwTWR3ZUJUNlFEN0JVSENjVU94Yi82ZUkwV1NVS21vZnNKMjk2QTNxSS91OGNOUUZjRVpmNE1Cb3pYa1hpd2pIaVJPVEdRNEhKZw",
        "created-at": "2025-09-16T16:29:22.855Z",
        "updated-at": "2025-09-16T16:29:22.855Z",
        "speculative": false,
        "components": []
      },
      "relationships": {
        "stack": {
          "data": {
            "id": "st-YwBzgFeeW6Mq4wkH",
            "type": "stacks"
          }
        },
        "stack-diagnostics": {
          "links": {
            "related": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH/stack-diagnostics"
          }
        },
        "stack-deployment-groups": {
          "links": {
            "related": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH/stack-deployment-groups"
          }
        }
      },
      "links": {
        "self": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH",
        "json-schemas": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH/json-schemas"
      },
      "meta": {
        "beta": false
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stacks/st-YwBzgFeeW6Mq4wkH/stack-configurations?page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "first": "https://app.terraform.io/api/v2/stacks/st-YwBzgFeeW6Mq4wkH/stack-configurations?page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "prev": null,
    "next": "https://app.terraform.io/api/v2/stacks/st-YwBzgFeeW6Mq4wkH/stack-configurations?page%5Bnumber%5D=2&page%5Bsize%5D=1",
    "last": "https://app.terraform.io/api/v2/stacks/st-YwBzgFeeW6Mq4wkH/stack-configurations?page%5Bnumber%5D=2&page%5Bsize%5D=1"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 1,
      "prev-page": null,
      "next-page": 2,
      "total-pages": 2,
      "total-count": 2
    }
  }
}

Show Stack configuration

GET /stack-configurations/:stack_configuration_id

This endpoint returns details of the specified Stack configuration.

Parameter	Description
`:stack_configuration_id`	The Stack configuration 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
`ingress_attributes`	The vcs information associated with the Stack configuration.
`stack_diagnostics`	The Stack diagnostics associated with the Stack configuration.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH

Sample Response

{
  "data": {
    "id": "stc-4EWffseuNa1FpfDH",
    "type": "stack-configurations",
    "attributes": {
      "status": "pending",
      "sequence-number": 2,
      "preparing-event-stream-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6Umh4WE9sTUlGb0F3Q0NFTUQ4a2ZIOUlvZ1ZWNmlEOERFRVgyUVBJY2ZZMGgwbUJpS0tQd2FYdjYvOUpMLzAyTUdlM2hLYWt5RGdlRmZUZm84b0trajZpenNodDcrVzB4Y3ZDanhWYUZ0YXFGRWx4aG5GMFVwQ2VmbUtVSzU0L2dKYjJGdE5rekoydG9mTEF6bnR1L2hDcjEvYkxtNUNyOE90UUxlVEQ3cTl3emtqTU9IQlFOeDhIcnk3Tk8yNVZRcm9JQ2swUjdsYmZ6OTJBS0FuOWpJSmF3Y0ZDK2NEU3hoRmFoL0VUWVhIR25QVUxJSmFvK2RqcytlQ2JMc1ROZVphNDFBcEVoUjJZeGJSYyttSEwydnhCTjhnUnFyVXlCUEJOUlVyR0g1aW1pMHFuZ1EybTIxOGpjNWJlMnYrRHY5L0swV3RodGIvZk1DejN5SFBGSnJtVndyS2NGMmpUekd6ajByd2RyeXZqdHVLcFRIUnFobWdTeQ",
      "created-at": "2025-09-16T16:29:22.855Z",
      "updated-at": "2025-09-16T16:29:22.855Z",
      "speculative": false,
      "components": []
    },
    "relationships": {
      "stack": {
        "data": {
          "id": "st-YwBzgFeeW6Mq4wkH",
          "type": "stacks"
        }
      },
      "stack-diagnostics": {
        "links": {
          "related": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH/stack-diagnostics"
        }
      },
      "stack-deployment-groups": {
        "links": {
          "related": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH/stack-deployment-groups"
        }
      }
    },
    "links": {
      "self": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH",
      "json-schemas": "/api/v2/stack-configurations/stc-4EWffseuNa1FpfDH/json-schemas"
    },
    "meta": {
      "beta": false
    }
  }
}

List Deployment Group Summaries

This endpoint lists deployment group summaries for the specified Stack configuration.

GET /stack-configurations/:stack_configuration_id/stack-deployment-group-summaries

Parameter	Description
`:stack_configuration_id`	The Stack configuration id to list the deployment group 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/stack-configurations/stc-yyu5ajbMU45nea3L/stack-deployment-group-summaries

Sample Response

{
  "data": [
    {
      "id": "sdg-wPG9EBFcz7LvYSJ9",
      "type": "stack-deployment-group-summaries",
      "attributes": {
        "name": "simple_default",
        "status": "succeeded",
        "status-counts": {
          "pending": 0,
          "pre-deploying": 0,
          "pre-deploying-pending-operator": 0,
          "acquiring-lock": 0,
          "deploying": 0,
          "deploying-pending-operator": 0,
          "succeeded": 1,
          "failed": 0,
          "abandoned": 0
        }
      },
      "relationships": {
        "stack-deployment-group": {
          "data": {
            "id": "sdg-wPG9EBFcz7LvYSJ9",
            "type": "stack-deployment-groups"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-configurations/stc-yyu5ajbMU45nea3L/stack-deployment-group-summaries?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-configurations/stc-yyu5ajbMU45nea3L/stack-deployment-group-summaries?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-configurations/stc-yyu5ajbMU45nea3L/stack-deployment-group-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
    }
  }
}

List Stack configuration diagnostics

This endpoint lists the diagnostics related to the preparation process for the specified Stack configuration.

GET /stack-configurations/:stack_configuration_id/stack-diagnostics

Parameter	Description
`:stack_configuration_id`	The Stack configuration id to list the diagnostics 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 diagnostics per page.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-configurations/stc-vHvM8dY1cYCVsfuT/stack-diagnostics

Sample Response

{
  "data": [
    {
      "id": "std-fU7vZ3RS1TRYnrUs",
      "type": "stack-diagnostics",
      "attributes": {
        "severity": "error",
        "summary": "Diagnostics reported",
        "detail": "While preparing the configuration, HCP Terraform reported 1 error.",
        "diags": [
          {
            "range": {
              "end": {
                "byte": 213,
                "line": 10,
                "column": 4
              },
              "start": {
                "byte": 212,
                "line": 10,
                "column": 3
              },
              "source": "git::https://github.com/aaabdelgany/pet-nulls-stack.git//deployments.tfdeploy.hcl?ref=41607dab260dcd108a81ce1fa935bf72c93abbf6",
              "filename": "deployments.tfdeploy.hcl"
            },
            "detail": "The argument \"deployment_group\" was already set at git::https://github.com/aaabdelgany/pet-nulls-stack.git//deployments.tfdeploy.hcl?ref=41607dab260dcd108a81ce1fa935bf72c93abbf6:9,3-19. Each argument may be set only once.",
            "snippet": {
              "code": "  deployment_group = deployment_group.custom2",
              "values": [],
              "context": "deployment \"simple\"",
              "start_line": 10,
              "highlight_end_offset": 3,
              "highlight_start_offset": 2
            },
            "summary": "Attribute redefined",
            "severity": "error"
          }
        ],
        "acknowledged": true,
        "acknowledged-at": "2025-08-27T18:29:33.605Z",
        "created-at": "2025-08-27T18:16:37.380Z"
      },
      "relationships": {
        "stack-configuration": {
          "data": {
            "id": "stc-vHvM8dY1cYCVsfuT",
            "type": "stack-configurations"
          }
        }
      },
      "links": {
        "self": "/api/v2/stack-diagnostics/std-fU7vZ3RS1TRYnrUs"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-configurations/stc-vHvM8dY1cYCVsfuT/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-configurations/stc-vHvM8dY1cYCVsfuT/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-configurations/stc-vHvM8dY1cYCVsfuT/stack-diagnostics?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
    }
  }
}

Fetch Stack configuration upload URL

GET /stack-configurations/:stack_configuration_id/upload-url

This endpoint fetches the Stack configuration upload url. Use this URL to upload a raw configuration file for a manually created Stack configuration.

Parameter	Description
`:stack_configuration_id`	The Stack configuration id to fetch the upload URL for.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-configurations/stc-SihZTyXKfNXUWuUa/upload-url

Sample Response

{
  "data": {
    "source-upload-url": "https://github.com/stack-config-uploads"
  },
  "links": {
    "self": "/api/v2/stack-configurations/stc-SihZTyXKfNXUWuUa/upload-url"
  }
}

Fetch Stack configuration source bundle

GET /stack-configurations/:stack_configuration_id/source-bundle

This endpoint redirects to the download URL for a Stack configuration source bundle.

Parameter	Description
`:stack_configuration_id`	The Stack configuration id to fetch the source bundle for.

Status	Response	Reason
302	HTTP Redirect	Successfully redirect client to temporary source bundle download URL
404	JSON API error object	Stack configuration not found, or user unauthorized to perform action

Stack configurations API reference

Overview

Create a Stack configuration

Request Body

Sample Payload

Sample Request

Sample Response

Fetch a Stack configuration

Sample Request

List Stack configurations

Query Parameters

Available Related Resources

Sample Request

Sample Response

Show Stack configuration

Available Related Resources

Sample Request

Sample Response

List Deployment Group Summaries

Query Parameters

Sample Request

Sample Response

List Stack configuration diagnostics

Query Parameters

Sample Request

Sample Response

Fetch Stack configuration upload URL

Sample Request

Sample Response

Fetch Stack configuration source bundle