Manage module versions API

This topic provides reference information about API endpoints that let your deprecate module versions in your organization’s private registry.

Introduction

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.

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

After deprecating a module version, you can revert that deprecated status to remove the warnings from that version in the registry and outputs. For more details on module deprecation, refer to Deprecate module versions.

Note: The ability to deprecate module versions is in public beta. All APIs and workflows are subject to change.

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 is used for.
`: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 is used for.
`: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"
  }
}