June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Network Infrastructure
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform Cloud and Enterprise

  • Overview
  • Plans and Features
  • Getting Started
    • API Docs template
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
      • Modules
      • Providers
      • Private Provider Versions and Platforms
      • GPG Keys
    • Runs
    • Run Tasks
    • Run Tasks Integration
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Access
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Resources
    • Variable Sets
      • Overview
      • Module Sharing
      • Organizations
      • Runs
      • Settings
      • Terraform Versions
      • Users
      • Workspaces
    • Changelog
    • Stability Policy
    • Overview
    • Creating Workspaces
    • Naming
    • Terraform Configurations
      • Overview
      • Managing Variables
      • Overview
      • VCS Connections
      • Access
      • Notifications
      • SSH Keys for Modules
      • Run Triggers
      • Run Tasks
    • Terraform State
    • JSON Filtering
    • Remote Operations
    • Viewing and Managing Runs
    • Run States and Stages
    • Run Modes and Options
    • UI/VCS-driven Runs
    • API-driven Runs
    • CLI-driven Runs
    • The Run Environment
    • Installing Software
    • Users
    • Teams
    • Organizations
    • Permissions
    • Two-factor Authentication
    • API Tokens
      • Overview
      • Microsoft Azure AD
      • Okta
      • SAML
      • Linking a User Account
      • Testing
    • Overview
    • GitHub.com
    • GitHub.com (OAuth)
    • GitHub Enterprise
    • GitLab.com
    • GitLab EE and CE
    • Bitbucket Cloud
    • Bitbucket Server and Data Center
    • Azure DevOps Services
    • Azure DevOps Server
    • Troubleshooting
    • Overview
    • Adding Public Providers and Modules
    • Publishing Private Providers
    • Publishing Private Modules
    • Using Providers and Modules
    • Configuration Designer
  • Migrating to Terraform Cloud
    • Overview
    • Using Sentinel with Terraform 0.12
    • Manage Policies
    • Enforce and Override Policies
    • Mocking Terraform Sentinel Data
    • Working With JSON Result Data
      • Overview
      • tfconfig
      • tfconfig/v2
      • tfplan
      • tfplan/v2
      • tfstate
      • tfstate/v2
      • tfrun
    • Example Policies
    • Overview
    • AWS
    • GCP
    • Azure
      • Overview
      • Service Catalog
      • Admin Guide
      • Developer Reference
      • Example Customizations
      • V1 Setup Instructions
    • Splunk Integration
    • Kubernetes Integration
    • Run Tasks Integration
    • Overview
    • IP Ranges
    • Data Security
    • Security Model
    • Overview
    • Part 1: Overview of Our Recommended Workflow
    • Part 2: Evaluating Your Current Provisioning Practices
    • Part 3: How to Evolve Your Provisioning Practices
    • Part 3.1: From Manual Changes to Semi-Automation
    • Part 3.2: From Semi-Automation to Infrastructure as Code
    • Part 3.3: From Infrastructure as Code to Collaborative Infrastructure as Code
    • Part 3.4: Advanced Workflow Improvements

  • Terraform Cloud Agents

  • Terraform Enterprise Admin

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Registry Modules API

Note: Public Module Curation is only available in Terraform Cloud. Where applicable, the registry_name parameter must be private for Terraform Enterprise.

»Terraform Cloud Registry Implementation

The Terraform Cloud Module Registry implements the Registry standard API for consuming/exposing private modules. Refer to the Module Registry HTTP API to perform the following:

  • Browse available modules
  • Search modules by keyword
  • List available versions for a specific module
  • Download source code for a specific module version
  • List latest version of a module for all providers
  • Get the latest version for a specific module provider
  • Get a specific module
  • Download the latest version of a module

For publicly curated modules, the Terraform Cloud Module Registry acts as a proxy to the Terraform Registry for the following:

  • List available versions for a specific module
  • Get a specific module
  • Get the latest version for a specific module provider

