page_title	description
Configuration Versions - API Docs - HCP Terraform	Use the `/configuration-versions` endpoint to manage configuration versions for a workspace. List, show, and create configuration versions and their files using the HTTP API.

Configuration Versions API

-> Note: Before working with the runs or configuration versions APIs, read the API-driven run workflow page, which includes both a full overview of this workflow and a walkthrough of a simple implementation of it.

A configuration version (configuration-version) is a resource used to reference the uploaded configuration files. It is associated with the run to use the uploaded configuration files for performing the plan and apply.

You need read runs permission to list and view configuration versions for a workspace, and you need queue plans permission to create new configuration versions. Refer to the permissions documentation for more details.

Attributes

Configuration Version States

The configuration version state is found in data.attributes.status, and you can reference the following list of possible states.

A configuration version created through the API or CLI can only be used in runs if it is in an uploaded state. A configuration version created through a linked VCS repository may also be used in runs if it is in an archived state.

State	Description
`pending`	The initial status of a configuration version after it has been created. Pending configuration versions cannot be used to create new runs.
`fetching`	For configuration versions created from a commit to a connected VCS repository, HCP Terraform is currently fetching the associated files from VCS.
`uploaded`	The configuration version is fully processed and can be used in runs.
`archived`	All immediate runs are complete and HCP Terraform has discarded the files associated with this configuration version. If the configuration version was created through a connected VCS repository, it can still be used in new runs. In those cases, HCP Terraform will re-fetch the files from VCS.
`errored`	HCP Terraform could not process this configuration version, and it cannot be used to create new runs. You can try again by pushing a new commit to your linked VCS repository or creating a new configuration version with the API or CLI.
`backing_data_soft_deleted`	Indicates that the configuration version's backing data is marked for garbage collection. If no action is taken, the backing data associated with this configuration version is permanently deleted after a set number of days. You can restore the backing data associated with the configuration version before it is permanently deleted.
`backing_data_permanently_deleted`	The configuration version's backing data has been permanently deleted and can no longer be restored.

List Configuration Versions

GET /workspaces/:workspace_id/configuration-versions

Parameter	Description
`:workspace_id`	The ID of the workspace to list configurations from. Obtain this from the workspace settings or the Show Workspace endpoint.

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 configuration versions per page.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/workspaces/ws-2Qhk7LHgbMrm3grF/configuration-versions

Sample Response

{
  "data": [
    {
      "id": "cv-ntv3HbhJqvFzamy7",
      "type": "configuration-versions",
      "attributes": {
        "error": null,
        "error-message": null,
        "source": "gitlab",
        "speculative":false,
        "status": "uploaded",
        "status-timestamps": {},
        "provisional": false
      },
      "relationships": {
        "ingress-attributes": {
          "data": {
            "id": "ia-i4MrTxmQXYxH2nYD",
            "type": "ingress-attributes"
          },
          "links": {
            "related":
              "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/ingress-attributes"
          }
        }
      },
      "links": {
        "self": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7",
        "download": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download"
      }
    }
  ]
}

Show a Configuration Version

GET /configuration-versions/:configuration-id

Parameter	Description
`:configuration-id`	The id of the configuration to show.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7

Sample Response

{
  "data": {
    "id": "cv-ntv3HbhJqvFzamy7",
    "type": "configuration-versions",
    "attributes": {
      "error": null,
      "error-message": null,
      "source": "gitlab",
      "speculative":false,
      "status": "uploaded",
      "status-timestamps": {},
      "provisional": false
    },
    "relationships": {
      "ingress-attributes": {
        "data": {
          "id": "ia-i4MrTxmQXYxH2nYD",
          "type": "ingress-attributes"
        },
        "links": {
          "related":
            "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/ingress-attributes"
        }
      }
    },
    "links": {
      "self": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7",
      "download": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download"
    }
  }
}

Show a Configuration Version's Commit Information

An ingress attributes resource (ingress-attributes) is used to reference commit information for configuration versions created in a workspace with a VCS repository.

GET /configuration-versions/:configuration-id/ingress-attributes

Parameter	Description
`:configuration-id`	The id of the configuration to show.

Ingress attributes can also be fetched as part of a query to a particular configuration version via include:

GET /configuration-versions/:configuration-id?include=ingress-attributes

Parameter	Description
`:configuration-id`	The id of the configuration to show.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/configuration-versions/cv-TrHjxIzad9Ae9i8x/ingress-attributes

Sample Response

