Admin Terraform policy plugin versions API

The /admin/tfpolicy-versions API endpoint lets site administrators manage which versions of Terraform policy are available to Terraform Enterprise users.

List all Terraform policy plugin versions

GET /api/v2/admin/tfpolicy-versions

This endpoint lists all known versions of the Terraform policy plugin.

Status	Response	Reason
200	JSON API document (`type: "tfpolicy-versions"`)	Successfully lists Terraform policy plugin versions.
404	JSON API error object	Client 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.

Parameter	Description
`filter[version]`	Optional. Specifies a Terraform policy plugin version to filter for as a query string. Terraform Enterprise matches on the exact version. This option takes precedence over search queries.
`search[version]`	Optional. Specifies a Terraform policy plugin version to search for as a query string. Terraform Enterprise matches on the exact version.
`sort`	Optional. Allows sorting by version. The only valid value is `"version"`. Prepending a hyphen to the sort parameter reverses the order, for example `"-version"`. If omitted, the default sort order is descending.
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 20 Terraform policy plugin versions per page.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://tfe.example.com/api/v2/admin/tfpolicy-versions"

Sample Response

{
  "data": [
    {
      "id": "tool-GeJTot5THp1f2Xcp",
      "type": "tfpolicy-versions",
      "attributes": {
        "version": "0.3.0",
        "url": null,
        "sha": null,
        "official": true,
        "enabled": true,
        "beta": false,
        "deprecated": false,
        "deprecated-reason": null,
        "created-at": "2026-09-07T10:04:53.586Z",
        "archs": [
          {
            "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_amd64.zip",
            "sha": "a8373bf9b2763f0401b71bc2ebfc8e788990507da64c5726c29532e851992a71",
            "os": "linux",
            "arch": "amd64"
          },
          {
            "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_arm64.zip",
            "sha": "30f81bf6a6adc8ba76a1bf617ecd31e46b59dc496141fbefba38a85017d6b670",
            "os": "linux",
            "arch": "arm64"
          }
        ]
      }
    }
  ],
  "links": {
    "self": "https://tfe.example.com/api/v2/admin/tfpolicy-versions?page%5Bnumber%5D=1&page%5Bsize%5D=10&page%5Bnumber%5D=1&page%5Bsize%5D=20&sort=-version",
    "first": "https://tfe.example.com/api/v2/admin/tfpolicy-versions?page%5Bnumber%5D=1&page%5Bsize%5D=10&page%5Bnumber%5D=1&page%5Bsize%5D=20&sort=-version",
    "prev": null,
    "next": "https://tfe.example.com/api/v2/admin/tfpolicy-versions?page%5Bnumber%5D=1&page%5Bsize%5D=10&page%5Bnumber%5D=2&page%5Bsize%5D=20&sort=-version",
    "last": "https://tfe.example.com/api/v2/admin/tfpolicy-versions?page%5Bnumber%5D=1&page%5Bsize%5D=10&page%5Bnumber%5D=2&page%5Bsize%5D=20&sort=-version"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": 2,
      "total-pages": 2,
      "total-count": 26
    }
  }
}

Create a Terraform policy plugin version

POST /api/v2/admin/tfpolicy-versions

Status	Response	Reason
201	JSON API document (`type: "tfpolicy-versions"`)	The Terraform policy plugin version was successfully created.
404	JSON API error object	The client is not an administrator.
422	JSON API error object	Validation errors.

Request Body

When sending a POST request, you must provide a JSON object with the following properties as the request payload.

Properties without a default value are required.

We recommend setting the URL and SHA-256 checksum of a Terraform policy plugin binary in the archs[n].url and archs[n].sha fields.