The Terraform Cloud Module Registry endpoints differs from the Module Registry endpoints in the following ways:

  • The :namespace parameter should be replaced with the organization name for private modules.
  • The private module registry discovery endpoints have the path prefix provided in the discovery document which is currently /api/registry/v1.
  • The public module registry discovery endpoints have the path prefix provided in the discovery document which is currently /api/registry/public/v1.
  • Authentication is handled the same as all other Terraform Cloud endpoints.

»Sample Registry Request (private module)

List available versions for the consul module for the aws provider on the module registry published from the Github organization my-gh-repo-org:

$ curl https://registry.terraform.io/v1/modules/my-gh-repo-org/consul/aws/versions
$ curl https://registry.terraform.io/v1/modules/my-gh-repo-org/consul/aws/versions

The same request for the same module and provider on the Terraform Cloud module registry for the my-cloud-org organization:

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

»Sample Proxy Request (public module)

List available versions for the consul module for the aws provider on the module registry published from the Github organization my-gh-repo-org:

$ curl https://registry.terraform.io/v1/modules/my-gh-repo-org/consul/aws/versions
$ curl https://registry.terraform.io/v1/modules/my-gh-repo-org/consul/aws/versions

The same request for the same module and provider on the Terraform Cloud module registry:

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

»List Registry Modules for an Organization

GET /organizations/:organization_name/registry-modules

ParameterDescription
:organization_nameThe name of the organization to list available modules from.

Lists the modules that are available to a given organization. This includes the full list of publicly curated and private modules and is filterable.

StatusResponseReason
200JSON API document (type: "registry-modules")The request was successful
404JSON API error objectModules not found or user unauthorized to perform action

»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.

ParameterDescription
qOptional. 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.

»Sample Request

curl \
  --request GET \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules
curl \
  --request GET \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules

»Sample Response

{
  "data": [
    {
      "id": "mod-kwt1cBiX2SdDz38w",
      "type": "registry-modules",
      "attributes": {
        "name": "api-gateway",
        "namespace": "my-organization",
        "provider": "alicloud",
        "status": "setup_complete",
        "version-statuses": [
          {
            "version": "1.1.0",
            "status": "ok"
          }
        ],
        "created-at": "2021-04-07T19:01:18.528Z",
        "updated-at": "2021-04-07T19:01:19.863Z",
        "registry-name": "private",
        "permissions": {
          "can-delete": true,
          "can-resync": true,
          "can-retry": true
        }
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          }
        }
      },
      "links": {
        "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/api-gateway/alicloud"
      }
    },
    {
      "id": "mod-PopQnMtYDCcd3PRX",
      "type": "registry-modules",
      "attributes": {
        "name": "aurora",
        "namespace": "my-organization",
        "provider": "aws",
        "status": "setup_complete",
        "version-statuses": [
          {
            "version": "4.1.0",
            "status": "ok"
          }
        ],
        "created-at": "2021-04-07T19:04:41.375Z",
        "updated-at": "2021-04-07T19:04:42.828Z",
        "registry-name": "private",
        "permissions": {
          "can-delete": true,
          "can-resync": true,
          "can-retry": true
        }
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          }
        }
      },
      "links": {
        "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/aurora/aws"
      }
    },
    ...,
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=1&page%5Bsize%5D=6",
    "first": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=1&page%5Bsize%5D=6",
    "prev": null,
    "next": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=2&page%5Bsize%5D=6",
    "last": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=29&page%5Bsize%5D=6"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 6,
      "prev-page": null,
      "next-page": 2,
      "total-pages": 29,
      "total-count": 169
    }
  }
}
{
  "data": [
    {
      "id": "mod-kwt1cBiX2SdDz38w",
      "type": "registry-modules",
      "attributes": {
        "name": "api-gateway",
        "namespace": "my-organization",
        "provider": "alicloud",
        "status": "setup_complete",
        "version-statuses": [
          {
            "version": "1.1.0",
            "status": "ok"
          }
        ],
        "created-at": "2021-04-07T19:01:18.528Z",
        "updated-at": "2021-04-07T19:01:19.863Z",
        "registry-name": "private",
        "permissions": {
          "can-delete": true,
          "can-resync": true,
          "can-retry": true
        }
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          }
        }
      },
      "links": {
        "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/api-gateway/alicloud"
      }
    },
    {
      "id": "mod-PopQnMtYDCcd3PRX",
      "type": "registry-modules",
      "attributes": {
        "name": "aurora",
        "namespace": "my-organization",
        "provider": "aws",
        "status": "setup_complete",
        "version-statuses": [
          {
            "version": "4.1.0",
            "status": "ok"
          }
        ],
        "created-at": "2021-04-07T19:04:41.375Z",
        "updated-at": "2021-04-07T19:04:42.828Z",
        "registry-name": "private",
        "permissions": {
          "can-delete": true,
          "can-resync": true,
          "can-retry": true
        }
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          }
        }
      },
      "links": {
        "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/aurora/aws"
      }
    },
    ...,
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=1&page%5Bsize%5D=6",
    "first": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=1&page%5Bsize%5D=6",
    "prev": null,
    "next": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=2&page%5Bsize%5D=6",
    "last": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=29&page%5Bsize%5D=6"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 6,
      "prev-page": null,
      "next-page": 2,
      "total-pages": 29,
      "total-count": 169
    }
  }
}

