Configuration Versions API

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.

List Configuration Versions

GET /workspaces/:workspace_id/configuration-versions

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.

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": {}
      },
      "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

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": {}
    },
    "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

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

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

Request Body

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

Properties without a default value are required.

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"
    },
    "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

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

This endpoint notifies Terraform Cloud 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, and have no runs in progress. Otherwise, calling this endpoint will result in an error.

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

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

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

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.

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

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: