HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Terraform
Terraform Home

State versions API reference

Attributes

State version API objects represent an instance of Terraform state data, but do not directly contain the stored state. Instead, they contain information about the state, its properties, and its contents, and include one or more URLs from which the state can be downloaded.

Some of the information returned in a state version API object might be populated asynchronously by HCP Terraform. This includes resources, modules, providers, and the state version outputs associated with the state version. These values might not be immediately available after the state version is uploaded. The resources-processed property on the state version object indicates whether or not HCP Terraform has finished any necessary asynchronous processing. If you need to use these values, be sure to wait for resources-processed to become true before assuming that the values are in fact empty.

AttributeDescription
billable-rum-countCount of billable Resources Under Management (RUM). Only present for Organization members on RUM plans who have visibility to see billable RUM usage in the Usage page
hosted-json-state-download-urlA URL from which you can download the state data in a stable format appropriate for external integrations to consume. Only available if the state was created by Terraform 1.3+.
hosted-state-download-urlA URL from which you can download the raw state data, in the format used internally by Terraform.
hosted-json-state-upload-urlA URL to which you can upload state data in a stable format appropriate for external integrations to consume. You can upload JSON state content once per state version.
hosted-state-upload-urlA URL to which you can upload state data in the format used Terraform uses internally. You can upload state data once per state version.
modulesExtracted information about the Terraform modules in this state data. Populated asynchronously.
providersExtracted information about the Terraform providers used for resources in this state data. Populated asynchronously.
intermediateA boolean flag that indicates the state version is a snapshot and not yet set as the current state version for a workspace. The last intermediate state version becomes the current state version when the workspace is unlocked. Not yet supported in Terraform Enterprise.
resourcesExtracted information about the resources in this state data. Populated asynchronously.
resources-processedA Boolean flag indicating whether HCP Terraform has finished asynchronously extracting outputs, resources, and other information about this state data.
serialThe serial number of this state instance, which increases every time Terraform creates new state in the workspace.
state-versionThe version of the internal state format used for this state. Different Terraform versions read and write different format versions, but it only changes infrequently.
statusIndicates a state version's content upload status. This status can be pending, finalized or discarded.
terraform-versionThe Terraform version that created this state. Populated asynchronously.
vcs-commit-shaThe SHA of the configuration commit used in the Terraform run that produced this state. Only present if the workspace is connected to a VCS repository.
vcs-commit-urlA link to the configuration commit used in the Terraform run that produced this state. Only present if the workspace is connected to a VCS repository.

State Version Status

The state version status is found in data.attributes.status, and you can reference the following list of possible statuses. A state version created through the API or CLI will only be listed in the UI if it is has a finalized status.

StateDescription
pendingIndicates that a state version has been created but the state data is not encoded within the request. Pending state versions do not contain state data and do not appear in the UI. You cannot unlock the workspace until the latest state version is finalized.
finalizedIndicates that the state version has been successfully uploaded to HCP Terraform or that the state version was created with a valid state attribute.
discardedThe state version was discarded because it was superseded by a newer state version before it could be uploaded.
backing_data_soft_deletedEnterprise The backing files associated with this state version are marked for garbage collection. Terraform permanently deletes backing files associated with this state version after a set number of days, but you can restore the backing data associated with it before it is permanently deleted.
backing_data_permanently_deletedEnterprise The backing files associated with this state version have been permanently deleted and can no longer be restored.

Create a State Version

Hands-on: Try the Version Remote State with the HCP Terraform API tutorial to download a remote state file and use the Terraform API to create a new state version.

POST /workspaces/:workspace_id/state-versions

ParameterDescription
:workspace_idThe workspace ID to create the new state version in. Obtain this from the workspace settings or the Show Workspace endpoint.

Creates a state version and sets it as the current state version for the given workspace. The workspace must be locked by the user creating a state version. The workspace may be locked with the API or with the UI. This is most useful for migrating existing state from Terraform Community edition into a new HCP Terraform workspace.

