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.
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, Terraform Cloud 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 Terraform Cloud 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, Terraform Cloud will re-fetch the files from VCS.
errored
Terraform Cloud 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.
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.
»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
{"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"}}}
{"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"}}}
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.
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.
POST /configuration-versions/:configuration_version_id/actions/archive
Parameter
Description
configuration_version_id
The ID of the configuration version to 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 uploadedstate, 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.
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 uploadedstate.
The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available: