Manage module versions API reference

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.

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.

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

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.

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

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.

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
        }
      ]
    }
  ]
}