»Publish a Private Module from a VCS

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

ParameterDescription
:organization_nameThe 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.

StatusResponseReason
201JSON API document (type: "registry-modules")Successfully published module
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
404JSON API error objectUser not authorized

»Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringMust be "registry-modules".
data.attributes.vcs-repo.identifierstringThe repository from which to ingress the configuration.
data.attributes.vcs-repo.oauth-token-idstringThe VCS Connection (OAuth Connection + Token) to use as identified. This ID can be obtained from the oauth-tokens endpoint.
data.attributes.vcs-repo.display_identifierstringThe 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.

»Sample Payload

{
  "data": {
    "attributes": {
      "vcs-repo": {
        "identifier":"lafentres/terraform-aws-my-module",
        "oauth-token-id":"ot-hmAyP66qk2AMVdbJ",
        "display_identifier":"lafentres/terraform-aws-my-module"
      }
    },
    "type":"registry-modules"
  }
}
{
  "data": {
    "attributes": {
      "vcs-repo": {
        "identifier":"lafentres/terraform-aws-my-module",
        "oauth-token-id":"ot-hmAyP66qk2AMVdbJ",
        "display_identifier":"lafentres/terraform-aws-my-module"
      }
    },
    "type":"registry-modules"
  }
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/vcs
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/vcs

»Sample Response

{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "my-module",
      "namespace": "my-organization",
      "registry-name": "private",
      "provider": "aws",
      "status": "pending",
      "version-statuses": [],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T19:36:56.288Z",
      "vcs-repo": {
        "branch": "",
        "ingress-submodules": true,
        "identifier": "lafentres/terraform-aws-my-module",
        "display-identifier": "lafentres/terraform-aws-my-module",
        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
        "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..."
      },
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws"
    }
  }
}
{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "my-module",
      "namespace": "my-organization",
      "registry-name": "private",
      "provider": "aws",
      "status": "pending",
      "version-statuses": [],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T19:36:56.288Z",
      "vcs-repo": {
        "branch": "",
        "ingress-submodules": true,
        "identifier": "lafentres/terraform-aws-my-module",
        "display-identifier": "lafentres/terraform-aws-my-module",
        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
        "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..."
      },
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws"
    }
  }
}

»Create a Module (with no VCS connection)

POST /organizations/:organization_name/registry-modules

ParameterDescription
:organization_nameThe 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.

»Private modules

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.

»Public modules

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.

StatusResponseReason
201JSON API document (type: "registry-modules")Successfully published module
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
403JSON API error objectForbidden - public module curation disabled
404JSON API error objectUser not authorized

»Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringMust be "registry-modules".
data.attributes.namestringThe 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.providerstringSpecifies the Terraform provider that this module is used for. May contain lowercase alphanumeric characters. Maximum length is 64 characters.
data.attributes.namespacestringThe 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-namestringIndicates whether this is a publicly maintained module or private. Must be either public or private.

»Sample Payload (private module)

