Add initial Stacks API documentation #826

aaabdelgany · 2025-02-04T21:42:44Z

What

This PR adds the basic api documentation for Stacks.

Why

Stacks has hit open beta so it's time we documented the api. This will likely be the first PR among many since the API surface area is pretty expansive but hopefully we can get the most useful/frequently hit endpoints.

Screenshots

Merge Checklist

If items do not apply to your changes, add (N/A) and mark them as complete.

Pull Request

One or more labels describe the type of change (e.g. clarification) and associated product (e.g. HCP Terraform ).
Description links to related pull requests or issues, if any.

Content

API documentation and the API Changelog have been updated.
Links to related content where appropriate (e.g., API endpoints, permissions, etc.).
Pages with related content are updated and link to this content when appropriate.
Sidebar navigation files have been updated for added, deleted, reordered, or renamed pages.
New pages have metadata (page name and description) at the top.
New code blocks have the correct syntax and line breaks to eliminate horizontal scroll bars.
The Vercel website preview successfully deployed.

Reviews

I or someone else reviewed the content for technical accuracy.
I or someone else reviewed the content for typos, punctuation, spelling, and grammar.

vercel · 2025-02-04T21:42:49Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
terraform-docs-common	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 13, 2025 8:46pm

website/docs/cloud-docs/api-docs/stacks.mdx

ker-an · 2025-02-13T21:36:28Z

website/docs/cloud-docs/api-docs/stacks.mdx

