Note: Public Module Curation is only available in Terraform Cloud. Where applicable, the registry_name parameter must be private for Terraform Enterprise.
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
q
Optional. A search query string. Modules are searchable by name, namespace, provider fields.
filter[field name]
Optional. If specified, restricts results to those with the matching field name value. Valid values are registry_name, provider, and organization_name.
page[number]
Optional. If omitted, the endpoint will return the first page.
page[size]
Optional. If omitted, the endpoint will return 20 registry modules per page.
Deprecation warning: the following endpoint POST /registry-modules is replaced by the below endpoint and will be removed from future versions of the API!
POST /organizations/:organization_name/registry-modules/vcs
Parameter
Description
:organization_name
The name of the organization to create a module in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team.
Publishes a new registry private module from a VCS repository, with module versions managed automatically by the repository's tags. The publishing process will fetch all tags in the source repository that look like SemVer versions with optional 'v' prefix. For each version, the tag is cloned and the config parsed to populate module details (input and output variables, readme, submodules, etc.). The Module Registry Requirements define additional requirements on naming, standard module structure and tags for releases.
This 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 "registry-modules".
data.attributes.vcs-repo.identifier
string
The repository from which to ingress the configuration.
data.attributes.vcs-repo.oauth-token-id
string
The VCS Connection (OAuth Connection + Token) to use as identified. This ID can be obtained from the oauth-tokens endpoint.
data.attributes.vcs-repo.display_identifier
string
The display identifier for the repository. For most VCS providers outside of BitBucket Cloud, this will match the data.attributes.vcs-repo.identifier string.
A VCS repository identifier is a reference to a VCS repository in the format :org/:repo, where :org and :repo refer to the organization (or project key, for Bitbucket Server) and repository in your VCS provider. The format for Azure DevOps is :org/:project/_git/:repo.
The OAuth Token ID identifies the VCS connection, and therefore the organization, that the module will be created in.
POST /organizations/:organization_name/registry-modules
Parameter
Description
:organization_name
The name of the organization to create a module in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team.
Creates a new registry module without a backing VCS repository.
After creating a module, a version must be created and uploaded in order to be usable. Modules created this way do not automatically update with new versions; instead, you must explicitly create and upload each new version with the Create a Module Version endpoint.
When created, the public module record will be available in the organization's registry module list. You cannot create versions for public modules as they are maintained in the public registry.
This 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 "registry-modules".
data.attributes.name
string
The name of this module. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters.
data.attributes.provider
string
Specifies the Terraform provider that this module is used for. May contain lowercase alphanumeric characters. Maximum length is 64 characters.
data.attributes.namespace
string
The namespace of this module. Cannot be set for private modules. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters.
data.attributes.registry-name
string
Indicates whether this is a publicly maintained module or private. Must be either public or private.
Deprecation warning: the following endpoint POST /registry-modules/:organization_name/:name/:provider/versions is replaced by the below endpoint and will be removed from future versions of the API!
POST /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/versions
Parameter
Description
:organization_name
The name of the organization to create a module in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team.
:namespace
The namespace of the module for which the version is being created. For private modules this is the same as the :organization_name parameter
:name
The name of the module for which the version is being created.
:provider
The name of the provider for which the version is being created.
:registry-name
Must be private.
Creates a new registry module version. This endpoint only applies to private modules without a VCS repository; VCS-linked modules automatically create new versions for new tags. After creating the version, the module should be uploaded to the returned upload link.
Package the files in an archive format by running tar zcvf module.tar.gz * in the module's directory.
~$ cd terraform-null-test
terraform-null-test$ tar zcvf module.tar.gz *
a README.md
a examples
a examples/default
a examples/default/main.tf
a examples/default/README.md
a main.tf
~$ cd terraform-null-test
terraform-null-test$ tar zcvf module.tar.gz *
a README.md
a examples
a examples/default
a examples/default/main.tf
a examples/default/README.md
a main.tf
Deprecation warning: the following endpoint GET /registry-modules/show/:organization_name/:name/:provider is replaced by the below endpoint and will be removed from future versions of the API!
GET /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider
The name of the organization to delete a module from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team.
:namespace
The module namespace that the deletion will affect. For private modules this is the name of the organization that owns the module.
:name
The module name that the deletion will affect.
:provider
If specified, the provider for the module that the deletion will affect.
:version
If specified, the version for the module and provider that will be deleted.
:registry_name
Either public or private
When removing modules, there are three versions of the endpoint, depending on how many parameters are specified.
If all parameters (module namespace, name, provider, and version) are specified, the specified version for the given provider of the module is deleted.
If module namespace, name, and provider are specified, the specified provider for the given module is deleted along with all its versions.
If only module namespace and name are specified, the entire module is deleted.
For public modules, only the the endpoint specifying the module namespace and name is valid. The other DELETE endpoints will 404.
For public modules, this only removes the record from the organization's Terraform Cloud Registry and does not remove the public module from registry.terraform.io.
If a version deletion would leave a provider with no versions, the provider will be deleted. If a provider deletion would leave a module with no providers, the module will be deleted.