Creating state versions requires permission to read and write state versions for the workspace. (More about permissions.)

Warning: Use caution when uploading state to workspaces that have already performed Terraform runs. Replacing state improperly can result in orphaned or duplicated infrastructure resources.

Note: For Free Tier organizations, HCP Terraform always retains at least the last 100 states (across all workspaces) and at least the most recent state for every workspace. Additional states beyond the last 100 are retained for six months, and are then deleted.

Note: You cannot access this endpoint with organization tokens. You must access it with a user token or team token.

StatusResponseReason
201JSON API documentSuccessfully created a state version.
404JSON API error objectWorkspace not found, or user unauthorized to perform action.
409JSON API error objectConflict; check the error object for more information.
412JSON API error objectPrecondition failed; check the error object for more information.
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.).

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 pathTypeDefaultDescription
data.typestringMust be "state-versions".
data.attributes.serialintegerThe serial of the state version. Must match the serial value extracted from the raw state file.
data.attributes.md5stringAn MD5 hash of the raw state version.
data.attributes.statestring(nothing)Optional Base64 encoded raw state file. If omitted, you must use the upload method below to complete the state version creation. The workspace may not be unlocked normally until the state version is uploaded.
data.attributes.lineagestring(nothing)Optional Lineage of the state version. Should match the lineage extracted from the raw state file. Early versions of terraform did not have the concept of lineage, so this is an optional attribute.
data.attributes.json-statestring(nothing)Optional Base64 encoded json state, as expressed by terraform show -json. See JSON Output Format for more details.
data.attributes.json-state-outputsstring(nothing)Optional Base64 encoded output values as represented by terraform show -json (the contents of the values/outputs key). If provided, the workspace outputs populate immediately. If omitted, HCP Terraform populates the workspace outputs from the given state after a short time.
data.relationships.run.data.idstring(nothing)Optional The ID of the run to associate with the state version.

Sample Payload

{
  "data": {
    "type":"state-versions",
    "attributes": {
      "serial": 1,
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "lineage": "871d1b4a-e579-fb7c-ffdb-f0c858a647a7",
      "state": "...",
      "json-state": "...",
      "json-state-outputs": "..."
    },
    "relationships": {
      "run": {
        "data": {
          "type": "runs",
          "id": "run-bWSq4YeYpfrW4mx7"
        }
      }
    }
  }
}

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/workspaces/ws-6fHMCom98SDXSQUv/state-versions

Sample Response

{
    "data": {
        "id": "sv-DmoXecHePnNznaA4",
        "type": "state-versions",
        "attributes": {
            "vcs-commit-sha": null,
            "vcs-commit-url": null,
            "created-at": "2018-07-12T20:32:01.490Z",
            "hosted-state-download-url": "https://archivist.terraform.io/v1/object/f55b739b-ff03-4716-b436-726466b96dc4",
            "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/4fde7951-93c0-4414-9a40-f3abc4bac490",
            "hosted-state-upload-url": null,
            "hosted-json-state-upload-url": null,
            "status": "finalized",
            "intermediate": true,
            "serial": 1
        },
        "links": {
            "self": "/api/v2/state-versions/sv-DmoXecHePnNznaA4"
        }
    }
}

Upload State and JSON State

You can upload state version content in the same request when creating a state version. However, we strongly recommend that you upload content separately.

PUT https://archivist.terraform.io/v1/object/<UNIQUE OBJECT ID>

HCP Terraform returns a hosted-state-upload-url or hosted-json-state-upload-url returned when you create a state-version. Once you upload state content, this URL is hidden on the resource and no longer available.

Sample Request

In the below example, @filename is the name of Terraform state file you wish to upload.

curl \
  --header "Content-Type: application/octet-stream" \
  --request PUT \
  --data-binary @filename \
  https://archivist.terraform.io/v1/object/4c44d964-eba7-4dd5-ad29-1ece7b99e8da

List State Versions for a Workspace

GET /state-versions

