diff --git a/content/terraform-docs-common/data/cloud-docs-nav-data.json b/content/terraform-docs-common/data/cloud-docs-nav-data.json index 2251ba1d76..f030a092b7 100644 --- a/content/terraform-docs-common/data/cloud-docs-nav-data.json +++ b/content/terraform-docs-common/data/cloud-docs-nav-data.json @@ -24,7 +24,7 @@ { "title": "Get started", "href": "https://learn.hashicorp.com/collections/terraform/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS" - }, + }, { "title": "Migrate to HCP Terraform", "path": "migrate" @@ -803,7 +803,8 @@ "path": "api-docs/private-registry/provider-versions-platforms" }, { "title": "GPG keys", "path": "api-docs/private-registry/gpg-keys" }, - { "title": "Tests", "path": "api-docs/private-registry/tests" } + { "title": "Tests", "path": "api-docs/private-registry/tests" }, + { "title": "Stack Component Configurations", "path": "api-docs/private-registry/stack-component-configurations" } ] }, { "title": "Projects", "path": "api-docs/projects" }, diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/private-registry/stack-component-configurations.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/private-registry/stack-component-configurations.mdx new file mode 100644 index 0000000000..3fa2a957fa --- /dev/null +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/private-registry/stack-component-configurations.mdx @@ -0,0 +1,689 @@ +--- +page_title: Stack Component Configurations API reference for HCP Terraform +description: >- + Use the HCP Terraform API's `/registry-components` endpoint to read, publish, update, delete, and add versions to Stack component configurations in your organization's private registry. +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/cloud-docs/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# 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 referencing it in a `stack` block in their own `.tfcomponent.hcl` file. Refer to [Use artifacts from the HCP Terraform private registry](/terraform/cloud-docs/registry/using#use-a-stack-component-configuration) to learn more about using the `stack` block. To learn more about Stacks, refer to the [Stacks overview](/terraform/cloud-docs/stacks). + +This page documents the API endpoints for managing Stack component configurations in your organization's private registry. + +## Overview + +The scope of the API includes the following endpoints: + +| Method | Path | Action | +|--------|------|--------| +| GET | `/organizations/:organization_name/registry-components` | [List Stack component configurations](#list-stack-component-configurations-for-an-organization) for an organization. | +| POST | `/organizations/:organization_name/registry-components` | [Create a Stack component configuration](#create-a-stack-component-configuration) (with or without VCS). | +| POST | `/api/v2/registry-components/:component_id/versions` | [Create a new version](#create-a-stack-component-configuration-version) of a Stack component configuration. | +| PUT | `https://archivist.terraform.io/v1/object/` | [Upload a Stack component configuration version archive](#add-a-stack-component-configuration-version). | +| GET | `/api/v2/registry-components/:component_id` | [Get details](#get-a-stack-component-configuration) of a Stack component configuration. | +| DELETE | `/api/v2/registry-components/:component_id/versions/:version` | [Delete a specific version](#delete-a-stack-component-configuration) of a Stack component configuration. | +| DELETE | `/api/v2/registry-components/:component_id` | [Delete an entire Stack component configuration](#delete-a-stack-component-configuration). | + +## List Stack Component Configurations for an Organization + +`GET /organizations/:organization_name/registry-components` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to list available component configurations from. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/cloud-docs/api-docs#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. 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 + +```shell +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 + +```json +{ + "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` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The 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 or team member with the **Manage Stack Component Configurations** permission enabled. | + +Creates a new Stack component configuration. This endpoint supports two publishing modes: + +**VCS-backed**: Publishes a component configuration from a VCS repository, with 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 configuration is parsed to populate component configuration details (input and output variables, readme, providers, etc.). + +**API-only**: Creates a component configuration without a backing VCS repository. After creating the component configuration, you must explicitly create and upload each version using the Create a Stack Component Configuration Version endpoint. + +| Status | Response | Reason | +| ------- | ----------------------------------------------------------- | ------------------------------------------------------------ | +| [201][] | [JSON API document][] (`type: "registry-components"`) | Successfully published component configuration | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [404][] | [JSON API error object][] | Not 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. + +**For VCS-backed component configurations:** + +| Key path | Type | Default | Description | +| ------------------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"registry-components"`. | +| `data.attributes.name` | string | (optional) | The name of this component configuration. If not specified, the name will be derived from 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.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. 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-id` | string | | The VCS Connection GitHub App Installation 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_identifier` | string | | The 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-directory` | string | (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-prefix` | string | (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 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 Data Center, 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 component configuration will be created in. + +**For API-only component configurations:** + +| Key path | Type | Default | Description | +| --------------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-components"`. | +| `data.attributes.name`| string | | The 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 (VCS-backed) + +**Basic VCS configuration:** + +```json +{ + "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", + } + } + } +} +``` + +**Monorepo configuration with source directory and tag prefix:** + +```json +{ + "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 Payload (API-only) + +```json +{ + "data": { + "type": "registry-components", + "attributes": { + "name": "eks-cluster" + } + } +} +``` + +### Sample Request + +```shell +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 (VCS-backed) + +```json +{ + "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" + } + } +} +``` + +### Sample Response (API-only) + +```json +{ + "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 Stack Component Configuration Version + +`POST /api/v2/registry-components/:component_id/versions` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:component_id` | The ID of the component configuration for which the version is being created (e.g., `comp-UnpBkfLQJZUXARc6`). The token authenticating the API request must belong to a team or team member with the **Manage Stack Component Configurations** permission enabled. | + +Creates a new registry component configuration version. This endpoint only applies to private component configurations without a VCS repository. VCS-backed Stack component configurations automatically create new versions for new tags. After creating the version for an API-only component configuration, you should upload the component configuration to the link that HCP Terraform returns. + +| Status | Response | Reason | +| ------- | --------------------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-component-versions"`) | Successfully published component configuration version | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [404][] | [JSON API error object][] | Not 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 path | Type | Default | Description | +| ------------------------------ | ------ | ------- | -------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-component-versions"`. | +| `data.attributes.version` | string | | A valid semver version string. | + +### Sample Payload + +```json +{ + "data": { + "type": "registry-component-versions", + "attributes": { + "version": "1.2.3" + } + } +} +``` + +### Sample Request + +```shell +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 + +```json +{ + "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 Stack Component Configuration Version + +`PUT https://archivist.terraform.io/v1/object/` + +**The URL is provided 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 (not in a subdirectory). + +Given the following 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 + +```shell +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 will become `"completed"`. + +## Get a Stack Component Configuration + +`GET /api/v2/registry-components/:component_id` + +### Parameters + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------- | +| `:component_id` | The ID of the component configuration to retrieve (e.g., `comp-7GjfsTX1Yc5E1boD`). | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-components"`) | The request was successful | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | + +### Sample Request + +```shell +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 (API-only) + +```json +{ + "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 (VCS-backed) + +```json +{ + "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 Stack Component Configuration + +Thereis endpoint supports two deletion modes: + +**Delete a specific version:** +`DELETE /api/v2/registry-components/:component_id/versions/:version` + +**Delete entire component configuration:** +`DELETE /api/v2/registry-components/:component_id` + +### Parameters + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:component_id` | The ID of the component configuration to delete (e.g., `comp-jKXTSGwC8uV6vACK`). The token authenticating the API request must belong to a team or team member with the **Manage Stack Component Configurations** permission enabled. | +| `:version` | **(For version deletion only)** The version number to delete (e.g., `2.0.0`). | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------ | +| [204][] | No Content | Success | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | + +### Sample Request (Delete a specific version) + +```shell +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 +``` + +### Sample Request (Delete entire component configuration) + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/registry-components/comp-YF7Avu8dHpJev9Cc +``` diff --git a/content/terraform-enterprise/1.0.x/data/enterprise-nav-data.json b/content/terraform-enterprise/1.0.x/data/enterprise-nav-data.json index 155eb8ceef..09af5d041c 100644 --- a/content/terraform-enterprise/1.0.x/data/enterprise-nav-data.json +++ b/content/terraform-enterprise/1.0.x/data/enterprise-nav-data.json @@ -136,7 +136,8 @@ { "title": "Tests", "path": "api-docs/private-registry/tests" - } + }, + { "title": "Stack Component Configurations", "path": "api-docs/private-registry/stack-component-configurations" } ] }, { "title": "Projects", "path": "api-docs/projects" }, diff --git a/content/terraform-enterprise/1.1.x/data/enterprise-nav-data.json b/content/terraform-enterprise/1.1.x/data/enterprise-nav-data.json index 5d1ba42f94..5ac1b99c01 100644 --- a/content/terraform-enterprise/1.1.x/data/enterprise-nav-data.json +++ b/content/terraform-enterprise/1.1.x/data/enterprise-nav-data.json @@ -140,7 +140,8 @@ { "title": "Tests", "path": "api-docs/private-registry/tests" - } + }, + { "title": "Stack Component Configurations", "path": "api-docs/private-registry/stack-component-configurations" } ] }, { "title": "Projects", "path": "api-docs/projects" },