HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

Stack component configurations API reference

Publish a Stack component configuration to the HCP Terraform private registry to share Stacks across your organization. When you publish a component configuration, other teams can use it to create a Stack by defining a stack block in their own <NAME>.tfcomponent.hcl file.

Refer to Publish a Stack to learn more publishing a Stack component configuration. To learn more about Stacks, refer to the Stacks overview.

Overview

The following table lists all the endpoints for managing Stack component configurations in your organization's private registry:

MethodPathAction
GET/organizations/:organization_name/registry-componentsList Stack component configurations for an organization.
POST/organizations/:organization_name/registry-componentsCreate a Stack component configuration, with or without VCS.
POST/api/v2/registry-components/:component_id/versionsCreate a new version of a Stack component configuration.
PUThttps://archivist.terraform.io/v1/object/<UNIQUE_OBJECT_ID>Add a Stack component configuration version.
GET/api/v2/registry-components/:component_idGet details about a Stack component configuration.
DELETE/api/v2/registry-components/:component_id/versions/:versionDelete a specific version of a Stack component configuration.
DELETE/api/v2/registry-components/:component_idDelete an entire Stack component configuration.

List Stack component configurations for an organization

GET /organizations/:organization_name/registry-components

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

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. Component configurations are searchable by name and namespace fields.
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 component configurations per page.

Sample request

The following example request lists Stack component configurations for the my-organization organization:

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

Sample response

The following response example lists Stack component configurations for the my-organization organization:

{
  "data": [
    {
      "id": "comp-wed33EBTz4w8XeSS",
      "type": "registry-components",
      "attributes": {
        "name": "hashibank-app-security",
        "namespace": "my-organization",
        "description": "Stack component configuration for HashiBank application security",
        "status": "completed",
        "created-at": "2024-11-11T11:20:21Z",
        "updated-at": "2024-11-11T11:20:24Z",
        "latest-version": "1.0.0",
        "published-at": "2024-11-11T11:20:30.126135Z",
        "providers": [
          {
            "name": "aws",
            "namespace": "hashicorp",
            "source": "hashicorp/aws"
          }
        ]
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "org-rT5Smhs7tBfjGnsZ",
            "type": "organizations"
          }
        }
      },
      "links": {
        "self": "/api/v2/registry-components/comp-wed33EBTz4w8XeSS"
      }
    },
    {
      "id": "comp-hGqAHmU28NE2hnjA",
      "type": "registry-components",
      "attributes": {
        "name": "eks-cluster",
        "namespace": "my-organization",
        "description": "Stack component configuration for EKS cluster setup",
        "status": "completed",
        "created-at": "2024-11-26T13:45:28Z",
        "updated-at": "2024-11-26T13:45:30Z",
        "latest-version": "1.0.5",
        "published-at": "2024-11-26T13:45:33.719842Z",
        "providers": [
          {
            "name": "aws",
            "namespace": "hashicorp",
            "source": "hashicorp/aws"
          },
          {
            "name": "random",
            "namespace": "hashicorp",
            "source": "hashicorp/random"
          }
        ]
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "org-rT5Smhs7tBfjGnsZ",
            "type": "organizations"
          }
        }
      },
      "links": {
        "self": "/api/v2/registry-components/comp-hGqAHmU28NE2hnjA"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/organizations/my-organization/registry-components?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/organizations/my-organization/registry-components?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/organizations/my-organization/registry-components?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 2
    }
  }
}

Create a Stack component configuration

POST /organizations/:organization_name/registry-components

ParameterDescription
:organization_nameThe name of the organization to create a component configuration in. The organization must already exist, and the token authenticating the API request must belong to a team member with Manage Stack component configurations permissions.

You can use this endpoint to publish a component configuration using the API-only workflow or VCS-backed workflow.

StatusResponseReason
201JSON API document (type: "registry-components")Successfully published component configuration
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
404JSON API error objectNot found, or the user is unauthorized to perform this action.

VCS-backed workflow

VCS-backed publishing sources a component configuration directly from a VCS repository. The publishing process fetches all SemVer version tags with the optional v prefix.

For each version, HCP Terraform clones the tag and parses the configuration to create different versions of the component configuration. Each component configuration version details the required input and output variables, README documentation, providers, and other related information.

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-components".
data.attributes.namestring(optional)The name of this component configuration. If not specified, HCP Terraform uses the repository name. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters.
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. Get this ID from the oauth-tokens endpoint. You can not specify this value if github-app-installation-id is specified.
data.attributes.vcs-repo.github-app-installation-idstringThe GitHub App installation connection to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from Account Settings within HCP Terraform. You can not specify this value if oauth-token-id is specified.
data.attributes.vcs-repo.display_identifierstringThe display identifier for the repository. For most VCS providers outside of Bitbucket Cloud, this identifier matches the data.attributes.vcs-repo.identifier string.
data.attributes.vcs-repo.source-directorystring(optional)The directory in the repository where the component configuration is located. Useful for monorepo setups where multiple component configurations exist in different directories.
data.attributes.vcs-repo.tag-prefixstring(optional)A prefix to filter tags for versioning. Only tags matching this prefix will be considered as versions. Useful for monorepo setups where multiple component configurations share the same repository but use different tag prefixes.

A VCS repository identifier, data.attributes.vcs-repo.identifier, is a reference to your VCS repository. Use the syntax :org/:repo, where :org and :repo refer to the organization and repository in your VCS provider. If you are using Bitbucket Data Center, use the syntax :project_key/:repo. If you are using Azure DevOps, use the syntax :org/:project/_git/:repo.

The OAuth token ID identifies the VCS connection, and therefore the organization, that HCP Terraform creates the component configuration in.

Sample payload

The following example payload sources a VCS-backed component configuration from the my-org organization in the terraform-component-eks-cluster repository:

{
  "data": {
    "type": "registry-components",
    "attributes": {
      "vcs-repo": {
        "identifier": "my-org/terraform-component-eks-cluster",
        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
        "display_identifier": "my-org/terraform-component-eks-cluster",
      }
    }
  }
}

The following example payload sources a VCS-backed component configuration from the my-org organization in the hashibank-monorepo repository with a source directory and tag prefix:

{
  "data": {
    "type": "registry-components",
    "attributes": {
      "name": "hashibank-app-security",
      "vcs-repo": {
        "identifier": "my-org/hashibank-monorepo",
        "github-app-installation-id": "ghain-abc123xyz456",
        "source-directory": "components/security",
        "tag-prefix": "security/"
      }
    }
  }
}

Sample response

The following example response body returns the VCS-backed component configuration's details:

{
  "data": {
    "id": "comp-UnpBkfLQJZUXARc6",
    "type": "registry-components",
    "attributes": {
      "name": "hashibank-app-security",
      "namespace": "my-organization",
      "status": "completed",
      "created-at": "2024-12-03T10:31:53Z",
      "updated-at": "2024-12-03T10:31:53Z",
      "version-statuses": [
        {
          "version": "1.0.0",
          "status": "completed"
        }
      ],
      "vcs-repo": {
        "identifier": "my-org/hashibank-app-security",
        "display-identifier": "my-org/hashibank-app-security",
        "source-directory": null,
        "tag-prefix": null,
        "oauth-token-id": "ot-eNzYfKyB11MMTqEx"
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "org-rT5Smhs7tBfjGnsZ",
          "type": "organizations"
        }
      },
      "registry-component-versions": {
        "links": {
          "related": "/api/v2/registry-components/comp-UnpBkfLQJZUXARc6/versions"
        }
      }
    },
    "links": {
      "self": "/api/v2/registry-components/comp-UnpBkfLQJZUXARc6"
    }
  }
}

API-only workflow

API-only publishing creates a component configuration without a backing VCS repository. After creating the component configuration, you must explicitly create and upload subsequent versions using the Create a component configuration version endpoint.

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-components".
data.attributes.namestringThe name of this component configuration. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters.

Sample payload

The following example payload creates an API-only component configuration named eks-cluster:

{
  "data": {
    "type": "registry-components",
    "attributes": {
      "name": "eks-cluster"
    }
  }
}

Sample request

The following example request creates an API-only component configuration in the my-organization organization:

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-components

Sample response

The following example response body returns the API-only component configuration's details:

