Type '/' to Search

»Admin Terraform Versions API

Terraform Enterprise feature: The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance.

These API endpoints are available in Terraform Enterprise as of version 201807-1.

The Terraform Versions Admin API lets site administrators manage which versions of Terraform are available to the Terraform Cloud users within their enterprise.

»List all Terraform versions

GET /api/v2/admin/terraform-versions

This endpoint lists all known versions of Terraform.

StatusResponseReason
200JSON API document (type: "terraform-versions")Successfully listed Terraform versions
404JSON API error objectClient is not an administrator.

»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[version]Optional. A query string. This will find an exact Terraform version matching the version queried. This option takes precedence over search queries. This option is available in Terraform Enterprise v202201-2 or later.
search[version]Optional. A search query string. This will search for Terraform versions matching the version number queried. This option is available in Terraform Enterprise v202201-2 or later.
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 Terraform versions per page.

»Sample Request

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

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

»Sample Response

{
  "data": [
    {
      "id": "tool-L4oe7rNwn7J4E5Yr",
      "type": "terraform-versions",
      "attributes": {
        "version": "0.11.8",
        "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",
        "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",
        "deprecated": false,
        "deprecated-reason": null,
        "official": true,
        "enabled": true,
        "beta": false,
        "usage": 0,
        "created-at": "2018-08-15T22:34:24.561Z"
      }
    },
    {
      "id": "tool-qcbYn12vuRKPgPpy",
      "type": "terraform-versions",
      "attributes": {
        "version": "0.11.7",
        "url": "https://releases.hashicorp.com/terraform/0.11.7/terraform_0.11.7_linux_amd64.zip",
        "sha": "6b8ce67647a59b2a3f70199c304abca0ddec0e49fd060944c26f666298e23418",
        "deprecated": false,
        "deprecated-reason": null,
        "official": true,
        "enabled": true,
        "beta": false,
        "usage": 2,
        "created-at": null
      }
    }
  ],
  "links": {
    "self": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "last": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=4&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": 2,
      "total-pages": 4,
      "total-count": 70
    }
  }
}

{  "data": [    {      "id": "tool-L4oe7rNwn7J4E5Yr",      "type": "terraform-versions",      "attributes": {        "version": "0.11.8",        "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",        "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",        "deprecated": false,        "deprecated-reason": null,        "official": true,        "enabled": true,        "beta": false,        "usage": 0,        "created-at": "2018-08-15T22:34:24.561Z"      }    },    {      "id": "tool-qcbYn12vuRKPgPpy",      "type": "terraform-versions",      "attributes": {        "version": "0.11.7",        "url": "https://releases.hashicorp.com/terraform/0.11.7/terraform_0.11.7_linux_amd64.zip",        "sha": "6b8ce67647a59b2a3f70199c304abca0ddec0e49fd060944c26f666298e23418",        "deprecated": false,        "deprecated-reason": null,        "official": true,        "enabled": true,        "beta": false,        "usage": 2,        "created-at": null      }    }  ],  "links": {    "self": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "first": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "prev": null,    "next": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=2&page%5Bsize%5D=20",    "last": "https://tfe.example.com/api/v2/admin/terraform-versions?page%5Bnumber%5D=4&page%5Bsize%5D=20"  },  "meta": {    "pagination": {      "current-page": 1,      "prev-page": null,      "next-page": 2,      "total-pages": 4,      "total-count": 70    }  }}

»Create a Terraform version

POST /admin/terraform-versions

StatusResponseReason
201JSON API document (type: "terraform-versions")The Terraform version was successfully created
404JSON API error objectClient is not an administrator
422JSON API error objectValidation errors

»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 "terraform-versions"
data.attributes.versionstringA semantic version string in N.N.N or N.N.N-bundleName format (e.g. "0.11.0", "0.12.20-beta1".)
data.attributes.urlstringThe URL where a ZIP-compressed 64-bit Linux binary of this version can be downloaded
data.attributes.shastringThe SHA-256 checksum of the compressed Terraform binary
data.attributes.deprecatedboolfalseWhether or not this version of Terraform is deprecated
data.attributes.deprecated-reasonstringnullAdditional context about why a version of Terraform is deprecated. Field is null unless deprecated is true.
data.attributes.officialboolfalseWhether or not this is an official release of Terraform
data.attributes.enabledbooltrueWhether or not this version of Terraform is enabled for use in Terraform Cloud
data.attributes.betaboolfalseWhether or not this version of Terraform is a beta pre-release

»Sample Payload

{
  "data": {
    "type": "terraform-versions",
    "attributes": {
      "version": "0.11.8",
      "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",
      "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",
      "official": true,
      "enabled": true,
      "beta": false
    }
  }
}

{  "data": {    "type": "terraform-versions",    "attributes": {      "version": "0.11.8",      "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",      "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",      "official": true,      "enabled": true,      "beta": false    }  }}

»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/admin/terraform-versions

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

»Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "terraform-versions",
    "attributes": {
      "version": "0.11.8",
      "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",
      "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",
      "official": true,
      "deprecated": false,
      "deprecated-reason": null,
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2018-08-15T22:34:24.561Z"
    }
  }
}

{  "data": {    "id": "tool-L4oe7rNwn7J4E5Yr",    "type": "terraform-versions",    "attributes": {      "version": "0.11.8",      "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",      "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",      "official": true,      "deprecated": false,      "deprecated-reason": null,      "enabled": true,      "beta": false,      "usage": 0,      "created-at": "2018-08-15T22:34:24.561Z"    }  }}

»Show a Terraform version

GET /api/v2/admin/terraform-versions/:id

ParameterDescription
:idThe ID of the Terraform version to show
StatusResponseReason
200JSON API document (type: "terraform-versions")The request was successful
404JSON API error objectTerraform version not found, or client is not an administrator

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/admin/terraform-versions/tool-L4oe7rNwn7J4E5Yr

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/admin/terraform-versions/tool-L4oe7rNwn7J4E5Yr

»Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "terraform-versions",
    "attributes": {
      "version": "0.11.8",
      "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",
      "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",
      "official": true,
      "deprecated": false,
      "deprecated-reason": null,
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2018-08-15T22:34:24.561Z"
    }
  }
}

{  "data": {    "id": "tool-L4oe7rNwn7J4E5Yr",    "type": "terraform-versions",    "attributes": {      "version": "0.11.8",      "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",      "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",      "official": true,      "deprecated": false,      "deprecated-reason": null,      "enabled": true,      "beta": false,      "usage": 0,      "created-at": "2018-08-15T22:34:24.561Z"    }  }}

»Update a Terraform version

PATCH /admin/terraform-versions/:id

ParameterDescription
:idThe ID of the Terraform version to update
StatusResponseReason
200JSON API document (type: "terraform-versions")The Terraform version was successfully updated
404JSON API error objectTerraform version not found, or client is not an administrator
422JSON API error objectValidation errors

»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 "terraform-versions"
data.attributes.versionstring(previous value)A semantic version string in N.N.N or N.N.N-bundleName format (e.g. "0.11.0", "0.12.20-beta1".)
data.attributes.urlstring(previous value)The URL where a ZIP-compressed 64-bit Linux binary of this version can be downloaded
data.attributes.shastring(previous value)The SHA-256 checksum of the compressed Terraform binary
data.attributes.officialbool(previous value)Whether or not this is an official release of Terraform
data.attributes.deprecatedbool(previous value)Whether or not this version of Terraform is deprecated
data.attributes.deprecated-reasonstring(previous value)Additional context about why a version of Terraform is deprecated.
data.attributes.enabledbool(previous value)Whether or not this version of Terraform is enabled for use in Terraform Cloud
data.attributes.betabool(previous value)Whether or not this version of Terraform is a beta pre-release

»Sample Payload

{
  "data": {
    "type": "terraform-versions",
    "attributes": {
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of Terraform. Please upgrade as soon as possible"
    }
  }
}

{  "data": {    "type": "terraform-versions",    "attributes": {      "deprecated": true,      "deprecated-reason": "A bug was discovered in this version of Terraform. Please upgrade as soon as possible"    }  }}

»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/admin/terraform-versions/tool-L4oe7rNwn7J4E5Yr

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request PATCH \  --data @payload.json \  https://app.terraform.io/api/v2/admin/terraform-versions/tool-L4oe7rNwn7J4E5Yr

»Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "terraform-versions",
    "attributes": {
      "version": "0.11.8",
      "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",
      "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",
      "official": true,
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of Terraform. Please upgrade as soon as possible",
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2018-08-15T22:34:24.561Z"
    }
  }
}

{  "data": {    "id": "tool-L4oe7rNwn7J4E5Yr",    "type": "terraform-versions",    "attributes": {      "version": "0.11.8",      "url": "https://releases.hashicorp.com/terraform/0.11.8/terraform_0.11.8_linux_amd64.zip",      "sha": "84ccfb8e13b5fce63051294f787885b76a1fedef6bdbecf51c5e586c9e20c9b7",      "official": true,      "deprecated": true,      "deprecated-reason": "A bug was discovered in this version of Terraform. Please upgrade as soon as possible",      "enabled": true,      "beta": false,      "usage": 0,      "created-at": "2018-08-15T22:34:24.561Z"    }  }}

»Delete a Terraform version

DELETE /admin/terraform-versions/:id

This endpoint removes a Terraform version from Terraform Cloud. Versions cannot be removed if they are labeled as official versions of Terraform or if there are workspaces using them.

ParameterDescription
:idThe ID of the Terraform version to delete
StatusResponseReason
204Empty responseThe Terraform version was successfully deleted
404JSON API error objectTerraform version not found, or client is not an administrator
422JSON API error objectThe Terraform version cannot be removed (it is official or is in use)

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/admin/terraform-versions/tool-L4oe7rNwn7J4E5Yr

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request DELETE \  https://app.terraform.io/api/v2/admin/terraform-versions/tool-L4oe7rNwn7J4E5Yr