Listing state versions requires permission to read state versions for the workspace. (More about permissions.)

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.

ParameterDescription
filter[workspace][name]Required The name of one workspace to list versions for.
filter[organization][name]Required The name of the organization that owns the desired workspace.
filter[status]Optional. Filter state versions by status: pending, finalized, or discarded.
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 state versions per page.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/v2/state-versions?filter%5Bworkspace%5D%5Bname%5D=my-workspace&filter%5Borganization%5D%5Bname%5D=my-organization"

Sample Response

{
    "data": [
        {
            "id": "sv-g4rqST72reoHMM5a",
            "type": "state-versions",
            "attributes": {
                "created-at": "2021-06-08T01:22:03.794Z",
                "size": 940,
                "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...",
                "hosted-state-upload-url": null,
                "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...",
                "hosted-json-state-upload-url": null,
                "status": "finalized",
                "intermediate": false,
                "modules": {
                    "root": {
                        "null-resource": 1,
                        "data.terraform-remote-state": 1
                    }
                },
                "providers": {
                    "provider[\"terraform.io/builtin/terraform\"]": {
                        "data.terraform-remote-state": 1
                    },
                    "provider[\"registry.terraform.io/hashicorp/null\"]": {
                        "null-resource": 1
                    }
                },
                "resources": [
                    {
                        "name": "other_username",
                        "type": "data.terraform_remote_state",
                        "count": 1,
                        "module": "root",
                        "provider": "provider[\"terraform.io/builtin/terraform\"]"
                    },
                    {
                        "name": "random",
                        "type": "null_resource",
                        "count": 1,
                        "module": "root",
                        "provider": "provider[\"registry.terraform.io/hashicorp/null\"]"
                    }
                ],
                "resources-processed": true,
                "serial": 9,
                "state-version": 4,
                "terraform-version": "0.15.4",
                "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345",
                "vcs-commit-sha": "abcdef12345"
            },
            "relationships": {
                "run": {
                    "data": {
                        "id": "run-YfmFLWpgTv31VZsP",
                        "type": "runs"
                    }
                },
                "created-by": {
                    "data": {
                        "id": "user-onZs69ThPZjBK2wo",
                        "type": "users"
                    },
                    "links": {
                        "self": "/api/v2/users/user-onZs69ThPZjBK2wo",
                        "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by"
                    }
                },
                "workspace": {
                    "data": {
                        "id": "ws-noZcaGXsac6aZSJR",
                        "type": "workspaces"
                    }
                },
                "outputs": {
                    "data": [
                        {
                            "id": "wsout-V22qbeM92xb5mw9n",
                            "type": "state-version-outputs"
                        },
                        {
                            "id": "wsout-ymkuRnrNFeU5wGpV",
                            "type": "state-version-outputs"
                        },
                        {
                            "id": "wsout-v82BjkZnFEcscipg",
                            "type": "state-version-outputs"
                        }
                    ]
                }
            },
            "links": {
                "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a"
            }
        },
        {
            "id": "sv-QYKf6GvNv75ZPTBr",
            "type": "state-versions",
            "attributes": {
                "created-at": "2021-06-01T21:40:25.941Z",
                "size": 819,
                "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...",
                "hosted-state-upload-url": null,
                "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...",
                "hosted-json-state-upload-url": null,
                "status": "finalized",
                "intermediate": false,
                "modules": {
                    "root": {
                        "data.terraform-remote-state": 1
                    }
                },
                "providers": {
                    "provider[\"terraform.io/builtin/terraform\"]": {
                        "data.terraform-remote-state": 1
                    }
                },
                "resources": [
                    {
                        "name": "other_username",
                        "type": "data.terraform_remote_state",
                        "count": 1,
                        "module": "root",
                        "provider": "provider[\"terraform.io/builtin/terraform\"]"
                    }
                ],
                "resources-processed": true,
                "serial": 8,
                "state-version": 4,
                "terraform-version": "0.15.4",
                "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/12345abcdef",
                "vcs-commit-sha": "12345abcdef"
            },
            "relationships": {
                "run": {
                    "data": {
                        "id": "run-cVtxks6R8wsjCZMD",
                        "type": "runs"
                    }
                },
                "created-by": {
                    "data": {
                        "id": "user-onZs69ThPZjBK2wo",
                        "type": "users"
                    },
                    "links": {
                        "self": "/api/v2/users/user-onZs69ThPZjBK2wo",
                        "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by"
                    }
                },
                "workspace": {
                    "data": {
                        "id": "ws-noZcaGXsac6aZSJR",
                        "type": "workspaces"
                    }
                },
                "outputs": {
                    "data": [
                        {
                            "id": "wsout-MmqMhmht6jFmLRvh",
                            "type": "state-version-outputs"
                        },
                        {
                            "id": "wsout-Kuo9TCHg3oDLDQqa",
                            "type": "state-version-outputs"
                        }
                    ]
                }
            },
            "links": {
                "self": "/api/v2/state-versions/sv-QYKf6GvNv75ZPTBr"
            }
        }
    ],
    "links": {
        "self": "https://app.terraform.io/api/v2/state-versions?filter%5Borganization%5D%5Bname%5D=hashicorp&filter%5Bworkspace%5D%5Bname%5D=my-workspace&page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "first": "https://app.terraform.io/api/v2/state-versions?filter%5Borganization%5D%5Bname%5D=hashicorp&filter%5Bworkspace%5D%5Bname%5D=my-workspace&page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "prev": null,
        "next": null,
        "last": "https://app.terraform.io.io/api/v2/state-versions?filter%5Borganization%5D%5Bname%5D=hashicorp&filter%5Bworkspace%5D%5Bname%5D=my-workspace&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": 10
        }
    }
}

Fetch the Current State Version for a Workspace

GET /workspaces/:workspace_id/current-state-version

ParameterDescription
:workspace_idThe ID for the workspace whose current state version you want to fetch. Obtain this from the workspace settings or the Show Workspace endpoint.

Fetches the current state version for the given workspace. This state version will be the input state when running terraform operations.

Viewing state versions requires permission to read state versions for the workspace. (More about permissions.)

StatusResponseReason
200JSON API documentSuccessfully returned current state version for the given workspace.
404JSON API error objectWorkspace not found, workspace does not have a current state version, 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/workspaces/ws-6fHMCom98SDXSQUv/current-state-version

Sample Response

{
    "data": {
        "id": "sv-g4rqST72reoHMM5a",
        "type": "state-versions",
        "attributes": {
            "billable-rum-count": 0,
            "created-at": "2021-06-08T01:22:03.794Z",
            "size": 940,
            "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-state-upload-url": null,
            "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-json-state-upload-url": null,
            "status": "finalized",
            "intermediate": false,
            "modules": {
                "root": {
                    "null-resource": 1,
                    "data.terraform-remote-state": 1
                }
            },
            "providers": {
                "provider[\"terraform.io/builtin/terraform\"]": {
                    "data.terraform-remote-state": 1
                },
                "provider[\"registry.terraform.io/hashicorp/null\"]": {
                    "null-resource": 1
                }
            },
            "resources": [
                {
                    "name": "other_username",
                    "type": "data.terraform_remote_state",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"terraform.io/builtin/terraform\"]"
                },
                {
                    "name": "random",
                    "type": "null_resource",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"registry.terraform.io/hashicorp/null\"]"
                }
            ],
            "resources-processed": true,
            "serial": 9,
            "state-version": 4,
            "terraform-version": "0.15.4",
            "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345",
            "vcs-commit-sha": "abcdef12345"
        },
        "relationships": {
            "run": {
                "data": {
                    "id": "run-YfmFLWpgTv31VZsP",
                    "type": "runs"
                }
            },
            "created-by": {
                "data": {
                    "id": "user-onZs69ThPZjBK2wo",
                    "type": "users"
                },
                "links": {
                    "self": "/api/v2/users/user-onZs69ThPZjBK2wo",
                    "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by"
                }
            },
            "workspace": {
                "data": {
                    "id": "ws-noZcaGXsac6aZSJR",
                    "type": "workspaces"
                }
            },
            "outputs": {
                "data": [
                    {
                        "id": "wsout-V22qbeM92xb5mw9n",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-ymkuRnrNFeU5wGpV",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-v82BjkZnFEcscipg",
                        "type": "state-version-outputs"
                    }
                ]
            }
        },
        "links": {
            "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a"
        }
    }
}

Show a State Version

GET /state-versions/:state_version_id

Viewing state versions requires permission to read state versions for the workspace. (More about permissions.)

ParameterDescription
:state_version_idThe ID of the desired state version.
StatusResponseReason
200JSON API documentSuccessfully returned current state version for the given workspace.
404JSON API error objectWorkspace not found, workspace does not have a current state version, 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/state-versions/sv-SDboVZC8TCxXEneJ

Sample Response

{
    "data": {
        "id": "sv-g4rqST72reoHMM5a",
        "type": "state-versions",
        "attributes": {
            "created-at": "2021-06-08T01:22:03.794Z",
            "size": 940,
            "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-state-upload-url": null,
            "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-json-state-upload-url": null,
            "status": "finalized",
            "intermediate": false,
            "modules": {
                "root": {
                    "null-resource": 1,
                    "data.terraform-remote-state": 1
                }
            },
            "providers": {
                "provider[\"terraform.io/builtin/terraform\"]": {
                    "data.terraform-remote-state": 1
                },
                "provider[\"registry.terraform.io/hashicorp/null\"]": {
                    "null-resource": 1
                }
            },
            "resources": [
                {
                    "name": "other_username",
                    "type": "data.terraform_remote_state",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"terraform.io/builtin/terraform\"]"
                },
                {
                    "name": "random",
                    "type": "null_resource",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"registry.terraform.io/hashicorp/null\"]"
                }
            ],
            "resources-processed": true,
            "serial": 9,
            "state-version": 4,
            "terraform-version": "0.15.4",
            "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345",
            "vcs-commit-sha": "abcdef12345"
        },
        "relationships": {
            "run": {
                "data": {
                    "id": "run-YfmFLWpgTv31VZsP",
                    "type": "runs"
                }
            },
            "created-by": {
                "data": {
                    "id": "user-onZs69ThPZjBK2wo",
                    "type": "users"
                },
                "links": {
                    "self": "/api/v2/users/user-onZs69ThPZjBK2wo",
                    "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by"
                }
            },
            "workspace": {
                "data": {
                    "id": "ws-noZcaGXsac6aZSJR",
                    "type": "workspaces"
                }
            },
            "outputs": {
                "data": [
                    {
                        "id": "wsout-V22qbeM92xb5mw9n",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-ymkuRnrNFeU5wGpV",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-v82BjkZnFEcscipg",
                        "type": "state-version-outputs"
                    }
                ]
            }
        },
        "links": {
            "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a"
        }
    }
}

Rollback to a Previous State Version

PATCH /workspaces/:workspace_id/state-versions

ParameterDescription
:workspace_idThe workspace ID to create the new state version in. Obtain this from the workspace settings or the Show Workspace endpoint.

Creates a state version by duplicating the specified state version and sets it as the current state version for the given workspace. The workspace must be locked by the user creating a state version. The workspace may be locked with the API or with the UI. This is most useful for rolling back to a known-good state after an operation such as a Terraform upgrade didn't go as planned.

Creating state versions requires permission to read and write state versions for the workspace. (More about permissions.)

Warning: Use caution when rolling back to a previous state. Replacing state improperly can result in orphaned or duplicated infrastructure resources.

Note: You cannot access this endpoint with organization tokens. You must access it with a user token or team token.

