coder · Emyrk · Apr 2, 2024 · Apr 1, 2024 · Apr 1, 2024
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/coderd/workspaces.go b/coderd/workspaces.go
@@ -332,6 +332,10 @@ func (api *API) workspaceByOwnerAndName(rw http.ResponseWriter, r *http.Request)
 // Create a new workspace for the currently authenticated user.
 //
 // @Summary Create user workspace by organization
+// @Description Create a new workspace using a template. The request must
+// @Description specify either the Template ID or the Template Version ID,
+// @Description not both. If the Template ID is specified, the active version
+// @Description of the template will be used.
 // @ID create-user-workspace-by-organization
 // @Security CoderSessionToken
 // @Accept json

diff --git a/codersdk/organizations.go b/codersdk/organizations.go
@@ -138,6 +138,9 @@ type CreateTemplateRequest struct {
 
 // CreateWorkspaceRequest provides options for creating a new workspace.
 // Either TemplateID or TemplateVersionID must be specified. They cannot both be present.
+// @Description CreateWorkspaceRequest provides options for creating a new workspace.
+// @Description Only one of TemplateID or TemplateVersionID can be specified, not both.
+// @Description If TemplateID is specified, the active version of the template will be used.
 type CreateWorkspaceRequest struct {
 	// TemplateID specifies which template should be used for creating the workspace.
 	TemplateID uuid.UUID `json:"template_id,omitempty" validate:"required_without=TemplateVersionID,excluded_with=TemplateVersionID" format:"uuid"`

diff --git a/docs/api/schemas.md b/docs/api/schemas.md
diff --git a/docs/api/workspaces.md b/docs/api/workspaces.md