{
  "data": {
    "id": "ia-zqHjxJzaB9Ae6i9t",
    "type": "ingress-attributes",
    "attributes": {
      "branch": "add-cool-stuff",
      "clone-url": "https://github.com/hashicorp/foobar.git",
      "commit-message": "Adding really cool infrastructure",
      "commit-sha": "1e1c1018d1bbc0b8517d072718e0d87c1a0eda95",
      "commit-url": "https://github.com/hashicorp/foobar/commit/1e1c1018d1bbc0b8517d072718e0d87c1a0eda95",
      "compare-url": "https://github.com/hashicorp/foobar/pull/163",
      "identifier": "hashicorp/foobar",
      "is-pull-request": true,
      "on-default-branch": false,
      "pull-request-number": 163,
      "pull-request-url": "https://github.com/hashicorp/foobar/pull/163",
      "pull-request-title": "Adding really cool infrastructure",
      "pull-request-body": "These are changes to add really cool stuff. We should absolutely merge this.",
      "tag": null,
      "sender-username": "chrisarcand",
      "sender-avatar-url": "https://avatars.githubusercontent.com/u/2430490?v=4",
      "sender-html-url": "https://github.com/chrisarcand"
    },
    "relationships": {
      "created-by": {
        "data": {
          "id": "user-PQk2Z3dfXAax18P6s",
          "type": "users"
        },
        "links": {
          "related": "/api/v2/ingress-attributes/ia-zqHjxJzaB9Ae6i9t/created-by"
        }
      }
    },
    "links": {
      "self": "/api/v2/ingress-attributes/ia-zqHjxJzaB9Ae6i9t"
    }
  }
}

Create a Configuration Version

POST /workspaces/:workspace_id/configuration-versions

Parameter	Description
`:workspace_id`	The ID of the workspace to create the new configuration version in. Obtain this from the workspace settings or the Show Workspace endpoint.

-> Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

Request Body

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

Properties without a default value are required.

Key path	Type	Default	Description
`data.attributes.auto-queue-runs`	boolean	true	When true, runs are queued automatically when the configuration version is uploaded.
`data.attributes.speculative`	boolean	false	When true, this configuration version may only be used to create runs which are speculative, that is, can neither be confirmed nor applied.
`data.attributes.provisional`	boolean	false	When true, this configuration version does not immediately become the workspace current configuration version. If the associated run is applied, it then becomes the current configuration version unless a newer one exists.

Sample Payload

{
  "data": {
    "type": "configuration-versions",
    "attributes": {
      "auto-queue-runs": true
    }
  }
}

Sample Request

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

Sample Response

{
  "data": {
    "id": "cv-UYwHEakurukz85nW",
    "type": "configuration-versions",
    "attributes": {
      "auto-queue-runs": true,
      "error": null,
      "error-message": null,
      "source": "tfe-api",
      "speculative":false,
      "status": "pending",
      "status-timestamps": {},
      "upload-url":
        "https://archivist.terraform.io/v1/object/9224c6b3-2e14-4cd7-adff-ed484d7294c2",
      "provisional": false
    },
    "relationships": {
      "ingress-attributes": {
        "data": null,
        "links": {
          "related":
            "/api/v2/configuration-versions/cv-UYwHEakurukz85nW/ingress-attributes"
        }
      }
    },
    "links": { "self": "/api/v2/configuration-versions/cv-UYwHEakurukz85nW" }
  }
}

Configuration Files Upload URL

Once a configuration version is created, use the upload-url attribute to upload configuration files associated with that version. The upload-url attribute is only provided in the response when creating configuration versions.

Upload Configuration Files

-> Note: If auto-queue-runs was either not provided or set to true during creation of the configuration version, a run using this configuration version will be automatically queued on the workspace. If auto-queue-runs was set to false explicitly, then it is necessary to create a run on the workspace manually after the configuration version is uploaded.

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

The URL is provided in the upload-url attribute when creating a configuration-versions resource. After creation, the URL is hidden on the resource and no longer available.

Sample Request

@filename is the name of configuration 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

Archive a Configuration Version

POST /configuration-versions/:configuration_version_id/actions/archive

Parameter	Description
`configuration_version_id`	The ID of the configuration version to archive.

This endpoint notifies HCP Terraform to discard the uploaded .tar.gz file associated with this configuration version. This endpoint can only archive configuration versions that were created with the API or CLI, are in an uploaded state, have no runs in progress, and are not the current configuration version for any workspace. Otherwise, calling this endpoint will result in an error.

HCP Terraform automatically archives configuration versions created through VCS when associated runs are complete and then re-fetches the files for subsequent runs.

Status	Response	Reason(s)
202	none	Successfully initiated the archive process.
409	JSON API error object	Configuration version was in a non-archivable state or the configuration version was created with VCS and cannot be archived through the API.
404	JSON API error object	Configuration version was not found or user not authorized.