StatusResponseReason
201JSON API documentSuccessfully rolled back.
404JSON API error objectWorkspace not found, or user unauthorized to perform action.
409JSON API error objectConflict; check the error object for more information.
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.).

Request Body

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

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringMust be "state-versions".
data.relationships.rollback-state-version.data.idstringThe ID of the state version to use for the rollback operation.

Sample Payload

{
  "data": {
    "type":"state-versions",
    "relationships": {
      "rollback-state-version": {
        "data": {
          "type": "state-versions",
          "id": "sv-bWfq4Y1YpRKW4mx7"
        }
      }
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/workspaces/ws-6fHMCom98SDXSQUv/state-versions

Sample Response

{
    "data": {
        "id": "sv-DmoXecHePnNznaA4",
        "type": "state-versions",
        "attributes": {
            "created-at": "2022-11-22T01:22:03.794Z",
            "size": 940,
            "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-state-upload-url": null,
            "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-json-state-upload-url": null,
            "modules": {
                "root": {
                    "null-resource": 1,
                    "data.terraform-remote-state": 1
                }
            },
            "providers": {
                "provider[\"terraform.io/builtin/terraform\"]": {
                    "data.terraform-remote-state": 1
                },
                "provider[\"registry.terraform.io/hashicorp/null\"]": {
                    "null-resource": 1
                }
            },
            "resources": [
                {
                    "name": "other_username",
                    "type": "data.terraform_remote_state",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"terraform.io/builtin/terraform\"]"
                },
                {
                    "name": "random",
                    "type": "null_resource",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"registry.terraform.io/hashicorp/null\"]"
                }
            ],
            "resources-processed": true,
            "serial": 9,
            "state-version": 4,
            "terraform-version": "1.3.5"
        },
        "relationships": {
            "rollback-state-version": {
                "data": {
                    "id": "sv-YfmFLgTv31VZsP",
                    "type": "state-versions"
                }
            }
        },
        "links": {
            "self": "/api/v2/state-versions/sv-DmoXecHePnNznaA4"
        }
    }
}

Mark a State Version for Garbage Collection

Enterprise

This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise.

POST /api/v2/state-versions/:state_version_id/actions/soft_delete_backing_data

This endpoint directs Terraform Enterprise to soft delete the backing files associated with this state version. Soft deletion marks the state version for garbage collection. Terraform permanently deletes state versions after a set number of days unless the state version is restored. Once a state version is soft deleted, any attempts to read the state version will fail. Refer to State Version Status for information about all data states.

This endpoint can only soft delete state versions that are in an finalized state and are not the current state version. Otherwise, calling this endpoint results in an error.

You must have organization owner permissions to soft delete state versions. Refer to Permissions for additional information about permissions.

ParameterDescription
:state_version_idThe ID of the state version to mark for garbage collection.
StatusResponseReason
200JSON API documentTerraform successfully marked the data for garbage collection.
400JSON API error objectTerraform failed to transition the state to backing_data_soft_deleted.
404JSON API error objectTerraform did not find the state version or the user is not authorized to modify the state version.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/state-versions/sv-ntv3HbhJqvFzamy7/actions/soft_delete_backing_data
  --data {"data": {"attributes": {"delete-older-than-n-days": 23}}}

Sample Response

{
    "data": {
        "id": "sv-g4rqST72reoHMM5a",
        "type": "state-versions",
        "attributes": {
            "created-at": "2021-06-08T01:22:03.794Z",
            "size": 940,
            "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-state-upload-url": null,
            "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-json-state-upload-url": null,
            "status": "backing_data_soft_deleted",
            "intermediate": false,
            "delete-older-than-n-days": 23,
            "modules": {
                "root": {
                    "null-resource": 1,
                    "data.terraform-remote-state": 1
                }
            },
            "providers": {
                "provider[\"terraform.io/builtin/terraform\"]": {
                    "data.terraform-remote-state": 1
                },
                "provider[\"registry.terraform.io/hashicorp/null\"]": {
                    "null-resource": 1
                }
            },
            "resources": [
                {
                    "name": "other_username",
                    "type": "data.terraform_remote_state",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"terraform.io/builtin/terraform\"]"
                },
                {
                    "name": "random",
                    "type": "null_resource",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"registry.terraform.io/hashicorp/null\"]"
                }
            ],
            "resources-processed": true,
            "serial": 9,
            "state-version": 4,
            "terraform-version": "0.15.4",
            "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345",
            "vcs-commit-sha": "abcdef12345"
        },
        "relationships": {
            "run": {
                "data": {
                    "id": "run-YfmFLWpgTv31VZsP",
                    "type": "runs"
                }
            },
            "created-by": {
                "data": {
                    "id": "user-onZs69ThPZjBK2wo",
                    "type": "users"
                },
                "links": {
                    "self": "/api/v2/users/user-onZs69ThPZjBK2wo",
                    "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by"
                }
            },
            "workspace": {
                "data": {
                    "id": "ws-noZcaGXsac6aZSJR",
                    "type": "workspaces"
                }
            },
            "outputs": {
                "data": [
                    {
                        "id": "wsout-V22qbeM92xb5mw9n",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-ymkuRnrNFeU5wGpV",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-v82BjkZnFEcscipg",
                        "type": "state-version-outputs"
                    }
                ]
            }
        },
        "links": {
            "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a"
        }
    }
}

Restore a State Version Marked for Garbage Collection

Enterprise

This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise.

POST /api/v2/state-versions/:state_version_id/actions/restore_backing_data

This endpoint directs Terraform Enterprise to restore backing files associated with this state version. This endpoint can only restore state versions that are not in a backing_data_permanently_deleted state. Terraform restores applicable state versions back to their finalized state. Otherwise, calling this endpoint results in an error.

You must have organization owner permissions to restore state versions. Refer to Permissions for additional information about permissions.

ParameterDescription
:state_version_idThe ID of the state version to restore.
StatusResponseReason
200JSON API documentTerraform successfully initiated the restore process.
400JSON API error objectTerraform failed to transition the state to finalized.
404JSON API error objectTerraform did not find the state version or the user is not authorized to modify the state version.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/state-versions/sv-ntv3HbhJqvFzamy7/actions/restore_backing_data

Sample Response

{
    "data": {
        "id": "sv-g4rqST72reoHMM5a",
        "type": "state-versions",
        "attributes": {
            "created-at": "2021-06-08T01:22:03.794Z",
            "size": 940,
            "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-state-upload-url": null,
            "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-json-state-upload-url": null,
            "status": "uploaded",
            "intermediate": false,
            "modules": {
                "root": {
                    "null-resource": 1,
                    "data.terraform-remote-state": 1
                }
            },
            "providers": {
                "provider[\"terraform.io/builtin/terraform\"]": {
                    "data.terraform-remote-state": 1
                },
                "provider[\"registry.terraform.io/hashicorp/null\"]": {
                    "null-resource": 1
                }
            },
            "resources": [
                {
                    "name": "other_username",
                    "type": "data.terraform_remote_state",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"terraform.io/builtin/terraform\"]"
                },
                {
                    "name": "random",
                    "type": "null_resource",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"registry.terraform.io/hashicorp/null\"]"
                }
            ],
            "resources-processed": true,
            "serial": 9,
            "state-version": 4,
            "terraform-version": "0.15.4",
            "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345",
            "vcs-commit-sha": "abcdef12345"
        },
        "relationships": {
            "run": {
                "data": {
                    "id": "run-YfmFLWpgTv31VZsP",
                    "type": "runs"
                }
            },
            "created-by": {
                "data": {
                    "id": "user-onZs69ThPZjBK2wo",
                    "type": "users"
                },
                "links": {
                    "self": "/api/v2/users/user-onZs69ThPZjBK2wo",
                    "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by"
                }
            },
            "workspace": {
                "data": {
                    "id": "ws-noZcaGXsac6aZSJR",
                    "type": "workspaces"
                }
            },
            "outputs": {
                "data": [
                    {
                        "id": "wsout-V22qbeM92xb5mw9n",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-ymkuRnrNFeU5wGpV",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-v82BjkZnFEcscipg",
                        "type": "state-version-outputs"
                    }
                ]
            }
        },
        "links": {
            "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a"
        }
    }
}

Permanently Delete a State Version

Enterprise

This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise.

POST /api/v2/state-versions/:state_version_id/actions/permanently_delete_backing_data

This endpoint directs Terraform Enterprise to permanently delete backing files associated with this state version. This endpoint can only permanently delete state versions that are in an backing_data_soft_deleted state and are not the current state version. Otherwise, calling this endpoint results in an error.

You must have organization owner permissions to permanently delete state versions. Refer to Permissions for additional information about permissions.

ParameterDescription
:state_version_idThe ID of the state version to permanently delete.
StatusResponseReason
200JSON API documentTerraform deleted the data permanently.
400JSON API error objectTerraform failed to transition the state to backing_data_permanently_deleted.
404JSON API error objectTerraform did not find the state version or the user is not authorized to modify the state version data.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/state-versions/sv-ntv3HbhJqvFzamy7/actions/permanently_delete_backing_data

Sample Response

{
    "data": {
        "id": "sv-g4rqST72reoHMM5a",
        "type": "state-versions",
        "attributes": {
            "created-at": "2021-06-08T01:22:03.794Z",
            "size": 940,
            "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-state-upload-url": null,
            "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...",
            "hosted-json-state-upload-url": null,
            "status": "backing_data_permanently_deleted",
            "intermediate": false,
            "modules": {
                "root": {
                    "null-resource": 1,
                    "data.terraform-remote-state": 1
                }
            },
            "providers": {
                "provider[\"terraform.io/builtin/terraform\"]": {
                    "data.terraform-remote-state": 1
                },
                "provider[\"registry.terraform.io/hashicorp/null\"]": {
                    "null-resource": 1
                }
            },
            "resources": [
                {
                    "name": "other_username",
                    "type": "data.terraform_remote_state",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"terraform.io/builtin/terraform\"]"
                },
                {
                    "name": "random",
                    "type": "null_resource",
                    "count": 1,
                    "module": "root",
                    "provider": "provider[\"registry.terraform.io/hashicorp/null\"]"
                }
            ],
            "resources-processed": true,
            "serial": 9,
            "state-version": 4,
            "terraform-version": "0.15.4",
            "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345",
            "vcs-commit-sha": "abcdef12345"
        },
        "relationships": {
            "run": {
                "data": {
                    "id": "run-YfmFLWpgTv31VZsP",
                    "type": "runs"
                }
            },
            "created-by": {
                "data": {
                    "id": "user-onZs69ThPZjBK2wo",
                    "type": "users"
                },
                "links": {
                    "self": "/api/v2/users/user-onZs69ThPZjBK2wo",
                    "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by"
                }
            },
            "workspace": {
                "data": {
                    "id": "ws-noZcaGXsac6aZSJR",
                    "type": "workspaces"
                }
            },
            "outputs": {
                "data": [
                    {
                        "id": "wsout-V22qbeM92xb5mw9n",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-ymkuRnrNFeU5wGpV",
                        "type": "state-version-outputs"
                    },
                    {
                        "id": "wsout-v82BjkZnFEcscipg",
                        "type": "state-version-outputs"
                    }
                ]
            }
        },
        "links": {
            "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a"
        }
    }
}

List State Version Outputs

The output values from a state version are also available via the API. For details, see the state version outputs documentation.

Available Related Resources

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

  • created_by - The user that created the state version. For state versions created via a run executed by HCP Terraform, this is an internal user account.
  • run - The run that created the state version, if applicable.
  • run.created_by - The user that manually triggered the run, if applicable.
  • run.configuration_version - The configuration version used in the run.
  • outputs - The parsed outputs for this state version.
Edit this page on GitHub