Stack states API reference

Stack states offer deeper insight into the state of a particular Stack deployment.

Overview

The scope of the API includes the following endpoints:

Method	Path	Action
`GET`	`/stacks/:stack_id/stack-states`	Call this endpoint to list Stack states.
`GET`	`/stack-states/:stack_state_id`	Call this endpoint to show a Stack state.
`GET`	`/stack-states/:stack_state_id/description`	Call this endpoint to show a Stack state description.

List Stack states

This endpoint lists states for a Stack.

GET /stacks/:stack_id/stack-states

Parameter	Description
`:stack_id`	The ID of the Stack to list the states of.

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 states per page.

Sample Request

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

Sample Response

{
  "data": [
    {
      "id": "sts-ykymXedzS8mbXKGc",
      "type": "stack-states",
      "attributes": {
        "generation": 1,
        "status": "completed",
        "deployment": "simple",
        "components": [
          {
            "address": "component.pet",
            "component-address": "component.pet",
            "instance-correlator": "ZLqa501mJ7nhAw2LjjI0EGseuFR73XnXVubflsHFj/4=",
            "component-correlator": "mVeO7lZxmV5xQ9Hr+JOAljxocBy301AqmloiGV9yohg=",
            "resource-instance-count": 3
          },
          {
            "address": "component.nulls",
            "component-address": "component.nulls",
            "instance-correlator": "gA0VCfa68e5TerC8yiNFUPa1PgLFqeV0HAf9t8j8vYE=",
            "component-correlator": "tgwFPu/Y6FxtySWdN/SjfLf01WUsOwtrefsbNLXfauI=",
            "resource-instance-count": 1
          },
          {
            "address": "component.nils",
            "component-address": "component.nils",
            "instance-correlator": "+0KI2KgtqbfLK27i3RWObJ7cU9LM5ksPkkOwiTMeNmE=",
            "component-correlator": "sqlcMWrMGhp3ZydAWIRw6wDXIeO5FBK9G6mC1Gw/oGo=",
            "resource-instance-count": 9
          }
        ],
        "is-current": true,
        "resource-instance-count": 13
      },
      "relationships": {
        "stack": {
          "data": {
            "id": "st-YwBzgFeeW6Mq4wkH",
            "type": "stacks"
          }
        },
        "stack-deployment-run": {
          "data": null
        }
      },
      "links": {
        "self": "/api/v2/stack-states/sts-ykymXedzS8mbXKGc",
        "description": "/api/v2/stack-states/sts-ykymXedzS8mbXKGc/description"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stacks/st-YwBzgFeeW6Mq4wkH/stack-states?page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "first": "https://app.terraform.io/api/v2/stacks/st-YwBzgFeeW6Mq4wkH/stack-states?page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "prev": null,
    "next": "https://app.terraform.io/api/v2/stacks/st-YwBzgFeeW6Mq4wkH/stack-states?page%5Bnumber%5D=2&page%5Bsize%5D=1",
    "last": "https://app.terraform.io/api/v2/stacks/st-YwBzgFeeW6Mq4wkH/stack-states?page%5Bnumber%5D=3&page%5Bsize%5D=1"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 1,
      "prev-page": null,
      "next-page": 2,
      "total-pages": 3,
      "total-count": 3
    }
  }
}

Show a Stack state

This endpoint lists details about a Stack state.

GET /stack_states/:stack_state_id

Parameter	Description
`:stack_state_id`	The ID of the Stack state to get details for.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-states/sts-PrqektntTNJrAhCm

Sample Response

{
  "data": {
    "id": "sts-ykymXedzS8mbXKGc",
    "type": "stack-states",
    "attributes": {
      "generation": 1,
      "status": "completed",
      "deployment": "simple",
      "components": [
        {
          "address": "component.pet",
          "component-address": "component.pet",
          "instance-correlator": "ZLqa501mJ7nhAw2LjjI0EGseuFR73XnXVubflsHFj/4=",
          "component-correlator": "mVeO7lZxmV5xQ9Hr+JOAljxocBy301AqmloiGV9yohg=",
          "resource-instance-count": 3
        },
        {
          "address": "component.nulls",
          "component-address": "component.nulls",
          "instance-correlator": "gA0VCfa68e5TerC8yiNFUPa1PgLFqeV0HAf9t8j8vYE=",
          "component-correlator": "tgwFPu/Y6FxtySWdN/SjfLf01WUsOwtrefsbNLXfauI=",
          "resource-instance-count": 1
        },
        {
          "address": "component.nils",
          "component-address": "component.nils",
          "instance-correlator": "+0KI2KgtqbfLK27i3RWObJ7cU9LM5ksPkkOwiTMeNmE=",
          "component-correlator": "sqlcMWrMGhp3ZydAWIRw6wDXIeO5FBK9G6mC1Gw/oGo=",
          "resource-instance-count": 9
        }
      ],
      "is-current": true,
      "resource-instance-count": 13
    },
    "relationships": {
      "stack": {
        "data": {
          "id": "st-YwBzgFeeW6Mq4wkH",
          "type": "stacks"
        }
      },
      "stack-deployment-run": {
        "data": null
      }
    },
    "links": {
      "self": "/api/v2/stack-states/sts-ykymXedzS8mbXKGc",
      "description": "/api/v2/stack-states/sts-ykymXedzS8mbXKGc/description"
    }
  }
}

Show a Stack state description

This endpoint redirects to a download URL for a Stack state description.

GET /stack-states/:stack_state_id/description

Parameter	Description
`:stack_state_id`	The ID of the Stack state to get a description for.

Status	Response	Reason
204	No Content	Responds with empty success when state has not yet been uploaded.
307	JSON API error object	Redirect client to temporary Stack state description download URL.
404	JSON API error object	Stack state 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-states/sts-LSqektntTNJrAhCt/description