+| `POST` | `/stack-plans/:stack_plan_id/replan` | Call this endpoint to [replan stack plan](#replan-stack-plan).|
+| `PATCH` | `/stacks/:stack_id` | Call this endpoint to [update a stack](#update-a-stack).|
+
+## List stacks


I wonder if it would be helpful to have a "Requirements" section above this where we can talk about specific permissions/tokens are user requires to interact with this endpoints? We did something similar on the Projects API page, see https://developer.hashicorp.com/terraform/cloud-docs/api-docs/projects#requirements.

ker-an · 2025-02-13T21:44:15Z

website/docs/cloud-docs/api-docs/stacks.mdx

+
+| Parameter            | Description                                             |
+| -------------------- | ------------------------------------------------------- |
+| `:organization_name` | The name of the organization to list the stacks of. |


Something I've done before is list the query parameters section. We could list the valid include data and any search/filter/pagination. An example of the policy sets query parameter section: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/policy-sets#query-parameters

ker-an

Had another look through! One small nitpick and I think we still have to add the query params but otherwise, I think we are ready for the Documentation Team to review!

ker-an · 2025-02-27T21:21:14Z

website/docs/cloud-docs/api-docs/stacks.mdx

+| `GET` | `/stack-diagnostics/:stack_diagnostic_id` | Call this endpoint to [show stack diagnostic](#show-stack-diagnostic).|
+| `GET` | `/stack-configurations/:stack_configuration_id/stack-diagnostics` | Call this endpoint to [list stack configuration diagnostics](#list-stack-configuration-diagnostics).|
+| `GET` | `/stacks/:stack_id/stack-plans` | Call this endpoint to [list stack plans](#list-stack-plans).|
+| `GET` | `/stack-plans/:stack_plan_id/` | Call this endpoint to [show stack plan](#show-stack-plan).|


rkoron007 · 2025-05-27T23:03:39Z

Hi @aaabdelgany! Heads up that we will be migrating the content from terraform-docs-common into the UDR repo (https://github.com/hashicorp/web-unified-docs) this week. So, I'm going through and merging any documentation PRs we can get in before migration, but for future work you'll need to recreate this PR over in the UDR repo after the migration is complete.

So this is a heads up that after the migration happens I'll close this PR and will let you know when you are good to recreate it! Apologies about the extra work you have to do though!

rkoron007 · 2025-06-03T21:03:48Z

Hello @aaabdelgany!

The UDR migration has occurred, and the HCP Terraform documentation version now lives in the unified documentation repository. I'm going to close this PR since we are no longer serving this content from this repo, but please feel free to recreate your PR in the UDR repository within the HCP Terraform documentation and tag me if you need a review:
https://github.com/hashicorp/web-unified-docs/tree/main/content/terraform-docs-common/docs/cloud-docs

Add initial basic API documentation for stacks

ae4d2f2

vercel bot deployed to Preview February 4, 2025 21:47 View deployment

GET Index

ff78811

vercel bot deployed to Preview February 6, 2025 18:24 View deployment

fetch latest config

e149140

vercel bot deployed to Preview February 6, 2025 21:22 View deployment

stack#delete

aaf98cf

vercel bot deployed to Preview February 6, 2025 21:40 View deployment

Add headers for more endpoints

fdb58ac

vercel bot had a problem deploying to Preview February 11, 2025 19:21 Failure

flesh out overview table

78b645e

vercel bot had a problem deploying to Preview February 11, 2025 20:00 Failure

Merge branch 'main' into stacks/api_documentation

a740bef

vercel bot had a problem deploying to Preview February 11, 2025 20:21 Failure

show stack and index stack configs

adc3954

aaabdelgany changed the title ~~Add initial basic API documentation for stacks~~ Add initial API documentation for stacks Feb 11, 2025

aaabdelgany changed the title ~~Add initial API documentation for stacks~~ Add initial Stacks API documentation Feb 11, 2025

vercel bot had a problem deploying to Preview February 11, 2025 20:49 Failure

add more endpoints to the overview table

9c2bdcd

vercel bot had a problem deploying to Preview February 11, 2025 23:03 Failure

wrap up api overview table

19ecedc

vercel bot had a problem deploying to Preview February 12, 2025 15:11 Failure

ker-an reviewed Feb 12, 2025

View reviewed changes

website/docs/cloud-docs/api-docs/stacks.mdx Show resolved Hide resolved

wrap up most of the GET endpoints

3329217

vercel bot deployed to Preview February 13, 2025 16:13 View deployment

wrap up remaining GET endpoints

2be18f1

vercel bot deployed to Preview February 13, 2025 16:49 View deployment

post WIP

4b784cf

vercel bot deployed to Preview February 13, 2025 18:24 View deployment

wrap up posts

f4223c2

vercel bot deployed to Preview February 13, 2025 18:43 View deployment

wrap up patch update

4b22082

aaabdelgany requested a review from a team February 13, 2025 20:28

aaabdelgany added the HCP Terraform label Feb 13, 2025

vercel bot deployed to Preview February 13, 2025 20:33 View deployment

Update changelog.mdx

3173dee

vercel bot deployed to Preview February 13, 2025 20:46 View deployment

ker-an reviewed Feb 13, 2025

View reviewed changes

ker-an self-requested a review February 27, 2025 21:17

ker-an reviewed Feb 27, 2025

View reviewed changes

rkoron007 added the notified-of-UDR A tag for tracking that this PR owner knows about UDR. label May 27, 2025

rkoron007 closed this Jun 3, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add initial Stacks API documentation #826

Add initial Stacks API documentation #826

Uh oh!

aaabdelgany commented Feb 4, 2025 •

edited

Loading

Uh oh!

vercel bot commented Feb 4, 2025 •

edited

Loading

Uh oh!

Uh oh!

ker-an Feb 13, 2025

Uh oh!

ker-an Feb 13, 2025

Uh oh!

ker-an left a comment •

edited

Loading

Uh oh!

ker-an Feb 27, 2025

Uh oh!

rkoron007 commented May 27, 2025

Uh oh!

rkoron007 commented Jun 3, 2025

Uh oh!

Uh oh!

	\| `GET` \| `/stack-plans/:stack_plan_id/` \| Call this endpoint to [show stack plan](#show-stack-plan).\|
	\| `GET` \| `/stack-plans/:stack_plan_id` \| Call this endpoint to [show stack plan](#show-stack-plan).\|

Add initial Stacks API documentation #826

Add initial Stacks API documentation #826

Uh oh!

Conversation

aaabdelgany commented Feb 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Screenshots

Merge Checklist

Pull Request

Content

Reviews

Uh oh!

vercel bot commented Feb 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ker-an Feb 13, 2025

Choose a reason for hiding this comment

Uh oh!

ker-an Feb 13, 2025

Choose a reason for hiding this comment

Uh oh!

ker-an left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ker-an Feb 27, 2025

Choose a reason for hiding this comment

Uh oh!

rkoron007 commented May 27, 2025

Uh oh!

rkoron007 commented Jun 3, 2025

Uh oh!

Uh oh!

aaabdelgany commented Feb 4, 2025 •

edited

Loading

vercel bot commented Feb 4, 2025 •

edited

Loading

ker-an left a comment •

edited

Loading