{
  "data": {
    "type": "registry-modules",
    "attributes": {
      "name": "my-module",
      "provider": "aws",
      "registry-name": "private"
    }
  }
}
{
  "data": {
    "type": "registry-modules",
    "attributes": {
      "name": "my-module",
      "provider": "aws",
      "registry-name": "private"
    }
  }
}

»Sample Payload (public module)

{
  "data": {
    "type": "registry-modules",
    "attributes": {
      "name": "vpc",
      "namespace": "terraform-aws-modules",
      "provider": "aws",
      "registry-name": "public"
    }
  }
}
{
  "data": {
    "type": "registry-modules",
    "attributes": {
      "name": "vpc",
      "namespace": "terraform-aws-modules",
      "provider": "aws",
      "registry-name": "public"
    }
  }
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules

»Sample Response (private module)

{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "my-module",
      "namespace": "my-organization",
      "registry-name": "private",
      "provider": "aws",
      "status": "pending",
      "version-statuses": [],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T19:36:56.288Z",
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws"
    }
  }
}
{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "my-module",
      "namespace": "my-organization",
      "registry-name": "private",
      "provider": "aws",
      "status": "pending",
      "version-statuses": [],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T19:36:56.288Z",
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws"
    }
  }
}

»Sample Response (public module)

{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "vpc",
      "namespace": "terraform-aws-modules",
      "registry-name": "public",
      "provider": "aws",
      "status": "pending",
      "version-statuses": [],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T19:36:56.288Z",
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws"
    }
  }
}
{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "vpc",
      "namespace": "terraform-aws-modules",
      "registry-name": "public",
      "provider": "aws",
      "status": "pending",
      "version-statuses": [],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T19:36:56.288Z",
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws"
    }
  }
}

»Create a Module Version

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

ParameterDescription
:organization_nameThe 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.
:namespaceThe namespace of the module for which the version is being created. For private modules this is the same as the :organization_name parameter
:nameThe name of the module for which the version is being created.
:providerThe name of the provider for which the version is being created.
:registry-nameMust 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.

StatusResponseReason
201JSON API document (type: "registry-module-versions")Successfully published module version
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
403JSON API error objectForbidden - not available for public modules
404JSON API error objectUser not authorized

»Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringMust be "registry-module-versions".
data.attributes.versionstringA valid semver version string.

»Sample Payload

{
  "data": {
    "type": "registry-module-versions",
    "attributes": {
      "version": "1.2.3"
    }
  }
}
{
  "data": {
    "type": "registry-module-versions",
    "attributes": {
      "version": "1.2.3"
    }
  }
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws/versions
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws/versions

»Sample Response

{
  "data": {
    "id": "modver-qjjF7ArLXJSWU3WU",
    "type": "registry-module-versions",
    "attributes": {
      "source": "tfe-api",
      "status": "pending",
      "version": "1.2.3",
      "created-at": "2018-09-24T20:47:20.931Z",
      "updated-at": "2018-09-24T20:47:20.931Z"
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "1881",
          "type": "registry-modules"
        }
      }
    },
    "links": {
      "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..."
    }
  }
}
{
  "data": {
    "id": "modver-qjjF7ArLXJSWU3WU",
    "type": "registry-module-versions",
    "attributes": {
      "source": "tfe-api",
      "status": "pending",
      "version": "1.2.3",
      "created-at": "2018-09-24T20:47:20.931Z",
      "updated-at": "2018-09-24T20:47:20.931Z"
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "1881",
          "type": "registry-modules"
        }
      }
    },
    "links": {
      "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..."
    }
  }
}

»Add a Module Version (Private Module)

PUT https://archivist.terraform.io/v1/object/<UNIQUE OBJECT ID>

The URL is provided in the upload links attribute in the registry-module-versions resource.

»Expected Archive Format

Terraform Cloud expects the module version uploaded to be a tarball with the module in the root (not in a subdirectory).

Given the following folder structure:

terraform-null-test
├── README.md
├── examples
│   └── default
│       ├── README.md
│       └── main.tf
└── main.tf
terraform-null-test
├── README.md
├── examples
│   └── default
│       ├── README.md
│       └── main.tf
└── main.tf

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

»Sample Request

curl \
  --header "Content-Type: application/octet-stream" \
  --request PUT \
  --data-binary @module.tar.gz \
  https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox...
curl \
  --header "Content-Type: application/octet-stream" \
  --request PUT \
  --data-binary @module.tar.gz \
  https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox...

After the registry module version is successfully parsed, its status will become "ok".

»Get a Module

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

»Parameters

ParameterDescription
:organization_nameThe name of the organization the module belongs to.
:namespaceThe namespace of the module. For private modules this is the name of the organization that owns the module.
:nameThe module name.
:providerThe module provider. Must be lowercase alphanumeric.
:registry-nameEither public or private.
StatusResponseReason
200JSON API document (type: "registry-modules")The request was successful
403JSON API error objectForbidden - public module curation disabled
404JSON API error objectModule not found or user unauthorized to perform action

»Sample Request (private module)

curl \
  --request GET \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws
curl \
  --request GET \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws

»Sample Request (public module)

curl \
  --request GET \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws
curl \
  --request GET \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws

»Sample Response (private module)

{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "my-module",
      "provider": "aws",
      "namespace": "my-organization",
      "registry-name": "private",
      "status": "setup_complete",
      "version-statuses": [
        {
          "version": "1.0.0",
          "status": "ok"
        }
      ],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T20:16:20.538Z",
      "vcs-repo": {
        "branch": "",
        "ingress-submodules": true,
        "identifier": "lafentres/terraform-aws-my-module",
        "display-identifier": "lafentres/terraform-aws-my-module",
        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
        "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..."
      },
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws"
    }
  }
}
{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "my-module",
      "provider": "aws",
      "namespace": "my-organization",
      "registry-name": "private",
      "status": "setup_complete",
      "version-statuses": [
        {
          "version": "1.0.0",
          "status": "ok"
        }
      ],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T20:16:20.538Z",
      "vcs-repo": {
        "branch": "",
        "ingress-submodules": true,
        "identifier": "lafentres/terraform-aws-my-module",
        "display-identifier": "lafentres/terraform-aws-my-module",
        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
        "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..."
      },
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws"
    }
  }
}

»Sample Response (public module)

{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "vpc",
      "provider": "aws",
      "namespace": "terraform-aws-modules",
      "registry-name": "public",
      "status": "setup_complete",
      "version-statuses": [],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T20:16:20.538Z",
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws"
    }
  }
}
{
  "data": {
    "id": "mod-fZn7uHu99ZCpAKZJ",
    "type": "registry-modules",
    "attributes": {
      "name": "vpc",
      "provider": "aws",
      "namespace": "terraform-aws-modules",
      "registry-name": "public",
      "status": "setup_complete",
      "version-statuses": [],
      "created-at": "2020-07-09T19:36:56.288Z",
      "updated-at": "2020-07-09T20:16:20.538Z",
      "permissions": {
        "can-delete": true,
        "can-resync": true,
        "can-retry": true
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws"
    }
  }
}

»Delete a Module

**Deprecation warning**: the following endpoints:
  • POST /registry-modules/actions/delete/:organization_name/:name/:provider/:version
  • POST /registry-modules/actions/delete/:organization_name/:name/:provider
  • POST /registry-modules/actions/delete/:organization_name/:name

are replaced by the below endpoints and will be removed from future versions of the API!

  • DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/:version
  • DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider
  • DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name

»Parameters

ParameterDescription
:organization_nameThe 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.
:namespaceThe module namespace that the deletion will affect. For private modules this is the name of the organization that owns the module.
:nameThe module name that the deletion will affect.
:providerIf specified, the provider for the module that the deletion will affect.
:versionIf specified, the version for the module and provider that will be deleted.
:registry_nameEither 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.

StatusResponseReason
204NothingSuccess
403JSON API error objectForbidden - public module curation disabled
404JSON API error objectModule, provider, or version not found or user not authorized

»Sample Request (private module)

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws/2.0.0
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws/2.0.0

»Sample Request (public module)

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws
github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager