A new platform for documentation and tutorials is launching soon.
We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.
Search Terraform documentation Terraform Enterprise Only: 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.
The Terraform Versions Admin API lets site administrators manage which versions of Terraform are available to the Terraform Cloud users within their enterprise.
GET /api/v2/admin/terraform-versions
This endpoint lists all known versions of Terraform.
» Query ParametersThis 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 filter[version]
Optional. A query string. This will find an exact Terraform version matching the version queried. This option takes precedence over search queries.search[version]
Optional. A search query string. This will search for Terraform versions matching the version number queried.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 Requestcurl \
--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
}
}
}
POST /admin/terraform-versions
» Request BodyThis 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.type
string Must be "terraform-versions"
data.attributes.version
string 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.url
string The URL where a ZIP-compressed 64-bit Linux binary of this version can be downloaded data.attributes.sha
string The SHA-256 checksum of the compressed Terraform binary data.attributes.deprecated
bool false
Whether or not this version of Terraform is deprecated data.attributes.deprecated-reason
string null
Additional context about why a version of Terraform is deprecated. Field is null unless deprecated is true. data.attributes.official
bool false
Whether or not this is an official release of Terraform data.attributes.enabled
bool true
Whether or not this version of Terraform is enabled for use in Terraform Cloud data.attributes.beta
bool false
Whether 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 Requestcurl \
--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"
}
}
}
GET /api/v2/admin/terraform-versions/:id
Parameter Description :id
The ID of the Terraform version to show
» Sample Requestcurl \
--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"
}
}
}
PATCH /admin/terraform-versions/:id
Parameter Description :id
The ID of the Terraform version to update
» Request BodyThis PATCH 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.type
string Must be "terraform-versions"
data.attributes.version
string (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.url
string (previous value) The URL where a ZIP-compressed 64-bit Linux binary of this version can be downloaded data.attributes.sha
string (previous value) The SHA-256 checksum of the compressed Terraform binary data.attributes.official
bool (previous value) Whether or not this is an official release of Terraform data.attributes.deprecated
bool (previous value) Whether or not this version of Terraform is deprecated data.attributes.deprecated-reason
string (previous value) Additional context about why a version of Terraform is deprecated. data.attributes.enabled
bool (previous value) Whether or not this version of Terraform is enabled for use in Terraform Cloud data.attributes.beta
bool (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 Requestcurl \
--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 /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.
Parameter Description :id
The ID of the Terraform version to delete
Status Response Reason 204 Empty response The Terraform version was successfully deleted 404 JSON API error object Terraform version not found, or client is not an administrator 422 JSON API error object The Terraform version cannot be removed (it is official or is in use)
» Sample Requestcurl \
--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