Key path	Type	Default	Description
`data.type`	string		Must be `"tfpolicy-versions"`.
`data.attributes.version`	string		A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"` or `"0.12.20-beta1"`).
`data.attributes.url`	string		The URL where you can download the Linux amd64 binary of this version. We recommend using the `archs[n].url` field instead.
`data.attributes.sha`	string		The SHA-256 checksum of the Linux amd64 Terraform policy plugin binary. We recommend using the `archs[n].sha` field instead.
`data.attributes.deprecated`	bool	`false`	Whether or not this version of Terraform policy plugin is deprecated.
`data.attributes.deprecated-reason`	string	`null`	Additional context about why a version of Terraform policy plugin is deprecated. Field is `null` unless the `data.attributes.deprecated` attribute is `true`.
`data.attributes.official`	bool	`false`	Whether or not this is an official release of Terraform policy plugin.
`data.attributes.enabled`	bool	`true`	Whether or not this version of Terraform policy plugin is enabled for use in HCP Terraform.
`data.attributes.beta`	bool	`false`	Whether or not this version of Terraform policy plugin is a beta pre-release.
`data.attributes.archs`	array		An array of architecture objects.
`data.attributes.archs[n].url`	string		The URL where you can download the 64-bit Linux binary of this version. We recommend using this field to set the URL instead of the `url` field.
`data.attributes.archs[n].sha`	string		The SHA-256 checksum of the Terraform policy plugin binary. We recommend using this field to set the checksum instead of the `sha` field.
`data.attributes.archs[n].os`	string	`"linux"`	Terraform policy plugin version operating system.
`data.attributes.archs[n].arch`	string	`"amd64"`	Terraform policy plugin version architecture.

Sample Payload

{
  "data": {
    "type": "tfpolicy-versions",
    "attributes": {
      "version": "0.3.0",
      "url": null,
      "sha": null,
      "official": true,
      "enabled": true,
      "beta": false,
      "deprecated": false,
      "deprecated-reason": null,
      "archs": [
        {
          "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_amd64.zip",
          "sha": "a8373bf9b2763f0401b71bc2ebfc8e788990507da64c5726c29532e851992a71",
          "os": "linux",
          "arch": "amd64"
        },
        {
          "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_arm64.zip",
          "sha": "30f81bf6a6adc8ba76a1bf617ecd31e46b59dc496141fbefba38a85017d6b670",
          "os": "linux",
          "arch": "arm64"
        }
      ]
    }
  }
}

Sample Request

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

Sample Response

{
  "data": {
    "id": "tool-GeJTot5THp1f2Xcp",
    "type": "tfpolicy-versions",
    "attributes": {
      "version": "0.3.0",
      "url": null,
      "sha": null,
      "official": true,
      "enabled": true,
      "beta": false,
      "deprecated": false,
      "deprecated-reason": null,
      "created-at": "2026-09-07T10:04:53.586Z",
      "archs": [
        {
          "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_amd64.zip",
          "sha": "a8373bf9b2763f0401b71bc2ebfc8e788990507da64c5726c29532e851992a71",
          "os": "linux",
          "arch": "amd64"
        },
        {
          "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_arm64.zip",
          "sha": "30f81bf6a6adc8ba76a1bf617ecd31e46b59dc496141fbefba38a85017d6b670",
          "os": "linux",
          "arch": "arm64"
        }
      ]
    }
  }
}

Show a Terraform policy plugin version

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

Parameter	Description
`:id`	The ID of the Terraform policy plugin version to show.

Status	Response	Reason
200	JSON API document (`type: "tfpolicy-versions"`)	Successfully shows the specified Terraform policy plugin version.
404	JSON API error object	Could not find the specified Terraform policy plugin version, 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/tfpolicy-versions/tool-GeJTot5THp1f2Xcp

Sample Response

{
  "data": {
    "id": "tool-GeJTot5THp1f2Xcp",
    "type": "tfpolicy-versions",
    "attributes": {
      "version": "0.3.0",
      "url": null,
      "sha": null,
      "official": true,
      "enabled": true,
      "beta": false,
      "deprecated": false,
      "deprecated-reason": null,
      "created-at": "2026-09-07T10:04:53.586Z",
      "archs": [
        {
          "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_amd64.zip",
          "sha": "a8373bf9b2763f0401b71bc2ebfc8e788990507da64c5726c29532e851992a71",
          "os": "linux",
          "arch": "amd64"
        },
        {
          "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_arm64.zip",
          "sha": "30f81bf6a6adc8ba76a1bf617ecd31e46b59dc496141fbefba38a85017d6b670",
          "os": "linux",
          "arch": "arm64"
        }
      ]
    }
  }
}

Update a Terraform policy plugin version

PATCH /api/v2/admin/tfpolicy-versions/:id