{
  "data": {
    "id": "comp-fZn7uHu99ZCpAKZJ",
    "type": "registry-components",
    "attributes": {
      "name": "eks-cluster",
      "namespace": "my-organization",
      "status": "pending",
      "created-at": "2024-01-15T19:36:56.288Z",
      "updated-at": "2024-01-15T19:36:56.288Z",
      "version-statuses": []
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "org-rT5Smhs7tBfjGnsZ",
          "type": "organizations"
        }
      },
      "registry-component-versions": {
        "links": {
          "related": "/api/v2/registry-components/comp-fZn7uHu99ZCpAKZJ/versions"
        }
      }
    },
    "links": {
      "self": "/api/v2/registry-components/comp-fZn7uHu99ZCpAKZJ"
    }
  }
}

Create a component configuration version

POST /api/v2/registry-components/:component_id/versions

ParameterDescription
:component_idThe ID of the component configuration to create, such as comp-UnpBkfLQJZUXARc6. The token authenticating the API request must belong to a team member with Manage Stack component configurations permissions.

Creates a new version for component configurations that do not source from a VCS repository. VCS-backed component configurations automatically create new versions for new tags. After creating a version for an API-published component configuration, you can upload subsequent configurations to the link that HCP Terraform returns.

StatusResponseReason
201JSON API document (type: "registry-component-versions")Successfully published component configuration version
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
404JSON API error objectNot found, or the user is unauthorized to perform this action.

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-component-versions".
data.attributes.versionstringA valid SemVer version string.

Sample payload

The following example payload creates a component configuration version for 1.2.3:

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

Sample request

The following example request creates a new version for the comp-UnpBkfLQJZUXARc6 component configuration:

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/registry-components/comp-UnpBkfLQJZUXARc6/versions

Sample response

The following example response body returns the details of the new component configuration version:

{
  "data": {
    "id": "compver-Ecdq2uaNUXNHNHcA",
    "type": "registry-component-versions",
    "attributes": {
      "source": "api",
      "status": "pending",
      "version": "1.0.0",
      "readme": null,
      "description": null,
      "published-at": null,
      "error-message": null,
      "source-url": null
    },
    "relationships": {
      "registry-component": {
        "links": {
          "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY"
        }
      },
      "resources": {
        "links": {
          "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/resources"
        }
      },
      "variables": {
        "links": {
          "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/variables"
        }
      },
      "outputs": {
        "links": {
          "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/outputs"
        }
      },
      "providers": {
        "links": {
          "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/providers"
        }
      },
      "subcomponents": {
        "links": {
          "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/subcomponents"
        }
      }
    },
    "links": {
      "self": "/api/v2/registry-components/compver-Ecdq2uaNUXNHNHcA/versions/1.0.0",
      "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6Q1JjVWM5ZHBFRXZzdWZTKy80NUh3bDRMREd4QkxRaXZ0bXE3QXYzRHFMcFE0NVVhVmRmSE43K0dTUlp1aUsxQ253VmN6SFoyM1pLWU4vbGxsVW8wUkh4UzZ3S1ZmYXljRHhKM1gxR0RIdTJiSlNMbGYzYmo5ejVlUHZPQlArRUJHa1h3WUFLemhuOUhsS3pXZnRvbHppbVJYZEJCUjl6TlZLdEhqT29DdjY4U3RQRW51MkptTCsvUUlWK2xKNDhjK2NaT1JCbjNLYWtGZFh1UGtJL2V4YVFYbjVEVXdScEpJNzdrR2ZKSXgvNjd6UkVEZDBDZElBQnljK0Y2YnhVeUpUV1BvRWdkY0hPajhyWHdKNW1QTS93bnNHK0lSSUVoQ05OTGJaR09MMnRzeHl4ZzBST2VVaG9PQzV6YjR5WXprU0REMldPSUxTV0xRVlBRbldvaGtRVUFtUWU3QitrWERoOUUwaFczOG1rTG4xc21KZ240ZU40PQ"
    }
  }
}

Add a component configuration version

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

HCP Terraform provides a URL in the upload links attribute in the registry-component-versions resource.

Expected archive format

HCP Terraform expects the component configuration version uploaded to be a gzip tarball with the component configuration in the root directory.

Given the following example folder structure:

terraform-component-eks-cluster
├── README.md
├── examples
│   └── default
│       ├── README.md
│       └── main.tf
└── components.tfcomponent.hcl

Package the files in an archive format by running tar zcvf component.tar.gz * in the component configuration's directory:

$ cd terraform-component-eks-cluster
terraform-component-eks-cluster
$ tar zcvf component.tar.gz *
a README.md
a examples
a examples/default
a examples/default/main.tf
a examples/default/README.md
a components.tfcomponent.hcl

