> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/api-reference/iacm/workspace-templates.md).

# Workspace Templates

Workspace Templates Service handles the API for managing template associations with workspaces.

## Retrieve workspace-template reconciliation diff

> Get the differences between the current workspace YAML and what it will look like when reconciled with the template

```json
{"openapi":"3.0.3","info":{"title":"Infrastructure as Code Management","version":"0.1.0"},"tags":[{"name":"workspace_templates","description":"Workspace Templates Service handles the API for managing template associations with workspaces."}],"servers":[{"url":"http://localhost:80"}],"paths":{"/api/orgs/{org}/projects/{project}/workspace/template/{workspace_id}/yaml-diff":{"get":{"tags":["workspace_templates"],"summary":"Retrieve workspace-template reconciliation diff","description":"Get the differences between the current workspace YAML and what it will look like when reconciled with the template","operationId":"workspace_templates#get-workspace-template-reconciliation-diff","parameters":[{"name":"org","in":"path","description":"Org is the organisation identifier.","required":true,"schema":{"type":"string","description":"Org is the organisation identifier.","minLength":1,"maxLength":128}},{"name":"project","in":"path","description":"Project is the project identifier.","required":true,"schema":{"type":"string","description":"Project is the project identifier.","minLength":1,"maxLength":128}},{"name":"workspace_id","in":"path","description":"Workspace identifier","required":true,"schema":{"type":"string","description":"Workspace identifier","minLength":1,"maxLength":128}},{"name":"Harness-Account","in":"header","description":"Account is the internal customer account ID.","allowEmptyValue":true,"required":true,"schema":{"type":"string","description":"Account is the internal customer account ID.","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetWorkspaceTemplateReconciliationDiffResponse"}}}},"400":{"description":"BadRequestError: Bad Request response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UnauthorizedError: Unauthorized response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ForbiddenError: Forbidden response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NotFoundError: Not Found response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"TimeoutError: Request Timeout response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"ConflictError: Conflict response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"LockedError: Locked response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"499":{"description":"ContextCancelledError:  response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"InternalServerError: Internal Server Error response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"BadGatewayError: Bad Gateway response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"GetWorkspaceTemplateReconciliationDiffResponse":{"type":"object","properties":{"currentWorkspaceYaml":{"type":"string","description":"Current workspace YAML"},"reconcilableWorkspaceYaml":{"type":"string","description":"Workspace YAML after applying changes from the template"},"requiresReconciliation":{"type":"boolean","description":"Indicates if the workspace needs template-based reconciliation"}},"required":["currentWorkspaceYaml","reconcilableWorkspaceYaml","requiresReconciliation"]},"Error":{"type":"object","properties":{"fault":{"type":"boolean","description":"Is the error a server-side fault?"},"id":{"type":"string","description":"ID is a unique identifier for this particular occurrence of the problem."},"message":{"type":"string","description":"Message is a human-readable explanation specific to this occurrence of the problem."},"name":{"type":"string","description":"Name is the name of this class of errors."},"temporary":{"type":"boolean","description":"Is the error temporary?"},"timeout":{"type":"boolean","description":"Is the error a timeout?"}},"required":["name","id","message","temporary","timeout","fault"]}}}}
```

## Create workspace template

> Add a workspace-template combination to the table.

```json
{"openapi":"3.0.3","info":{"title":"Infrastructure as Code Management","version":"0.1.0"},"tags":[{"name":"workspace_templates","description":"Workspace Templates Service handles the API for managing template associations with workspaces."}],"servers":[{"url":"http://localhost:80"}],"paths":{"/api/orgs/{org}/projects/{project}/workspace/templates":{"post":{"tags":["workspace_templates"],"summary":"Create workspace template","description":"Add a workspace-template combination to the table.","operationId":"workspace_templates#add-workspace-template","parameters":[{"name":"org","in":"path","description":"Org is the organisation identifier.","required":true,"schema":{"type":"string","description":"Org is the organisation identifier.","minLength":1,"maxLength":128}},{"name":"project","in":"path","description":"Project is the project identifier.","required":true,"schema":{"type":"string","description":"Project is the project identifier.","minLength":1,"maxLength":128}},{"name":"Harness-Account","in":"header","description":"Account is the internal customer account ID.","allowEmptyValue":true,"required":true,"schema":{"type":"string","description":"Account is the internal customer account ID.","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceTemplateRequest"}}}},"responses":{"201":{"description":"Created response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceTemplateResponse"}}}},"400":{"description":"BadRequestError: Bad Request response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UnauthorizedError: Unauthorized response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ForbiddenError: Forbidden response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NotFoundError: Not Found response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"TimeoutError: Request Timeout response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"ConflictError: Conflict response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"LockedError: Locked response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"499":{"description":"ContextCancelledError:  response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"InternalServerError: Internal Server Error response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"BadGatewayError: Bad Gateway response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"CreateWorkspaceTemplateRequest":{"type":"object","properties":{"template_id":{"type":"string","description":"Template identifier","minLength":1,"maxLength":128},"version":{"type":"string","description":"Template version","minLength":1,"maxLength":64},"workspace_id":{"type":"string","description":"Workspace identifier","minLength":1,"maxLength":128}},"required":["workspace_id","template_id","version"]},"CreateWorkspaceTemplateResponse":{"type":"object","properties":{"account":{"type":"string","description":"Account identifier.","minLength":1,"maxLength":128},"created_at":{"type":"integer","description":"Timestamp when the workspace-template association was created.","format":"int64"},"org":{"type":"string","description":"Organization identifier.","minLength":1,"maxLength":128},"project":{"type":"string","description":"Project identifier.","minLength":1,"maxLength":128},"template_id":{"type":"string","description":"Template identifier.","minLength":1,"maxLength":128},"updated_at":{"type":"integer","description":"Timestamp when the workspace-template association was last updated.","format":"int64"},"version":{"type":"string","description":"Template version associated with the workspace.","minLength":1,"maxLength":32},"workspace_id":{"type":"string","description":"Workspace identifier.","minLength":1,"maxLength":128}},"required":["workspace_id","template_id","created_at","updated_at","account","project","org"]},"Error":{"type":"object","properties":{"fault":{"type":"boolean","description":"Is the error a server-side fault?"},"id":{"type":"string","description":"ID is a unique identifier for this particular occurrence of the problem."},"message":{"type":"string","description":"Message is a human-readable explanation specific to this occurrence of the problem."},"name":{"type":"string","description":"Name is the name of this class of errors."},"temporary":{"type":"boolean","description":"Is the error temporary?"},"timeout":{"type":"boolean","description":"Is the error a timeout?"}},"required":["name","id","message","temporary","timeout","fault"]}}}}
```

## List workspaces by template id

> Get all workspaces associated with a specific template ID  for a given scope.

```json
{"openapi":"3.0.3","info":{"title":"Infrastructure as Code Management","version":"0.1.0"},"tags":[{"name":"workspace_templates","description":"Workspace Templates Service handles the API for managing template associations with workspaces."}],"servers":[{"url":"http://localhost:80"}],"paths":{"/api/orgs/{org}/projects/{project}/workspace/templates/{template_id}":{"get":{"tags":["workspace_templates"],"summary":"List workspaces by template id","description":"Get all workspaces associated with a specific template ID  for a given scope.","operationId":"workspace_templates#get-workspaces-by-template-id","parameters":[{"name":"org","in":"path","description":"Org is the organisation identifier.","required":true,"schema":{"type":"string","description":"Org is the organisation identifier.","minLength":1,"maxLength":128}},{"name":"project","in":"path","description":"Project is the project identifier.","required":true,"schema":{"type":"string","description":"Project is the project identifier.","minLength":1,"maxLength":128}},{"name":"template_id","in":"path","description":"Template identifier to filter workspaces","required":true,"schema":{"type":"string","description":"Template identifier to filter workspaces","minLength":1,"maxLength":128}},{"name":"Harness-Account","in":"header","description":"Account is the internal customer account ID.","allowEmptyValue":true,"required":true,"schema":{"type":"string","description":"Account is the internal customer account ID.","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HarnessIacmWorkspaceTemplate"},"description":"List of workspaces associated with the template ID"}}}},"400":{"description":"BadRequestError: Bad Request response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UnauthorizedError: Unauthorized response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ForbiddenError: Forbidden response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NotFoundError: Not Found response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"TimeoutError: Request Timeout response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"ConflictError: Conflict response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"LockedError: Locked response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"499":{"description":"ContextCancelledError:  response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"InternalServerError: Internal Server Error response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"BadGatewayError: Bad Gateway response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"HarnessIacmWorkspaceTemplate":{"type":"object","properties":{"account":{"type":"string","description":"Account identifier.","minLength":1,"maxLength":128},"created_at":{"type":"integer","description":"Timestamp when the workspace-template association was created.","format":"int64"},"org":{"type":"string","description":"Organization identifier.","minLength":1,"maxLength":128},"project":{"type":"string","description":"Project identifier.","minLength":1,"maxLength":128},"template_id":{"type":"string","description":"Template identifier.","minLength":1,"maxLength":128},"updated_at":{"type":"integer","description":"Timestamp when the workspace-template association was last updated.","format":"int64"},"version":{"type":"string","description":"Template version associated with the workspace.","minLength":1,"maxLength":32},"workspace_id":{"type":"string","description":"Workspace identifier.","minLength":1,"maxLength":128}},"description":"WorkspaceTemplateResource is the representation for a workspace-template association.","required":["workspace_id","template_id","created_at","updated_at","account","project","org"]},"Error":{"type":"object","properties":{"fault":{"type":"boolean","description":"Is the error a server-side fault?"},"id":{"type":"string","description":"ID is a unique identifier for this particular occurrence of the problem."},"message":{"type":"string","description":"Message is a human-readable explanation specific to this occurrence of the problem."},"name":{"type":"string","description":"Name is the name of this class of errors."},"temporary":{"type":"boolean","description":"Is the error temporary?"},"timeout":{"type":"boolean","description":"Is the error a timeout?"}},"required":["name","id","message","temporary","timeout","fault"]}}}}
```

## Update workspace template

> Update a workspace template combo to change its version.

```json
{"openapi":"3.0.3","info":{"title":"Infrastructure as Code Management","version":"0.1.0"},"tags":[{"name":"workspace_templates","description":"Workspace Templates Service handles the API for managing template associations with workspaces."}],"servers":[{"url":"http://localhost:80"}],"paths":{"/api/orgs/{org}/projects/{project}/workspace/templates/{template_id}/{workspace_id}":{"put":{"tags":["workspace_templates"],"summary":"Update workspace template","description":"Update a workspace template combo to change its version.","operationId":"workspace_templates#update-workspace-template","parameters":[{"name":"org","in":"path","description":"Org is the organisation identifier.","required":true,"schema":{"type":"string","description":"Org is the organisation identifier.","minLength":1,"maxLength":128}},{"name":"project","in":"path","description":"Project is the project identifier.","required":true,"schema":{"type":"string","description":"Project is the project identifier.","minLength":1,"maxLength":128}},{"name":"template_id","in":"path","description":"Template identifier","required":true,"schema":{"type":"string","description":"Template identifier","minLength":1,"maxLength":128}},{"name":"workspace_id","in":"path","description":"Workspace identifier","required":true,"schema":{"type":"string","description":"Workspace identifier","minLength":1,"maxLength":128}},{"name":"Harness-Account","in":"header","description":"Account is the internal customer account ID.","allowEmptyValue":true,"required":true,"schema":{"type":"string","description":"Account is the internal customer account ID.","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceTemplateRequest"}}}},"responses":{"200":{"description":"OK response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceTemplateResponse"}}}},"400":{"description":"BadRequestError: Bad Request response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UnauthorizedError: Unauthorized response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ForbiddenError: Forbidden response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NotFoundError: Not Found response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"TimeoutError: Request Timeout response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"ConflictError: Conflict response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"LockedError: Locked response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"499":{"description":"ContextCancelledError:  response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"InternalServerError: Internal Server Error response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"BadGatewayError: Bad Gateway response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"UpdateWorkspaceTemplateRequest":{"type":"object","properties":{"version":{"type":"string","description":"New template version","minLength":1,"maxLength":64}},"required":["version"]},"UpdateWorkspaceTemplateResponse":{"type":"object","properties":{"account":{"type":"string","description":"Account identifier.","minLength":1,"maxLength":128},"created_at":{"type":"integer","description":"Timestamp when the workspace-template association was created.","format":"int64"},"org":{"type":"string","description":"Organization identifier.","minLength":1,"maxLength":128},"project":{"type":"string","description":"Project identifier.","minLength":1,"maxLength":128},"template_id":{"type":"string","description":"Template identifier.","minLength":1,"maxLength":128},"updated_at":{"type":"integer","description":"Timestamp when the workspace-template association was last updated.","format":"int64"},"version":{"type":"string","description":"Template version associated with the workspace.","minLength":1,"maxLength":32},"workspace_id":{"type":"string","description":"Workspace identifier.","minLength":1,"maxLength":128}},"required":["workspace_id","template_id","created_at","updated_at","account","project","org"]},"Error":{"type":"object","properties":{"fault":{"type":"boolean","description":"Is the error a server-side fault?"},"id":{"type":"string","description":"ID is a unique identifier for this particular occurrence of the problem."},"message":{"type":"string","description":"Message is a human-readable explanation specific to this occurrence of the problem."},"name":{"type":"string","description":"Name is the name of this class of errors."},"temporary":{"type":"boolean","description":"Is the error temporary?"},"timeout":{"type":"boolean","description":"Is the error a timeout?"}},"required":["name","id","message","temporary","timeout","fault"]}}}}
```

## Delete workspace template

> Remove the association between a template and a workspace.

```json
{"openapi":"3.0.3","info":{"title":"Infrastructure as Code Management","version":"0.1.0"},"tags":[{"name":"workspace_templates","description":"Workspace Templates Service handles the API for managing template associations with workspaces."}],"servers":[{"url":"http://localhost:80"}],"paths":{"/api/orgs/{org}/projects/{project}/workspace/templates/{template_id}/{workspace_id}":{"delete":{"tags":["workspace_templates"],"summary":"Delete workspace template","description":"Remove the association between a template and a workspace.","operationId":"workspace_templates#remove-workspace-template","parameters":[{"name":"org","in":"path","description":"Org is the organisation identifier.","required":true,"schema":{"type":"string","description":"Org is the organisation identifier.","minLength":1,"maxLength":128}},{"name":"project","in":"path","description":"Project is the project identifier.","required":true,"schema":{"type":"string","description":"Project is the project identifier.","minLength":1,"maxLength":128}},{"name":"template_id","in":"path","description":"Template identifier","required":true,"schema":{"type":"string","description":"Template identifier","minLength":1,"maxLength":128}},{"name":"workspace_id","in":"path","description":"Workspace identifier","required":true,"schema":{"type":"string","description":"Workspace identifier","minLength":1,"maxLength":128}},{"name":"Harness-Account","in":"header","description":"Account is the internal customer account ID.","allowEmptyValue":true,"required":true,"schema":{"type":"string","description":"Account is the internal customer account ID.","minLength":1,"maxLength":128}}],"responses":{"204":{"description":"No Content response."},"400":{"description":"BadRequestError: Bad Request response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UnauthorizedError: Unauthorized response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ForbiddenError: Forbidden response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NotFoundError: Not Found response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"TimeoutError: Request Timeout response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"ConflictError: Conflict response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"LockedError: Locked response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"499":{"description":"ContextCancelledError:  response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"InternalServerError: Internal Server Error response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"BadGatewayError: Bad Gateway response.","content":{"application/vnd.goa.error":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"fault":{"type":"boolean","description":"Is the error a server-side fault?"},"id":{"type":"string","description":"ID is a unique identifier for this particular occurrence of the problem."},"message":{"type":"string","description":"Message is a human-readable explanation specific to this occurrence of the problem."},"name":{"type":"string","description":"Name is the name of this class of errors."},"temporary":{"type":"boolean","description":"Is the error temporary?"},"timeout":{"type":"boolean","description":"Is the error a timeout?"}},"required":["name","id","message","temporary","timeout","fault"]}}}}
```