Stack deployments API reference

You can create Stack deployments in a Stack's deployment.tfdeploy.hcl file. A deployment consists of a deployment group, at least one deployment run, and at least one deployment step. To learn more, refer to Define deployment configuration.

Overview

The scope of the API includes the following endpoints:

Method	Path	Action
`GET`	`/stacks/:stack_id/stack-deployments`	Call this endpoint to list Stack deployments.
`GET`	`/stack-configurations/:stack_configuration_id/stack-deployment-groups`	Call this endpoint to list Stack deployment groups.
`GET`	`/stack-configurations/:stack_configuration_id/stack-deployment-groups/:stack_deployment_group_name`	Call this endpoint to show a Stack deployment group by name.
`GET`	`/stack-deployment-groups/:stack_deployment_group_id`	Call this endpoint to show a Stack deployment group by ID.
`GET`	`/stack-deployment-groups/:stack_deployment_group_id/stack-deployment-runs`	Call this endpoint to list Stack deployment runs.
`GET`	`/stacks/:stack_id/stack-deployments/:deployment_name/stack-deployment-runs`	Call this endpoint to list deployment runs for a deployment group.
`GET`	`/stack-deployment-runs/:stack_deployment_run_id`	Call this endpoint to show a Stack deployment run.
`GET`	`/stack-deployment-runs/:stack_deployment_run_id/stack-deployment-steps`	Call this endpoint to list Stack deployment steps.
`GET`	`/stack-deployment-steps/:stack_deployment_step_id`	Call this endpoint to show a Stack deployment step.
`GET`	`/stack-deployment-steps/:stack_deployment_step_id/stack-diagnostics`	Call this endpoint to list Stack deployment step diagnostics.
`GET`	`/stack-deployment-steps/:stack_deployment_step_id/artifacts`	Call this endpoint to retrieve a deployment steps artifacts.
`GET`	`/stack-approvals/:stack_approval_id`	Call this endpoint to show a Stack approval.
`POST`	`/stack-deployment-groups/:stack_deployment_group_id/approve-all-plans`	Call this endpoint to approve a Stack deployment group.
`POST`	`/stack-deployment-groups/:stack_deployment_group_id/rerun`	Call this endpoint to rerun a Stack deployment group.
`POST`	`/stack-deployment-runs/:stack_deployment_run_id/approve-all-plans`	Call this endpoint to approve a Stack deployment run.
`POST`	`/stack-deployment-runs/:stack_deployment_run_id/cancel`	Call this endpoint to cancel a Stack deployment run.
`POST`	`/stack-deployment-steps/:stack_deployment_step_id/advance`	Call this endpoint to advance a Stack deployment step.

List Stack deployments

This endpoint lists all the deployments under the specified Stack.

GET /stacks/:stack_id/stack-deployments

Parameter	Description
`:stack_id`	The id of the Stack to list deployments 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 Stacks deployments 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
`latest_deployment_run`	The latest deployment run associated with that deployment.
`latest_deployment_run.stack_configuration`	The Stack configuration associated with the latest deployment run.

Sample Request

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

Sample Response