Request Body

This POST endpoint does not take a request body.

Sample Request

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

Download Configuration Files

GET /configuration-versions/:configuration_version_id/download

Parameter	Description
`configuration_version_id`	The ID of the configuration version to download.

GET /runs/:run_id/configuration-version/download

Parameter	Description
`run_id`	The ID of the run whose configuration version should be downloaded.

These endpoints generate a temporary URL to the location of the configuration version in a .tar.gz archive, and then redirect to that link. If using a client that can follow redirects, you can use these endpoints to save the .tar.gz archive locally without needing to save the temporary URL. These endpoints will return an error if attempting to download a configuration version that is not in an uploaded state.

Status	Response	Reason
302	HTTP Redirect	Configuration version found and temporary download URL generated
404	JSON API error object	Configuration version not found, or specified configuration version is not uploaded, or user unauthorized to perform action

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --location \
  https://app.terraform.io/api/v2/configuration-versions/cv-C6Py6WQ1cUXQX2x2/download \
  > export.tar.gz

Mark a Configuration Version for Garbage Collection

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

POST /api/v2/configuration-versions/:configuration-id/actions/soft_delete_backing_data

Parameter	Description
`:configuration-id`	The ID of the configuration version to soft delete.

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

This endpoint can only soft delete configuration versions that meet the following criteria:

Were created using the API or CLI,
are in an uploaded state,
and are not the current configuration version.

Otherwise, the endpoint returns an error.

Status	Response	Reason(s)
200	none	Terraform successfully marked the data for garbage collection.
400	JSON API error object	Terraform failed to transition the state to `backing_data_soft_deleted`.
404	JSON API error object	Terraform did not find the configuration version or the user is not authorized to modify the configuration version state.

Request Body

This POST endpoint does not take a request body.

Sample Request

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

Restore Configuration Versions Marked for Garbage Collection

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

POST /api/v2/configuration-versions/:configuration-id/actions/restore_backing_data

Parameter	Description
`:configuration-id`	The ID of the configuration version to restore back to its uploaded state if applicable.

This endpoint directs Terraform Enterprise to restore backing files associated with this configuration version. This endpoint can only restore delete configuration versions that meet the following criteria:

are not in a backing_data_permanently_deleted state.

Otherwise, the endpoint returns an error. Terraform restores applicable configuration versions back to their uploaded state.

Status	Response	Reason(s)
200	none	Terraform successfully initiated the restore process.
400	JSON API error object	Terraform failed to transition the state to `uploaded`.
404	JSON API error object	Terraform did not find the configuration version or the user is not authorized to modify the configuration version state.

Request Body

This POST endpoint does not take a request body.

Sample Request

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

Permanently Delete a Configuration Version

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

POST /api/v2/configuration-versions/:configuration-id/actions/permanently_delete_backing_data

Parameter	Description
`:configuration-id`	The ID of the configuration version to permanently delete.

This endpoint directs Terraform Enterprise to permanently delete backing files associated with this configuration version. This endpoint can only permanently delete configuration versions that meet the following criteria:

Were created using the API or CLI,
are in a backing_data_soft_deleted state,
and are not the current configuration version.

Otherwise, the endpoint returns an error.

Status	Response	Reason(s)
200	none	Terraform successfully deleted the data permanently.
400	JSON API error object	Terraform failed to transition the state to `backing_data_permanently_deleted`.
404	JSON API error object	Terraform did not find the configuration version or the user is not authorized to modify the configuration version state.

Request Body

This POST endpoint does not take a request body.

Sample Request

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

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:

Resource Name	Description
`ingress_attributes`	The commit information used in the configuration.
`run`	The run created by the configuration.

Files

configuration-versions.mdx

Latest commit

History

configuration-versions.mdx

File metadata and controls

Configuration Versions API

Attributes

Configuration Version States

List Configuration Versions

Query Parameters

Sample Request

Sample Response

Show a Configuration Version

Sample Request

Sample Response

Show a Configuration Version's Commit Information

Sample Request

Sample Response

Create a Configuration Version

Request Body

Sample Payload

Sample Request

Sample Response

Configuration Files Upload URL

Upload Configuration Files

Sample Request

Archive a Configuration Version

Request Body

Sample Request

Download Configuration Files

Sample Request

Mark a Configuration Version for Garbage Collection

Request Body

Sample Request

Restore Configuration Versions Marked for Garbage Collection

Request Body

Sample Request

Permanently Delete a Configuration Version

Request Body

Sample Request

Available Related Resources