Parameter	Description
`:id`	The ID of the Terraform policy plugin version to update.

Status	Response	Reason
200	JSON API document (`type: "tfpolicy-versions"`)	The Terraform policy plugin version was successfully updated.
404	JSON API error object	Could not find the specified Terraform policy plugin version, or client is not an administrator.
422	JSON API error object	Validation errors.

Request Body

When sending a PATCH request, you must include a JSON object with the following properties as a request payload.

Properties without a default value are required.

We recommend setting the URL and SHA-256 checksum of a Terraform policy plugin binary in the archs[n].url and archs[n].sha fields.

Key path	Type	Default	Description
`data.type`	string		Must be `"tfpolicy-versions"`.
`data.attributes.version`	string	(previous value)	A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"` or `"0.12.20-beta1"`).
`data.attributes.url`	string	(previous value)	The URL where you can download the Linux amd64 binary of this version. We recommend using the `archs[n].url` field instead.
`data.attributes.sha`	string	(previous value)	The SHA-256 checksum of the Linux amd64 Terraform policy plugin binary. We recommend using the `archs[n].sha` field instead.
`data.attributes.official`	bool	(previous value)	Whether or not this is an official release of Terraform policy plugin.
`data.attributes.deprecated`	bool	(previous value)	Whether or not this version of Terraform policy plugin is deprecated.
`data.attributes.deprecated-reason`	string	(previous value)	Additional context about why a version of Terraform policy plugin is deprecated.
`data.attributes.enabled`	bool	(previous value)	Whether or not this version of Terraform policy plugin is enabled for use in HCP Terraform.
`data.attributes.beta`	bool	(previous value)	Whether or not this version of Terraform policy plugin is a beta pre-release.
`data.attributes.archs`	array		An array of architecture objects.
`data.attributes.archs[n].url`	string		The URL where you can download the 64-bit Linux binary of this version. We recommend using this field to set the URL instead of the `url` field.
`data.attributes.archs[n].sha`	string		The SHA-256 checksum of the Terraform policy plugin binary. We recommend using this field to set the checksum instead of the `sha` field.
`data.attributes.archs[n].os`	string	`"linux"`	Terraform policy plugin version operating system.
`data.attributes.archs[n].arch`	string	`"amd64"`	Terraform policy plugin version architecture.

Sample Payload

{
  "data": {
    "type": "tfpolicy-versions",
    "attributes": {
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of Terraform policy plugin. 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/tfpolicy-versions/tool-GeJTot5THp1f2Xcp

Sample Response

{
  "data": {
    "id": "tool-GeJTot5THp1f2Xcp",
    "type": "tfpolicy-versions",
    "attributes": {
      "version": "0.3.0",
      "url": null,
      "sha": null,
      "official": true,
      "enabled": true,
      "beta": false,
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of Terraform policy plugin. Please upgrade as soon as possible",
      "created-at": "2026-09-07T10:04:53.586Z",
      "archs": [
        {
          "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_amd64.zip",
          "sha": "a8373bf9b2763f0401b71bc2ebfc8e788990507da64c5726c29532e851992a71",
          "os": "linux",
          "arch": "amd64"
        },
        {
          "url": "https://releases.hashicorp.com/tfpolicy-plugin/0.3.0/tfpolicy-plugin_0.3.0_linux_arm64.zip",
          "sha": "30f81bf6a6adc8ba76a1bf617ecd31e46b59dc496141fbefba38a85017d6b670",
          "os": "linux",
          "arch": "arm64"
        }
      ]
    }
  }
}

Delete a Terraform policy plugin version

DELETE /api/v2/admin/tfpolicy-versions/:id

This endpoint removes a Terraform policy plugin version from HCP Terraform. You cannot remove officially labeled Terraform policy plugin versions or any version used by a workspace.

Parameter	Description
`:id`	The ID of the Terraform policy plugin version to delete.

Status	Response	Reason
204	Empty response	The Terraform policy plugin version was successfully deleted.
404	JSON API error object	The request could not find a matching Terraform policy plugin version with the specified ID, or the client is not an administrator.
422	JSON API error object	The request could not remove the Terraform policy plugin version because it is an official version or a workspace uses it.

Sample Request

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