Sample request

The following example request uploads a component configuration version archive:

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

After the Stack component configuration version is successfully parsed, its status changes to "completed".

Get a Stack component configuration

GET /api/v2/registry-components/:component_id

Parameters

ParameterDescription
:component_idThe ID of the component configuration to retrieve, such as comp-7GjfsTX1Yc5E1boD.
StatusResponseReason
200JSON API document (type: "registry-components")The request was successful
404JSON API error objectNot found, or the user is unauthorized to perform this action.

Sample request

The following example request gets details about a Stack component configuration:

curl \
  --request GET \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/registry-components/comp-7GjfsTX1Yc5E1boD

Sample response for an API-published configuration

The following example response body returns an API-published component configuration's details:

{
  "data": {
    "id": "comp-7GjfsTX1Yc5E1boD",
    "type": "registry-components",
    "attributes": {
      "name": "test-stacks-1764762762",
      "namespace": "hashicorp",
      "status": "completed",
      "created-at": "2025-12-03T11:52:43Z",
      "updated-at": "2025-12-03T11:52:44Z",
      "version-statuses": [
        {
          "version": "1.0.0",
          "status": "completed"
        }
      ],
      "vcs-repo": null
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "org-rT5Smhs7tBfjGnsZ",
          "type": "organizations"
        }
      },
      "registry-component-versions": {
        "links": {
          "related": "/api/v2/registry-components/comp-7GjfsTX1Yc5E1boD/versions"
        }
      }
    },
    "links": {
      "self": "/api/v2/registry-components/comp-7GjfsTX1Yc5E1boD"
    }
  }
}

Sample response for a VCS-backed configuration

The following example response body returns the VCS-backed component configuration's details:

{
  "data": {
    "id": "comp-UnpBkfLQJZUXARc6",
    "type": "registry-components",
    "attributes": {
      "name": "hashibank-app-security",
      "namespace": "my-organization",
      "status": "completed",
      "created-at": "2024-12-03T10:31:53Z",
      "updated-at": "2024-12-03T10:31:53Z",
      "version-statuses": [
        {
          "version": "1.0.0",
          "status": "completed"
        },
        {
          "version": "1.1.0",
          "status": "completed"
        }
      ],
      "vcs-repo": {
        "identifier": "my-org/hashibank-app-security",
        "display-identifier": "my-org/hashibank-app-security",
        "source-directory": "components/security",
        "tag-prefix": "security/",
        "oauth-token-id": "ot-eNzYfKyB11MMTqEx"
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "org-rT5Smhs7tBfjGnsZ",
          "type": "organizations"
        }
      },
      "registry-component-versions": {
        "links": {
          "related": "/api/v2/registry-components/comp-UnpBkfLQJZUXARc6/versions"
        }
      }
    },
    "links": {
      "self": "/api/v2/registry-components/comp-UnpBkfLQJZUXARc6"
    }
  }
}

Delete a component configuration version

DELETE /api/v2/registry-components/:component_id/versions/:version

ParameterDescription
:component_idThe ID of the version of the component configuration to delete, such as comp-jKXTSGwC8uV6vACK. The token authenticating the API request must belong to a team member with Manage Stack component configurations permissions.
:versionThe version number to delete, such as 2.0.0.

You can delete a specific version of a component configuration, or the entire component configuration. This endpoint deletes a specific version of a component configuration from your private registry.

StatusResponseReason
204No ContentSuccess
404JSON API error objectNot found, or the user is unauthorized to perform this action.

Sample request

The following example request deletes a specific version of a component configuration:

curl \
  --request DELETE \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/registry-components/comp-jKXTSGwC8uV6vACK/versions/2.0.0

Delete a Stack component configuration

DELETE /api/v2/registry-components/:component_id

ParameterDescription
:component_idThe ID of the version of the component configuration to delete, such as comp-jKXTSGwC8uV6vACK. The token authenticating the API request must belong to a team member with Manage Stack component configurations permissions.

You can delete a specific version of a component configuration, or the entire component configuration. This endpoint deletes the entire component configuration from your private registry.

StatusResponseReason
204No ContentSuccess
404JSON API error objectNot found, or the user is unauthorized to perform this action.

Sample request

The following example deletes an entire component configuration from the private registry:

curl \
  --request DELETE \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/registry-components/comp-YF7Avu8dHpJev9Cc
Edit this page on GitHub