Manage module versions API reference

Use the module version management API endpoints to deprecate, revoke, and revert of status of module versions in your organization’s private registry.

Note: Module deprecation is available in the HCP Terraform Plus Edition. Module revocation is available in the HCP Terraform Premium Edition. Refer to HCP Terraform pricing for details.

Overview

As part of the module lifecycle, you can deprecate or revoke older module versions as you stop supporting them, signaling to module consumers that they need to upgrade to newer versions.

When you deprecate a module version, HCP Terraform adds warnings to the module's registry page and to run outputs when anyone uses the deprecated version. After deprecating a module version, you can revert that deprecated status to remove the warnings from that version in the registry and outputs.

Revoking a module version adds warnings to the module's registry page, warnings in the run outputs of existing users, and blocks new users from using that version. Reverting a module version’s revocation sets the module version back to a deprecated state.

For more details on deprecating or revoking module versions, refer to Manage module versions.

Deprecate a module version

Use this endpoint to deprecate a module version.

PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version

Parameter	Description
`:organization_name`	The name of the organization the module belongs to.
`:module_name`	The name of the module whose version you want to deprecate.
`:module_provider`	Specifies the Terraform provider that this module uses.
`:module_version`	The module version you want to deprecate.

This endpoint allows you to deprecate a specific module version. Deprecating a module version adds warnings to the run output of any consumers using this module.

Status	Response	Reason
200	JSON API document	Successfully deprecated a module version.
404	JSON API error object	This organization is not authorized to deprecate this module version, or the module version does not exist.
422	JSON API error object	Malformed request body, for example the request is missing attributes or uses the wrong types.
500 or 503	JSON API error object	Failure occurred while deprecating a module version.

Sample payload

{
  "data": {
    "type": "module-versions",
    "attributes": {
      "deprecation": {
        "deprecated-status": "Deprecated",
        "reason": "Deprecated due to a security vulnerability issue.",
        "link": "https://www.hashicorp.com/"
      }
    }
  }
}

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/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0

Sample response

{
    "data": {
        "type": "module-versions",
        "id": "1",
        "relationships": {
            "deprecation": {
                "data": {
                    "id": "2",
                    "type": "deprecations"
                }
            }
        }
    },
    "included": [
        {
            "type": "deprecations",
            "id": "2",
            "attributes": {
                "link": "https://www.hashicorp.com/",
                "reason": "Deprecated due to a security vulnerability issue. Applies will be blocked in 15 days."
            }
        }
    ]
}

Revert the deprecation status for a module version

Use this endpoint to revert the deprecation of a module version.

PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version

Parameter	Description
`:organization_name`	The name of the organization the module belongs to.
`:module_name`	The name of the module you want to revert the deprecation of.
`:module_provider`	Specifies the Terraform provider that this module uses.
`:module_version`	The module version you want to revert the deprecation of.

Deprecating a module version adds warnings to the run output of any consumers using this module. Reverting the deprecation status removes warnings from the output of consumers and fully reinstates the module version.

Status	Response	Reason
200	JSON API document	Successfully reverted a module version’s deprecation status and reinstated that version.
404	JSON API error object	This organization is not authorized to revert the depreciation of this module version, or the module version does not exist.
422	JSON API error object	Malformed request body, for example the request is missing attributes or uses the wrong types.
500 or 503	JSON API error object	Failure occurred while reverting the deprecation of a module version.

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/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0

Sample payload

{
  "data": {
    "type": "module-versions",
    "attributes": {
      "deprecation": {
        "deprecated-status": "Undeprecated"
      }
    }
  }
}

Sample response

{
  "data": {
     "type": "module-versions",
     "id": "1"
  }
}

Fetch a module version’s deprecation data

Send a GET request to the /modules/:github-organization/:module/:provider/versions endpoint to retrieve data about private registry modules, including the module's deprecation status. Refer to the private registry module API example for additional information.

For example, if you want to know the deprecation status of v0.0.1 of the aws provider’s consul module in your my-cloud-org organization, you could perform the following API call:

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/0.0.1

If the module is deprecated, your response includes a deprecation key with the details of that module version’s deprecation.

{
  "id": "hashicorp/consul/aws/0.0.1",
  "owner": "gruntwork-team",
  "namespace": "hashicorp",
  "name": "consul",
  "version": "0.0.1",
  "provider": "aws",
  "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer"
  // ... //
  "deprecation": {
    "reason": "This version was deprecated due to a vulnerability issue. Please upgrade to 0.0.2.",
    "link": "https://hashicorp.com"
  }
}

To check the deprecation status of all of the consul module’s versions, you could perform the following API call:

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/versions

The response includes multiple versions, and each version has a deprecation key listing the details of that module’s deprecation. If a module version has not been deprecated, the deprecation field returns null.

{
  "modules": [
    {
      "source": "hashicorp/consul/aws",
      "versions": [
          {
            "version": "0.0.1",
            // ... //
            "deprecation": {
              "reason": "security vulnerability",
              "link": "www.hashicorp.com"
            }
          },
          {
            "version": "0.0.2",
            "submodules": [],
            "root": {
                "dependencies": [],
                "providers": [
                  {
                      "name": "template",
                      "version": ""
                  },
                  {
                      "name": "aws",
                      "version": ""
                  }
                ]
            },
            "deprecation": null
        }
      ]
    }
  ]
}

Revoke a module version

Use this endpoint to revoke a module version. You must deprecate a module version before you can revoke it.

PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version

Parameter	Description
`:organization_name`	The name of the organization the module belongs to.
`:module_name`	The name of the module whose version you want to revoke.
`:module_provider`	Specifies the Terraform provider that this module uses.
`:module_version`	The module version you want to revoke.

This endpoint allows you to revoke a specific module version. Revoking a module version adds warnings to the run output of current consumers of this version and blocks new users from trying to use that version.

Status	Response	Reason
200	JSON API document	Successfully revoked a module version.
404	JSON API error object	This organization is not authorized to revoke this module version, or the module version does not exist.
422	JSON API error object	Malformed request body, for example the request is missing attributes or uses the wrong types.
500 or 503	JSON API error object	Failure occurred while revoking a module version.

Sample Payload

{
  "data": {
    "type": "module-versions",
    "attributes": {
      "revocation": {
        "status": "Revoked",
        "message": "Revoked due to a security vulnerability issue.",
        "link": "https://www.hashicorp.com/"
      }
    }
  }
}

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/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0

Sample Response

{
  "data": {
    "id": "modver-uKQCVs5vAKDmUMyw",
    "type": "registry-module-versions",
    "attributes": {
      "source": "tfe-api",
      "status": "ok",
      "version": "11.0.0",
      "commit-sha": null,
      "branch": null,
      "created-at": "2024-08-28T20:48:05.206Z",
      "updated-at": "2024-08-28T20:48:09.175Z",
      "revocation": {
        "status": "Revoked",
        "message": "Revoked due to a security vulnerability issue.",
        "link": "https://www.hashicorp.com/"
      }
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "mod-yDKMcmJYx9oFrGao",
          "type": "registry-modules"
        }
      }
    },
    "links": {
      "upload": "https://app.terraform.io/_archivist/v1/object/dmF1bHQ6djE6eElWekF3RH"
    }
  }
}

Revert the revocation status for a module version

Use this endpoint to revert the revocation of a module version.

PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version

Parameter	Description
`:organization_name`	The name of the organization the module belongs to.
`:module_name`	The name of the module you want to revert the revocation of.
`:module_provider`	Specifies the Terraform provider that this module uses.
`:module_version`	The module version you want to revert the revocation of.

When you revert the revocation of a module version, HCP Terraform sets that version as deprecated, signaling that it is still maintained and supported but not recommended. Deprecated module versions produce warnings in the registry and run outputs, but new users can still use them.

Status	Response	Reason
200	JSON API document	Successfully reverted a module version’s revocation status and deprecated that version.
404	JSON API error object	This organization is not authorized to revert the revocation of this module version, or the module version does not exist.
422	JSON API error object	Malformed request body, for example the request is missing attributes or uses the wrong types.
500 or 503	JSON API error object	Failure occurred while reverting the revocation of a module version.

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/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0

Sample payload

{
  "data": {
    "type": "module-versions",
    "attributes": {
      "revocation": {
        "status": "Unrevoked"
      }
    }
  }
}

Sample Response

{
  "data": {
    "id": "modver-uKQCVs5vAKDmUMyw",
    "type": "registry-module-versions",
    "attributes": {
      "source": "tfe-api",
      "status": "ok",
      "version": "11.0.0",
      "commit-sha": null,
      "branch": null,
      "created-at": "2024-08-28T20:48:05.206Z",
      "updated-at": "2024-08-28T20:48:09.175Z",
      "revocation": {
          "status": "Unrevoked",
      }
    },
    "relationships": {
      "registry-module": {
          "data": {
              "id": "mod-yDKMcmJYx9oFrGao",
              "type": "registry-modules"
          }
      }
    },
    "links": {
      "upload": "https://app.terraform.io/_archivist/v1/object/dmF1bHQ6djE6eElWekF3RH"
    }
  }
}

Fetch data about a module version’s revocation

Send a GET request to the /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider endpoint to retrieve data about private registry modules, including the module's revocation status. Refer to the private registry module API example for additional information.

For example, if you want to know the revocation status of v0.0.1 of the aws provider’s consul module in your my-cloud-org organization, you could perform the following API call:

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/organizations/my-cloud-org/registry-modules/private/my-cloud-org/consul/aws/version?module_version=1.0.0

If the module is revoked, your response includes a revocation key with the details of that module version’s revocation.

{
  "data": {
    "id": "modver-3tKAXyRnpGYCxW7d",
    "type": "registry-module-versions",
    "attributes": {
      "source": "github",
      "status": "ok",
      "version": "1.0.0",
      "commit-sha": "ea18e73d8da502870fdcbfc54155046bc0cf2679",
      "branch": null,
      "created-at": "2024-10-11T19:53:35.082Z",
      "updated-at": "2024-10-11T19:53:38.782Z",
      "revocation": {
        "status": "revoked",
        "message": "please upgrade to version 1.0.1",
        "link": "https://github.com"
      }
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "mod-u8BFFruSTSz8dN4C",
          "type": "registry-modules"
        }
      }
    },
    "links": {
      "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djQ6V1pZWWwra1"
    }
  }
}

To check the revocation status of all of the consul module’s versions, you could perform the following API call:

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/organizations/my-cloud-org/registry-modules/private/my-cloud-org/consul/aws

The response includes the revoked versions of this module in the revoked-versions key.

{
  "data": {
  "id": "mod-u8BFFruSTSz8dN4C",
  "type": "registry-modules",
  "attributes": {
      "name": "module",
      "namespace": "my-cloud-org",
      // ... //
      "revoked-versions": [
          "1.0.0"
      ],
    // ... //
  },
}