{
  "data": [
    {
      "id": "st-MWvJsvy1FCg3bnXY-std-simple",
      "type": "stack-deployments",
      "attributes": {
        "name": "simple"
      },
      "relationships": {
        "stack": {
          "data": {
            "id": "st-MWvJsvy1FCg3bnXY",
            "type": "stacks"
          }
        },
        "latest-deployment-run": {
          "data": {
            "id": "sdr-vzub48Y4f7sFBk7J",
            "type": "stack-deployment-runs"
          }
        }
      },
      "links": {
        "self": "/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments/simple",
        "stack-deployment-runs": "/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments/simple/stack-deployment-runs"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stacks/st-MWvJsvy1FCg3bnXY/stack-deployments?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 deployment groups

This endpoint lists all the deployment groups for the specified Stack configuration.

GET /stack-configurations/:stack_configuration_id/stack-deployment-groups

Parameter	Description
`:stack_configuration_id`	The id of the Stack configuration to list deployment groups 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 deployment groups 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-d7w6uC1QEB6fqWjW/stack-deployment-groups

Sample Response

{
  "data": [
    {
      "id": "sdg-f5GVSZb7HxQ5aWG7",
      "type": "stack-deployment-groups",
      "attributes": {
        "status": "pending",
        "created-at": "2025-09-16T14:46:45.026Z",
        "updated-at": "2025-09-16T14:46:45.026Z",
        "deploying-at": null,
        "succeeded-at": null,
        "failed-at": null,
        "abandoned-at": null,
        "name": "simple_default",
        "deployment-group-config": {
          "auto-approve-checks": []
        }
      },
      "relationships": {
        "stack-configuration": {
          "data": {
            "id": "stc-d7w6uC1QEB6fqWjW",
            "type": "stack-configurations"
          }
        },
        "stack-approvals": {
          "data": []
        },
        "stack-deployment-runs": {
          "links": {
            "related": "/api/v2/stack-deployment-groups/sdg-f5GVSZb7HxQ5aWG7/stack-deployment-runs"
          }
        }
      },
      "links": {
        "self": "/api/v2/stack-deployment-groups/sdg-f5GVSZb7HxQ5aWG7",
        "stack-deployment-group-summaries": "/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-group-summaries"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-groups?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
    }
  }
}

Show a Stack deployment group by name

This endpoint gets details about a Stack deployment group by name

GET /stack-configurations/:stack_configuration_id/stack-deployment-groups/:stack_deployment_group_name

Parameter	Description
`:stack_configuration_id`	The id of the Stack configuration to fetch the deployment groups for.
`:stack_deployment_group_name`	The name of the Stack deployment group.

Sample Request

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

Sample Response

{
  "data": {
    "id": "sdg-f5GVSZb7HxQ5aWG7",
    "type": "stack-deployment-groups",
    "attributes": {
      "status": "pending",
      "created-at": "2025-09-16T14:46:45.026Z",
      "updated-at": "2025-09-16T14:46:45.026Z",
      "deploying-at": null,
      "succeeded-at": null,
      "failed-at": null,
      "abandoned-at": null,
      "name": "simple_default",
      "deployment-group-config": {
        "auto-approve-checks": []
      }
    },
    "relationships": {
      "stack-configuration": {
        "data": {
          "id": "stc-d7w6uC1QEB6fqWjW",
          "type": "stack-configurations"
        }
      },
      "stack-approvals": {
        "data": []
      },
      "stack-deployment-runs": {
        "links": {
          "related": "/api/v2/stack-deployment-groups/sdg-f5GVSZb7HxQ5aWG7/stack-deployment-runs"
        }
      }
    },
    "links": {
      "self": "/api/v2/stack-deployment-groups/sdg-f5GVSZb7HxQ5aWG7",
      "stack-deployment-group-summaries": "/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-group-summaries"
    }
  }
}

Show a Stack deployment group by ID

This endpoint gets details about a Stack deployment group by ID.

GET /stack-deployment-groups/:stack_deployment_group_id

Parameter	Description
`:stack_deployment_group_id`	The id of the Stack deployment group to fetch.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-groups/sdg-f5GVSZb7HxQ5aWG7

Sample Response

{
  "data": {
    "id": "sdg-f5GVSZb7HxQ5aWG7",
    "type": "stack-deployment-groups",
    "attributes": {
      "status": "pending",
      "created-at": "2025-09-16T14:46:45.026Z",
      "updated-at": "2025-09-16T14:46:45.026Z",
      "deploying-at": null,
      "succeeded-at": null,
      "failed-at": null,
      "abandoned-at": null,
      "name": "simple_default",
      "deployment-group-config": {
        "auto-approve-checks": []
      }
    },
    "relationships": {
      "stack-configuration": {
        "data": {
          "id": "stc-d7w6uC1QEB6fqWjW",
          "type": "stack-configurations"
        }
      },
      "stack-approvals": {
        "data": []
      },
      "stack-deployment-runs": {
        "links": {
          "related": "/api/v2/stack-deployment-groups/sdg-f5GVSZb7HxQ5aWG7/stack-deployment-runs"
        }
      }
    },
    "links": {
      "self": "/api/v2/stack-deployment-groups/sdg-f5GVSZb7HxQ5aWG7",
      "stack-deployment-group-summaries": "/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-group-summaries"
    }
  }
}

List Stack deployment runs in a configuration

This endpoint lists Stack deployment runs for a Stack configuration.

GET /stack-configurations/:stack_configuration_id/stack-deployment-runs

Parameter	Description
`:stack_configuration_id`	The id of the Stack deployment group for which Stack deployment runs are being listed.

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 deployment runs 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
`stack_deployment_group`	The deployment group that contains the run.
`stack_approval`	The Stack approval created for the deployment run.
`destroy_stack_configuration`	The configuration that last referenced a deployment that has been omitted in the configuration that contains the specified run.
`current_step`	The current step for the deployment run.

Sample Request

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

Sample Response

{
  "data": [
    {
      "id": "sdr-AUkZBKdkE9vRKDsi",
      "type": "stack-deployment-runs",
      "attributes": {
        "status": "pre_deploying_pending_operator",
        "deployment": "simple",
        "created-at": "2025-09-16T14:46:45.032Z",
        "updated-at": "2025-09-16T14:46:45.121Z",
        "pre-deploying-at": "2025-09-16T14:46:45.067Z",
        "pre-deploying-pending-operator-at": "2025-09-16T14:46:45.121Z",
        "acquiring-lock-at": null,
        "deploying-at": null,
        "deploying-pending-operator-at": null,
        "succeeded-at": null,
        "failed-at": null,
        "abandoned-at": null,
        "plan-mode": "plan"
      },
      "relationships": {
        "stack-deployment-group": {
          "data": {
            "id": "sdg-f5GVSZb7HxQ5aWG7",
            "type": "stack-deployment-groups"
          }
        },
        "stack-configuration": {
          "data": {
            "id": "stc-d7w6uC1QEB6fqWjW",
            "type": "stack-configurations"
          }
        },
        "stack-deployment-steps": {
          "links": {
            "related": "/api/v2/stack-deployment-runs/sdr-AUkZBKdkE9vRKDsi/stack-deployment-steps"
          }
        },
        "stack-approval": {
          "data": null
        },
        "current-step": {
          "data": {
            "id": "sds-HQuuzLYg8rcPSbRt",
            "type": "stack-deployment-steps"
          }
        },
        "destroy-stack-configuration": {
          "data": null
        },
        "latest-deployment-run-for-deployment": {
          "data": null
        },
        "blocked-by-deployment-group": {
          "data": null
        }
      },
      "links": {
        "self": "/api/v2/stack-deployment-runs/sdr-AUkZBKdkE9vRKDsi"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-configurations/stc-d7w6uC1QEB6fqWjW/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "status-counts": {
      "total": 1
    },
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

List Stack deployment runs in a group

This endpoint lists Stack deployment runs for a Stack deployment group.

GET /stack-deployment-groups/:stack_deployment_group_id/stack-deployment-runs

Parameter	Description
`:stack_deployment_group_id`	The id of the Stack deployment group for which Stack deployment runs are being listed.

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 deployment runs 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
`stack_deployment_group`	The deployment group that contains the run.
`stack_approval`	The Stack approval created for the deployment run.
`destroy_stack_configuration`	The configuration that last referenced a deployment that has been omitted in the configuration that contains the specified run.
`blocked_by_deployment_group`	The deployment group that is blocking this run from proceeding.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-groups/stg-RSqektntTNJrAhCm/stack-deployment-runs

Sample Response

{
  "data": [
    {
      "id": "sdr-A7Ly5aDFHUepLeF7",
      "type": "stack-deployment-runs",
      "attributes": {
        "status": "pre_deploying_pending_operator",
        "deployment": "simple",
        "created-at": "2025-09-11T15:33:25.141Z",
        "updated-at": "2025-09-11T15:33:33.390Z",
        "pre-deploying-at": "2025-09-11T15:33:25.273Z",
        "pre-deploying-pending-operator-at": "2025-09-11T15:33:33.390Z",
        "acquiring-lock-at": null,
        "deploying-at": null,
        "deploying-pending-operator-at": null,
        "succeeded-at": null,
        "failed-at": null,
        "abandoned-at": null,
        "plan-mode": "normal"
      },
      "relationships": {
        "stack-deployment-group": {
          "data": {
            "id": "sdg-LwBSiWxcrjhYBGMK",
            "type": "stack-deployment-groups"
          }
        },
        "stack-configuration": {
          "data": {
            "id": "stc-jEvHkd8DXBK594WD",
            "type": "stack-configurations"
          }
        },
        "stack-deployment-steps": {
          "links": {
            "related": "/api/v2/stack-deployment-runs/sdr-A7Ly5aDFHUepLeF7/stack-deployment-steps"
          }
        },
        "stack-approval": {
          "data": null
        },
        "current-step": {
          "data": {
            "id": "sds-qbXEc9fNpt7MNpKT",
            "type": "stack-deployment-steps"
          }
        },
        "destroy-stack-configuration": {
          "data": null
        },
        "latest-deployment-run-for-deployment": {
          "data": null
        },
        "blocked-by-deployment-group": {
          "data": null
        }
      },
      "links": {
        "self": "/api/v2/stack-deployment-runs/sdr-A7Ly5aDFHUepLeF7"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-deployment-groups/sdg-LwBSiWxcrjhYBGMK/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-deployment-groups/sdg-LwBSiWxcrjhYBGMK/stack-deployment-runs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-deployment-groups/sdg-LwBSiWxcrjhYBGMK/stack-deployment-runs?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
    }
  }
}

Show a Stack deployment run

This endpoint gets details about a Stack deployment run.

GET /stack-deployment-runs/:stack_deployment_run_id

Parameter	Description
`:stack_deployment_run_id`	The id of the Stack deployment run to show.

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

Resource Name	Description
`stack_deployment_group`	The deployment group that contains the run.
`stack_approval`	The Stack approval created for the deployment run.
`destroy_stack_configuration`	The configuration that last referenced a deployment that has been omitted in the configuration that contains the specified run.
`blocked_by_deployment_group`	The deployment group that is blocking this run from proceeding.
`latest_deployment_run_for_deployment`	The latest deployment run for the deployment that the current run is targeting.

Sample Request

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

Sample Response

{
  "data": {
    "id": "sdr-A7Ly5aDFHUepLeF7",
    "type": "stack-deployment-runs",
    "attributes": {
      "status": "pre_deploying_pending_operator",
      "deployment": "simple",
      "created-at": "2025-09-11T15:33:25.141Z",
      "updated-at": "2025-09-11T15:33:33.390Z",
      "pre-deploying-at": "2025-09-11T15:33:25.273Z",
      "pre-deploying-pending-operator-at": "2025-09-11T15:33:33.390Z",
      "acquiring-lock-at": null,
      "deploying-at": null,
      "deploying-pending-operator-at": null,
      "succeeded-at": null,
      "failed-at": null,
      "abandoned-at": null,
      "plan-mode": "normal"
    },
    "relationships": {
      "stack-deployment-group": {
        "data": {
          "id": "sdg-LwBSiWxcrjhYBGMK",
          "type": "stack-deployment-groups"
        }
      },
      "stack-configuration": {
        "data": {
          "id": "stc-jEvHkd8DXBK594WD",
          "type": "stack-configurations"
        }
      },
      "stack-deployment-steps": {
        "links": {
          "related": "/api/v2/stack-deployment-runs/sdr-A7Ly5aDFHUepLeF7/stack-deployment-steps"
        }
      },
      "stack-approval": {
        "data": null
      },
      "current-step": {
        "data": {
          "id": "sds-qbXEc9fNpt7MNpKT",
          "type": "stack-deployment-steps"
        }
      },
      "destroy-stack-configuration": {
        "data": null
      },
      "latest-deployment-run-for-deployment": {
        "data": {
          "id": "sdr-A7Ly5aDFHUepLeF7",
          "type": "stack-deployment-runs"
        }
      },
      "blocked-by-deployment-group": {
        "data": null
      }
    },
    "links": {
      "self": "/api/v2/stack-deployment-runs/sdr-A7Ly5aDFHUepLeF7"
    }
  }
}

List Stack deployment steps

This endpoint lists Stack deployment steps for a Stack deployment run.

GET /stack-deployment-runs/:stack_deployment_run_id/stack-deployment-steps

Parameter	Description
`:stack_deployment_run_id`	The id of the Stack deployment run for which Stack deployment steps are being listed.

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 deployment steps runs 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
`stack_approval`	The approval associated with the specified step.
`stack_approval.user`	The user that created the approval for the specified step.
`stack_state`	The state that was created as the result of an apply operation from the specified step.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-runs/str-RSqektntTNJrAhCm/stack-deployment-steps

Sample Response

{
  "data": [
    {
      "id": "sds-c8qjj4urpyh1wFrU",
      "type": "stack-deployment-steps",
      "attributes": {
        "status": "pending_operator",
        "operation-type": "plan",
        "requires-state-lock": false,
        "created-at": "2025-09-10T21:22:31.577Z",
        "updated-at": "2025-09-11T17:38:13.903Z",
        "queued-at": "2025-09-10T21:22:31.606Z",
        "running-at": "2025-09-10T21:22:32.797Z",
        "pending-operator-at": "2025-09-10T21:22:39.862Z",
        "completed-at": null,
        "failed-at": null,
        "abandoned-at": null
      },
      "relationships": {
        "stack-deployment-run": {
          "data": {
            "id": "sdr-qreEJHTfJ9i3qooa",
            "type": "stack-deployment-runs"
          }
        },
        "stack-diagnostics": {
          "links": {
            "related": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU/stack-diagnostics"
          },
          "meta": {
            "count": 0
          }
        },
        "stack-approval": {
          "data": null
        }
      },
      "links": {
        "self": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU",
        "plan-description": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU/artifacts?name=plan-description",
        "structured-log": "https://app.terraform.io/_archivist/v1/object/dmF1bHQ6djE6QUFxZHhyS2xHcjA0MzVvbWhXOTVXU1gwQW1MS2hVNiszcHRLd01RZWgxT3phMmdJMWo0RC8xT1liWGZBaFFhalF2NG11R3dmdndIdnBmWWsyeWQzYnlnUW1sYjdTRm5rM1BjMlN0dVFXZWJMbmtkeWVaamMvYkhMcjZzLytvVVpJc3NtVFpJSng5MVVrTmd3eWNKM2JWd1ZNUXVUZWR3bzRHSU5qb3JzWW5FeEE0WlJlTHJySFlQMzJhMmRaSUJKMU5GYy9kQUJwOCs3M1k1WEhNa0o1VTdPK1FwRmYwVThqdkx1eklNQzVuYXphOUVBRTZzYUlERk1Pc3JXWnpwRnFYR3BGTGZleGNNSE1RVE0yTGVseFhkd3M0Ymo5ZkV4RXVZTUdrR0ZId215d2U3SllwaGFhRkUvT2VRUTVlTmZoUGp1SklxVkhTZ05IRktlVDNCeEN3UVpCUDlHRnpveUwrWTZ6aW81ZVM1YUM0QVZvV1BUMDA0WkF4VmtwTDVRclVRPQ"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-deployment-runs/sdr-qreEJHTfJ9i3qooa/stack-deployment-steps?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-deployment-runs/sdr-qreEJHTfJ9i3qooa/stack-deployment-steps?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-deployment-runs/sdr-qreEJHTfJ9i3qooa/stack-deployment-steps?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
    }
  }
}

Show a Stack deployment step

This endpoint gets details about a Stack deployment step.

GET /stack-deployment-steps/:stack_deployment_step_id

Parameter	Description
`:stack_deployment_step_id`	The id of the Stack deployment step to show.

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

Resource Name	Description
`stack_approval`	The approval associated with the specified step.
`stack_approval.user`	The user that created the approval for the specified step.
`stack_state`	The state that was created as the result of an apply operation from the specified step.

Sample Request

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

Sample Response

{
  "data": {
    "id": "sds-c8qjj4urpyh1wFrU",
    "type": "stack-deployment-steps",
    "attributes": {
      "status": "pending_operator",
      "operation-type": "plan",
      "requires-state-lock": false,
      "created-at": "2025-09-10T21:22:31.577Z",
      "updated-at": "2025-09-11T17:38:13.903Z",
      "queued-at": "2025-09-10T21:22:31.606Z",
      "running-at": "2025-09-10T21:22:32.797Z",
      "pending-operator-at": "2025-09-10T21:22:39.862Z",
      "completed-at": null,
      "failed-at": null,
      "abandoned-at": null
    },
    "relationships": {
      "stack-deployment-run": {
        "data": {
          "id": "sdr-qreEJHTfJ9i3qooa",
          "type": "stack-deployment-runs"
        }
      },
      "stack-diagnostics": {
        "links": {
          "related": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU/stack-diagnostics"
        },
        "meta": {
          "count": 0
        }
      },
      "stack-approval": {
        "data": null
      }
    },
    "links": {
      "self": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU",
      "plan-description": "/api/v2/stack-deployment-steps/sds-c8qjj4urpyh1wFrU/artifacts?name=plan-description",
      "structured-log": "https://app.terraform.io/_archivist/v1/object/dmF1bHQ6djE6dHAxbFAwTHRXK3FQRFRxWklXd2E1UG0yc1JLQ3JsNVJheUNZR2l5ak9EYy9XOHk3RmdqSGw4VEswUmJDTFBCNlEvSEgvRHhhb0FCRVBmKytCRHV4TktENEFJRytWT3dXVjdTR2ZuRkFRODdEOUtuN08vdzQvRGdEcXVmb0xINHR5QlJZRnB3L1ZmRmY3blk3Q3dub1hCUmVXMW9uZUxLUUdyZGQzUWpLS3M0S0dMMTNiN3ZGRnFrQ3NoSjVKeXE4WS9iTzd6anA2MHZkWitUZ2hEcndZcTBZK0M5dFFrQkZzWjdoTUJhdS9ja3VMb3M5OFZBa0k2WjJBSHh3T2NCRjBLdjNlRThRUDBqOStrVWYxWXQ2VllTUzUzQ1YxNUkvUUJyY09CeUFsOGtrSVlMTWdFWkErM1g4NmN4UEQ3emFHZDAwUnJOa0xyQmd3VERiRGF4ZTRiMzdNVFZkcFFFWlZBMzJOcDloOWZ3U1pTMjY0Y0M4enUwdUp6WmZUditVZjk4PQ"
    }
  }
}

List Stack deployment step diagnostics

This endpoint lists Stack deployment step diagnostics for a Stack deployment step.

GET /stack-deployment-steps/:stack_deployment_step_id/stack-diagnostics

Parameter	Description
`:stack_deployment_step_id`	The id of the Stack deployment step for which Stack deployment diagnostics are being listed.

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 deployment step diagnostics per page.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics

Sample Response

{
  "data": [
    {
      "id": "stf-PrqektntTNJrAhCm",
      "type": "stack-diagnostics",
      "attributes": {
        "severity": "warning",
        "summary": "Diagnostics reported",
        "detail": "While preparing the configuration, HCP Terraform reported 2 warnings.",
        "diags": null,
        "acknowledged": true,
        "acknowledged-at": "2025-06-11T06:13:01.082Z",
        "created-at": "2025-06-11T06:13:01.082Z"
      },
      "links": {
        "self": "/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics"
      },
      "relationships": {
       "stack-configuration": {
          "data": {
            "id": "stc-RSqektntTNJrAhCm",
            "type": "stack-configurations"
          }
        },
        "stack-deployment-step": {
          "data": {
            "id": "sds-qB6dJk7G7r7icTE8",
            "type": "stack-deployment-steps"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/stack-diagnostics?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/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
    }
  }
}

Show a Stack deployment step artifact

This endpoint returns an archivist URL for the requested artifact of a specified deployment step.

GET /stack-deployment-steps/:stack_deployment_step_id/artifacts

Parameter	Description
`:stack_deployment_step_id`	The id of the Stack deployment step for which the artifacts are requested.

Query Parameters

These are standard URL query parameters; remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`name`.	Required. The name of the particular artifact being requested. Acceptable values are `plan-description`, `plan-debug-log`, `apply-description`, and `apply-debug-log`

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/name=plan-description

Show a Stack approval

This endpoint gets details about a Stack approval.

GET /stack-approvals/:stack_approval_id

Parameter	Description
`:stack_approval_id`	The id of the Stack approval to show.

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

Resource Name	Description
`user`	The user that created the specified Stack approval.

Sample Request

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

Sample Response

{
  "data": {
    "id": "sa-6jJFPnNyEUSLLGhh",
    "type": "stack-approvals",
    "attributes": {
      "reason": null,
      "created-at": "2025-09-16T14:25:02.485Z"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "user-zqE1r5BwBu9rVLAR",
          "type": "users"
        }
      }
    }
  }
}

Approve a Stack deployment group

This endpoint creates a global approval for all runs in a Stack deployment group.

POST /stack-deployment-groups/:stack_deployment_group_id/approve-all-plans

Parameter	Description
`:stack_deployment_group_id`	The Stack deployment group id to approve.

Status	Response	Reason
204	No Content	Successfully created an approval for all plans recieved for Stack deployment Group.
404	JSON API error object	Stack deployment Group not found, or user unauthorized to perform action.

Request Body

This POST endpoint will optionally accept a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`reason`	string	""	The reason for the approval

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-groups/stg-LSqektntTNJrAhCt/approve-all-plans

Rerun a Stack deployment group

This endpoint reruns a Stack deployment group that has ended up in a failed state.

POST /stack-deployment-groups/:stack_deployment_group_id/rerun

Parameter	Description
`:stack_deployment_group_id`	The Stack deployment group id to rerun.

Status	Response	Reason
204	No Content	Successfully recieved plan for Stack deployment Group.
404	JSON API error object	Stack deployment Group not found, or user unauthorized to perform action

Query Parameters

This endpoint requires the usage of query parameters to specify which deployments within the group must be rerun

Parameter	Description
`deployments`	Required. A comma separated list specifying the names of the deployments within the group that are to be rerun.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-groups/stg-LSqektntTNJrAhCt/rerun

Approve a Stack deployment run

This endpoint approves all current and future plans associated with a Stack deployment run.

POST /stack-deployment-runs/:stack_deployment_run_id/approve-all-plans

Parameter	Description
`:stack_deployment_run_id`	The Stack deployment run id to approve.

Request Body

This POST endpoint will optionally accept a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`reason`	string	""	The reason for the approval

Query Parameters

Parameter	Description
`all_plans`	Optional. Approve all potential future plans as well.

Status	Response	Reason
204	No Content	Successfully approved all plans recieved for Stack deployment Run.
404	JSON API error object	Stack deployment Run 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-deployment-runs/sdr-LSqektntTNJrAhCt/approve-all-plans

Cancel a Stack deployment run

This endpoint cancels a Stack deployment run.

POST /stack-deployment-runs/:stack_deployment_run_id/cancel

Parameter	Description
`:stack_deployment_run_id`	The id for the deployment run to cancel.

Query Parameters

Parameter	Description
`force`	Optional. Whether or not to forcably cancel the deployment run.

Status	Response	Reason
204	No Content	Successfully receieved cancel for the Stack deployment Run.
404	JSON API error object	Stack deployment Run 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-deployment-runs/sdr-LSqektntTNJrAhCt/cancel

Advance a Stack deployment step

This endpoint advances a Stack deployment step.

POST /stack-deployment-steps/:stack_deployment_step_id/advance

Parameter	Description
`:stack_deployment_step_id`	The id for the Stack deployment step to advance.

Status	Response	Reason
204	No Content	Successfully recieved advance for Stack deployment Step.
404	JSON API error object	Stack deployment Step not found, or user unauthorized to perform action

Request Body

This POST endpoint will optionally accept a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`reason`	string	""	The reason for the advancement

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/stack-deployment-steps/sds-LSqektntTNJrAhCt/advance

Stack deployments API reference

Overview

List Stack deployments

Query Parameters

Available Related Resources

Sample Request

Sample Response

List Stack deployment groups

Query Parameters

Sample Request

Sample Response

Show a Stack deployment group by name

Sample Request

Sample Response

Show a Stack deployment group by ID

Sample Request

Sample Response

List Stack deployment runs in a configuration

Query Parameters

Available Related Resources

Sample Request

Sample Response

List Stack deployment runs in a group

Query Parameters

Available Related Resources

Sample Request

Sample Response

Show a Stack deployment run

Available Related Resources

Sample Request

Sample Response

List Stack deployment steps

Query Parameters

Available Related Resources

Sample Request

Sample Response

Show a Stack deployment step

Available Related Resources

Sample Request

Sample Response

List Stack deployment step diagnostics

Query Parameters

Sample Request

Sample Response

Show a Stack deployment step artifact

Query Parameters

Sample Request

Show a Stack approval

Available Related Resources

Sample Request

Sample Response

Approve a Stack deployment group

Request Body

Sample Request

Rerun a Stack deployment group

Query Parameters

Sample Request

Approve a Stack deployment run

Request Body

Query Parameters

Sample Request

Cancel a Stack deployment run

Query Parameters

Sample Request

Advance a Stack deployment step

Request Body

Sample Request