Overview

Currently, simple workspace operations are convoluted and difficult to understand in our API. In similar products, operations like create, delete, stop, and start have dedicated endpoints to simplify extension of the platform.

Due to the nature of Terraform, these operations have to be executed as workspace build transitions. Our API reflects these by asking users to pass a CreateWorkspaceBuildRequest the /builds endpoint, but it's usage is awkward and difficult to find.

Since this is such a commonly requested use case and challenge for our community and customers, we will manually add the steps to produce this behavior in the admin use cases page.

However, this is not the intuitive first place to look when users want to create a workspace through the API. A potentially more permanent solution would be adding a "frequent use cases" page to our API docs?