Workspaces API reference

This topic provides reference information about the workspaces AP. Workspaces represent running infrastructure managed by Terraform.

Overview

The scope of the API includes the following endpoints:

Method	Path	Action
`POST`	`/organizations/:organization_name/workspaces`	Call this endpoint to create a workspace. You can apply tags stored as key-value pairs when creating the workspace.
`POST`	`/organizations/:organization_name/workspaces/:name/actions/safe-delete`	Call this endpoint to safely delete a workspace by querying the organization and workspace names.
`POST`	`/workspaces/:workspace_id/actions/safe-delete`	Call this endpoint safely delete a workspace by querying the workspace ID.
`POST`	`/workspaces/:workspace_id/actions/lock`	Call this endpoint to lock a workspace.
`POST`	`/workspaces/:workspace_id/actions/unlock`	Call this endpoint to unlock a workspace.
`POST`	`/workspaces/:workspace_id/actions/force-unlock`	Call this endpoint to force a workspace to unlock.
`POST`	`/workspaces/:workspace_id/relationships/remote-state-consumers`	Call this endpoint to add remote state consumers.
`POST`	`/workspaces/:workspace_id/relationships/tags`	Call this endpoint to bind flat string tags to an existing workspace.
`POST`	`/workspaces/:workspace_id/relationships/data-retention-policy`	Call this endpoint to show the workspace data retention policy.
`GET`	`/organizations/:organization_name/workspaces`	Call this endpoint to list existing workspaces. Each project in the response contains a link to `effective-tag-bindings` and `tag-bindings` collections. You can filter the response by tag keys and values using a query string parameter.
`GET`	`/organizations/:organization_name/workspaces/:name`	Call this endpoint to show workspace details by querying the organization and workspace names.
`GET`	`/workspaces/:workspace_id`	Call this endpoint to show workspace details.
`GET`	`/workspaces/:workspace_id/relationships/remote-state-consumers`	Call this endpoint to list remote state consumers.
`GET`	`/workspaces/:workspace_id/relationships/tags`	Call this endpoint to list flat string workspace tags.
`GET`	`/workspaces/:workspace_id/tag-bindings`	Call this endpoint to list workspace key-value tags bound directly to this workspace.
`GET`	`/workspaces/:workspace_id/effective-tag-bindings`	Call this endpoint to list all workspace key-value tags, including both those bound directly to the workspace as well as those inherited from the parent project.
`GET`	`/workspaces/:workspace_id/relationships/data-retention-policy`	Call this endpoint to show the workspace data retention policy.
`PATCH`	`/workspaces/:workspace_id/relationships/ssh-key`	Call this endpoint to manage SSH key assignments for workspaces. Refer to Assign an SSH key to a workspace and Unassign an SSH key from a workspace for instructions.
`PATCH`	`/workspaces/:workspace_id`	Call this endpoint to update a workspace. You can apply tags stored as key-value pairs when updating the workspace.
`PATCH`	`/organizations/:organization_name/workspaces/:name`	Call this endpoint to update a workspace by querying the organization and workspace names.
`PATCH`	`/workspaces/:workspace_id/relationships/remote-state-consumers`	Call this endpoint to replace remote state consumers.
`DELETE`	`/workspaces/:workspace_id/relationships/remote-state-consumers`	Call this endpoint to delete remote state consumers.
`DELETE`	`/workspaces/:workspace_id/relationships/tags`	Call this endpoint to delete flat string workspace tags from the workspace.
`DELETE`	`/workspaces/:workspace_id/relationships/data-retention-policy`	Call this endpoint to remove a workspace data retention policy.
`DELETE`	`/workspaces/:workspace_id`	Call this endpoint to force delete a workspace, which deletes the workspace without first checking for managed resources.
`DELETE`	`/organizations/:organization_name/workspaces/:name`	Call this endpoint to force delete a workspace, which deletes the workspace without first checking for managed resources, by querying the organization and workspace names.

Requirements

You must be a member of a team with the Read permission enabled for Terraform runs to view workspaces.
You must be a member of a team with the Admin permissions enabled on the workspace to change settings and force-unlock it.
You must be a member of a team with the Lock/unlock permission enabled to lock and unlock the workspace.
You must meet one of the following requirements to create a workspace:
- Be the team owner
- Be on a team with the Manage all workspaces permission enabled
- Present an organization API token when calling the API.

Refer to Workspace Permissions for additional information.

Create a Workspace

Use the following endpoint to create a new workspace:

POST /organizations/:organization_name/workspaces

Parameter	Description
`:organization_name`	The name of the organization to create the workspace in. The organization must already exist in the system, and the user must have permissions to create new workspaces.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

By supplying the necessary attributes under a vcs-repository object, you can create a workspace that is configured against a VCS Repository.

Key path	Type	Default	Description
`data.type`	string	none	Must be `"workspaces"`.
`data.attributes.name`	string	none	The name of the workspace. Workspace names can only include letters, numbers, `-`, and `_`. The name a unique identifier n the organization.
`data.attributes.agent-pool-id`	string	none	Required when `execution-mode` is set to `agent`. The ID of the agent pool belonging to the workspace's organization. This value must not be specified if `execution-mode` is set to `remote` or `local` or if `operations` is set to `true`.
`data.attributes.allow-destroy-plan`	boolean	`true`	Whether destroy plans can be queued on the workspace.
`data.attributes.assessments-enabled`	boolean	`false`	(previously `drift-detection`) Whether or not HCP Terraform performs health assessments for the workspace. May be overridden by the organization setting `assessments-enforced`. Only available for Plus tier organizations, in workspaces running Terraform version 0.15.4+ and operating in Remote execution mode.
`data.attributes.auto-apply`	boolean	`false`	Whether to automatically apply changes when a Terraform plan is successful in runs initiated by VCS, UI or CLI, with some exceptions.
`data.attributes.auto-apply-run-trigger`	boolean	`false`	Whether to automatically apply changes when a Terraform plan is successful in runs initiated by run triggers.
`data.attributes.auto-destroy-at`	string	(nothing)	Timestamp when the next scheduled destroy run will occur, refer to Scheduled Destroy.
`data.attributes.auto-destroy-activity-duration`	string	(nothing)	Value and units for automatically scheduled destroy runs based on workspace activity. Valid values are greater than 0 and four digits or less. Valid units are `d` and `h`. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`.
`data.attributes.description`	string	(nothing)	A description for the workspace.
`data.attributes.execution-mode`	string	(nothing)	Which execution mode to use. Valid values are `remote`, `local`, and `agent`. When set to `local`, the workspace will be used for state storage only. This value must not be specified if `operations` is specified, and must be specified if `setting-overwrites.execution-mode` is set to `true`.
`data.attributes.file-triggers-enabled`	boolean	`true`	Whether to filter runs based on the changed files in a VCS push. If enabled, it uses either `trigger-prefixes` in conjunction with `working_directory` or `trigger-patterns` to describe the set of changed files that will start a run. If disabled, any push triggers a run.
`data.attributes.global-remote-state`	boolean	`false`	Whether the workspace should allow all workspaces in the organization to access its state data during runs. If `false`, then only specifically approved workspaces can access its state. Manage allowed workspaces using the Remote State Consumers endpoints, documented later on this page. Terraform Enterprise admins can choose the default value for new workspaces if this attribute is omitted.
`data.attributes.operations`	boolean	`true`	DEPRECATED Use `execution-mode` instead. Whether to use remote execution mode. When set to `false`, the workspace will be used for state storage only. This value must not be specified if `execution-mode` is specified.
`data.attributes.queue-all-runs`	boolean	`false`	Whether runs should be queued immediately after workspace creation. When set to false, runs triggered by a VCS change will not be queued until at least one run is manually queued.
`data.attributes.source-name`	string	none	A friendly name for the application or client creating this workspace. If set, this will be displayed on the workspace as "Created via `<SOURCE NAME>`".
`data.attributes.source-url`	string	none	A URL for the application or client creating this workspace. This can be the URL of a related resource in another app, or a link to documentation or other info about the client.
`data.attributes.speculative-enabled`	boolean	`true`	Whether this workspace allows automatic speculative plans. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. It doesn't prevent manual speculative plans via the CLI or the runs API.
`data.attributes.terraform-version`	string	latest release	Specifies the version of Terraform to use for this workspace. You can specify an exact version or a version constraint such as `~> 1.0.0`. If you specify a constraint, the workspace always uses the newest release that meets that constraint. If omitted when creating a workspace, this defaults to the latest released version.
`data.attributes.trigger-patterns`	array	`[]`	List of glob patterns that describe the files HCP Terraform monitors for changes. Trigger patterns are always appended to the root directory of the repository.
`data.attributes.trigger-prefixes`	array	`[]`	List of trigger prefixes that describe the paths HCP Terraform monitors for changes, in addition to the working directory. Trigger prefixes are always appended to the root directory of the repository. HCP Terraform starts a run when files are changed in any directory path matching the provided set of prefixes.
`data.attributes.vcs-repo.branch`	string	repository's default branch	The repository branch that Terraform executes from. If omitted or submitted as an empty string, this defaults to the repository's default branch.
`data.attributes.vcs-repo.identifier`	string	none	A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. The format for Azure DevOps is `:org/:project/_git/:repo`.
`data.attributes.vcs-repo.ingress-submodules`	boolean	`false`	Whether submodules should be fetched when cloning the VCS repository.
`data.attributes.vcs-repo.oauth-token-id`	string	none	Specifies the VCS OAuth connection and token. Call the `oauth-tokens` endpoint to retrieve the OAuth ID.
`data.attributes.vcs-repo.tags-regex`	string	none	A regular expression used to match Git tags. HCP Terraform triggers a run when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression.
`data.attributes.vcs-repo`	object	none	Settings for the workspace's VCS repository. If omitted, the workspace is created without a VCS repo. If included, you must specify at least the `oauth-token-id` and `identifier` keys.
`data.attributes.working-directory`	string	(nothing)	A relative path that Terraform will execute within. This defaults to the root of your repository and is typically set to a subdirectory matching the environment when multiple environments exist within the same repository.
`data.attributes.setting-overwrites`	object	none	The keys in this object are attributes that have organization-level defaults. Each attribute key stores a boolean value which is `true` by default. To overwrite the default inherited value, set an attribute's value to `false`. For example, to set `execution-mode` as the organization default, set `setting-overwrites.execution-mode` to `false`.
`data.relationships`	object	none	Specifies a group of workspace associations.
`data.relationships.project.data.id`	string	default project	The ID of the project to create the workspace in. If left blank, Terraform creates the workspace in the organization's default project. You must have permission to create workspaces in the project, either by organization-level permissions or team admin access to a specific project.
`data.relationships.tag-bindings.data`	list of objects	none	Specifies a list of tags to attach to the workspace.
`data.relationships.tag-bindings.data.type`	string	none	Must be `tag-bindings` for each object in the list.
`data.relationships.tag-bindings.data.attributes.key`	string	none	Specifies the tag key for each object in the list.
`data.relationships.tag-bindings.data.attributes.value`	string	none	Specifies the tag value for each object in the list.

Sample Payload

Without a VCS repository

{  "data": {    "attributes": {      "name": "workspace-1"    },    "type": "workspaces"  }}

With Key/Value Tags

{  "data": {    "attributes": {      "name": "workspace-1"    },    "type": "workspaces",    "relationships": {      "tag-bindings": {        {          "data": [{            "type": "tag-bindings",            "attributes": { "key": "env", "value": "test"}          }]        }      }    }  }}

With a VCS repository

{  "data": {    "attributes": {      "name": "workspace-2",      "terraform_version": "0.11.1",      "working-directory": "",      "vcs-repo": {        "identifier": "example/terraform-test-proj",        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",        "branch": "",        "tags-regex": null      }    },    "type": "workspaces"  }}

Using Git Tags

HCP Terraform triggers a run when you push a Git tag that matches the regular expression (SemVer): 1.2.3, 22.33.44, etc.

{  "data": {    "attributes": {      "name": "workspace-3",      "terraform_version": "0.12.1",      "file-triggers-enabled": false,      "working-directory": "/networking",      "vcs-repo": {        "identifier": "example/terraform-test-proj-monorepo",        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",        "branch": "",        "tags-regex": "\d+.\d+.\d+"      }    },    "type": "workspaces"  }}

For a monorepo using trigger prefixes

A run will be triggered in this workspace when changes are detected in any of the specified directories: /networking, /modules, or /vendor.

{  "data": {    "attributes": {      "name": "workspace-3",      "terraform_version": "0.12.1",      "file-triggers-enabled": true,      "trigger-prefixes": ["/modules", "/vendor"],      "working-directory": "/networking",      "vcs-repo": {        "identifier": "example/terraform-test-proj-monorepo",        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",        "branch": ""      },      "updated-at": "2017-11-29T19:18:09.976Z"    },    "type": "workspaces"  }}

For a monorepo using trigger patterns

A run will be triggered in this workspace when HCP Terraform detects any of the following changes:

A file with the extension tf in any directory structure in which the last folder is named networking (e.g., root/networking and root/module/networking)
Any file changed in the folder /base, no subfolders are included
Any file changed in the folder /submodule and all of its subfolders

{  "data": {    "attributes": {      "name": "workspace-4",      "terraform_version": "1.2.2",      "file-triggers-enabled": true,      "trigger-patterns": ["/**/networking/*.tf", "/base/*", "/submodule/**/*"],      "vcs-repo": {        "identifier": "example/terraform-test-proj-monorepo",        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",        "branch": ""      },      "updated-at": "2022-06-09T19:18:09.976Z"    },    "type": "workspaces"  }}

Using HCP Terraform agents

HCP Terraform agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure.

{  "data": {    "attributes": {      "name":"workspace-1",      "execution-mode": "agent",      "agent-pool-id": "apool-ZjT6A7mVFm5WHT5a"    }  },  "type": "workspaces"}

Using an organization default execution mode

{  "data": {    "attributes": {      "name":"workspace-with-default",      "setting-overwrites": {        "execution-mode": false      }    }  },  "type": "workspaces"}

With a project

{  "data": {    "type": "workspaces",    "attributes": {      "name": "workspace-in-project"    },    "relationships": {      "project": {        "data": {          "type": "projects",          "id": "prj-jT92VLSFpv8FwKtc"        }      }    }  }}

With key-value tags

{  "data": {    "type": "workspaces",    "attributes": {      "name": "workspace-in-project"    }  }}

Sample Request

$ 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/workspaces

Sample Response

Without a VCS repository

Note: The assessments-enabled property is only accepted by or returned from HCP Terraform.

{  "data": {    "id": "ws-6jrRyVDv1J8zQMB5",    "type": "workspaces",    "attributes": {      "actions": {        "is-destroyable": true      },      "allow-destroy-plan": true,      "assessments-enabled": false,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-status": null,      "auto-destroy-activity-duration": null,      "inherits-project-auto-destroy": null,      "created-at": "2021-08-16T21:22:49.566Z",      "description": null,      "environment": "default",      "execution-mode": "agent",      "file-triggers-enabled": true,      "global-remote-state": false,      "latest-change-at": "2021-08-16T21:22:49.566Z",      "last-assessment-result-at" : "2021-08-17T21:20:12.908Z",      "locked": true,      "locked-reason": null,      "name": "workspace-1",      "oauth-client-name": null,      "operations": true,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": true,        "can-force-delete": true,        "can-manage-assessments": true,        "can-manage-ephemeral-workspaces": false,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "apply-duration-average": 35000,      "plan-duration-average": 53000,      "policy-check-failures": null,      "queue-all-runs": false,      "resource-count": 10,      "run-failures": 3,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "tag-names": [],      "terraform-version": "1.9.4",      "trigger-prefixes": [],      "updated-at": "2021-08-16T21:22:49.566Z",      "vcs-repo": null,      "vcs-repo-identifier": null,      "working-directory": null,      "workspace-kpis-runs-count": 8,      "setting-overwrites": {        "execution-mode": true,        "agent-pool": true      }    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-1",      "self-html": "/app/my-organization/workspaces/workspace-1"    },    "relationships": {      "agent-pool": {        "data": {          "id": "apool-QxGd2tRjympfMvQc",          "type": "agent-pools"        }      },      "current-configuration-version": {        "data": null      },      "current-run": {        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"        }      },      "latest-run": { // Deprecated; same as current-run        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "current-state-version": {        "data": {          "id": "sv-hjy7ndEkmCtn31ps",          "type": "state-versions"        },        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"        }      },      "current-configuration-version": {        "data": {          "id": "cv-hjy7ndEkmCtn31ps",          "type": "configuration-versions"        },        "links": {          "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"        }      },      "current-assessment-result": {        "data": null      },      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "outputs": {        "data": [          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          },          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          }        ],        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"        }      },      "project": {        "data": {          "id": "prj-hjy7ndEkmCtn31ps",          "type": "projects"        }      },      "readme": {        "data": null      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"        }      },      "ssh-key": {        "data": {          "id": "sshkey-hjy7ndEkmCtn31ps",          "type": "ssh-keys"        },        "links": {          "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"        }      },      "locked-by": {        "data": {          "id": "user-hjy7ndEkmCtn31ps",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"        }      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"        }      },      "vars": {        "data": [          {            "id": "var-hjy7ndEkmCtn31ps",            "type": "vars"          }        ]      },    }  }}

With a VCS repository

{  "data": {    "id": "ws-KTuq99JSzgmDSvYj",    "type": "workspaces",    "attributes": {      "actions": {        "is-destroyable": true      },      "allow-destroy-plan": true,      "apply-duration-average": null,      "assessments-enabled": false,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-activity-duration": null,      "created-at": "2021-08-16T21:50:58.726Z",      "description": null,      "environment": "default",      "execution-mode": "remote",      "file-triggers-enabled": true,      "global-remote-state": false,      "latest-change-at": "2021-08-16T21:50:58.726Z",      "locked": false,      "locked-reason": "",      "name": "workspace-2",      "oauth-client-name": "github example",      "operations": true,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": true,        "can-force-delete": true,        "can-manage-assessments": true,        "can-manage-ephemeral-workspaces": false,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "apply-duration-average": 35000,      "plan-duration-average": 53000,      "policy-check-failures": null,      "queue-all-runs": false,      "resource-count": 10,      "run-failures": 3,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "tag-names": [],      "terraform-version": "1.9.4",      "trigger-prefixes": [],      "vcs-repo": {        "branch": "",        "display-identifier": "example/terraform-test-proj",        "identifier": "example/terraform-test-proj",        "ingress-submodules": false,        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",        "repository-http-url": "https://github.com/example/terraform-test-proj",        "service-provider": "github",        "tags-regex": null,        "webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"      },      "vcs-repo-identifier": "example/terraform-test-proj",      "working-directory": "",      "workspace-kpis-runs-count": null,      "setting-overwrites": {        "execution-mode": true,        "agent-pool": true      }    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-2",      "self-html": "/app/my-organization/workspaces/workspace-2"    },    "relationships": {      "relationships": {      "agent-pool": {        "data": null      },      "current-configuration-version": {        "data": null      },      "current-run": {        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"        }      },      "latest-run": { // Deprecated; same as current-run        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "current-state-version": {        "data": {          "id": "sv-hjy7ndEkmCtn31ps",          "type": "state-versions"        },        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"        }      },      "current-configuration-version": {        "data": {          "id": "cv-hjy7ndEkmCtn31ps",          "type": "configuration-versions"        },        "links": {          "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"        }      },      "current-assessment-result": {        "data": null      },      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "outputs": {        "data": [          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          }        ],        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"        }      },      "project": {        "data": {          "id": "prj-hjy7ndEkmCtn31ps",          "type": "projects"        }      },      "readme": {        "data": null      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"        }      },      "ssh-key": {        "data": {          "id": "sshkey-hjy7ndEkmCtn31ps",          "type": "ssh-keys"        },        "links": {          "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"        }      },      "locked-by": {        "data": {          "id": "user-hjy7ndEkmCtn31ps",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"        }      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"        }      },      "vars": {        "data": [          {            "id": "var-hjy7ndEkmCtn31ps",            "type": "vars"          }        ]      },    }  }}

With a project

{  "data": {    "id": "ws-HRkJLSYWF97jucqQ",    "type": "workspaces",    "attributes": {      "allow-destroy-plan": true,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-activity-duration": null,      "created-at": "2022-12-05T20:57:13.829Z",      "environment": "default",      "locked": false,      "locked-reason": "",      "name": "workspace-in-project",      "queue-all-runs": false,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "terraform-version": "1.3.5",      "working-directory": null,      "global-remote-state": true,      "updated-at": "2022-12-05T20:57:13.829Z",      "resource-count": 0,      "apply-duration-average": null,      "plan-duration-average": null,      "policy-check-failures": null,      "run-failures": null,      "workspace-kpis-runs-count": null,      "latest-change-at": "2022-12-05T20:57:13.829Z",      "operations": true,      "execution-mode": "remote",      "vcs-repo": null,      "vcs-repo-identifier": null,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": false,        "can-force-delete": true,        "can-manage-assessments": true,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "actions": {        "is-destroyable": true      },      "description": null,      "file-triggers-enabled": true,      "trigger-prefixes": [],      "trigger-patterns": [],      "assessments-enabled": false,      "last-assessment-result-at": null,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "tag-names": [],      "setting-overwrites": {        "execution-mode": false,        "agent-pool": false      }    },    "relationships": {      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "current-run": {        "data": null      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-HRkJLSYWF97jucqQ/effective-tag-bindings"        }      },      "latest-run": {        "data": null      },      "outputs": {        "data": []      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-HRkJLSYWF97jucqQ/relationships/remote-state-consumers"        }      },      "current-state-version": {        "data": null      },      "current-configuration-version": {        "data": null      },      "agent-pool": {        "data": null      },      "readme": {        "data": null      },      "project": {        "data": {          "id": "prj-jT92VLSFpv8FwKtc",          "type": "projects"        }      },      "current-assessment-result": {        "data": null      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-HRkJLSYWF97jucqQ/tag-bindings"        }      },      "vars": {        "data": []      },    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-in-project"    }  }}

Update a Workspace

Use one of the following endpoint to update a workspace:

Parameter	Description
`:workspace_id`	The ID of the workspace to update
`:organization_name`	The name of the organization the workspace belongs to.
`:name`	The name of the workspace to update. Workspace names are unique identifiers in the organization and can only include letters, numbers, `-`, and `_`.

Request Body

These PATCH endpoints require 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 `"workspaces"`.
`data.attributes.name`	string	(previous value)	A new name for the workspace, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. Warning: Changing a workspace's name changes its URL in the API and UI.
`data.attributes.agent-pool-id`	string	(previous value)	Required when `execution-mode` is set to `agent`. The ID of the agent pool belonging to the workspace's organization. This value must not be specified if `execution-mode` is set to `remote` or `local` or if `operations` is set to `true`.
`data.attributes.allow-destroy-plan`	boolean	(previous value)	Whether destroy plans can be queued on the workspace.
`data.attributes.assessments-enabled`	boolean	`false`	(previously `drift-detection`) Whether or not HCP Terraform performs health assessments for the workspace. May be overridden by the organization setting `assessments-enforced`. Only available for Plus tier organizations, in workspaces running Terraform version 0.15.4+ and operating in Remote execution mode.
`data.attributes.auto-apply`	boolean	(previous value)	Whether to automatically apply changes when a Terraform plan is successful in runs initiated by VCS, UI or CLI, with some exceptions.
`data.attributes.auto-apply-run-trigger`	boolean	(previous value)	Whether to automatically apply changes when a Terraform plan is successful in runs initiated by run triggers.
`data.attributes.auto-destroy-at`	string	(previous value)	Timestamp when the next scheduled destroy run will occur, refer to Scheduled Destroy.
`data.attributes.auto-destroy-activity-duration`	string	(previous value)	Value and units for automatically scheduled destroy runs based on workspace activity. Valid values are greater than 0 and four digits or less. Valid units are `d` and `h`. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`.
`data.attributes.description`	string	(previous value)	A description for the workspace.
`data.attributes.execution-mode`	string	(previous value)	Which execution mode to use. Valid values are `remote`, `local`, and `agent`. When set to `local`, the workspace will be used for state storage only. This value must not be specified if `operations` is specified, and must be specified if `setting-overwrites.execution-mode` is set to `true`.
`data.attributes.file-triggers-enabled`	boolean	(previous value)	Whether to filter runs based on the changed files in a VCS push. If enabled, it uses either `trigger-prefixes` in conjunction with `working_directory` or `trigger-patterns` to describe the set of changed files that will start a run. If disabled, any push will trigger a run.
`data.attributes.global-remote-state`	boolean	(previous value)	Whether the workspace should allow all workspaces in the organization to access its state data during runs. If `false`, then only specifically approved workspaces can access its state. Manage allowed workspaces using the Remote State Consumers endpoints, documented later on this page.
`data.attributes.operations`	boolean	(previous value)	DEPRECATED Use `execution-mode` instead. Whether to use remote execution mode. When set to `false`, the workspace will be used for state storage only. This value must not be specified if `execution-mode` is specified.
`data.attributes.queue-all-runs`	boolean	(previous value)	Whether runs should be queued immediately after workspace creation. When set to false, runs triggered by a VCS change will not be queued until at least one run is manually queued.
`data.attributes.speculative-enabled`	boolean	(previous value)	Whether this workspace allows automatic speculative plans. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. It doesn't prevent manual speculative plans via the CLI or the runs API.
`data.attributes.terraform-version`	string	(previous value)	The version of Terraform to use for this workspace. This can be either an exact version or a version constraint (like `~> 1.0.0`); if you specify a constraint, the workspace will always use the newest release that meets that constraint.
`data.attributes.trigger-patterns`	array	(previous value)	List of glob patterns that describe the files HCP Terraform monitors for changes. Trigger patterns are always appended to the root directory of the repository.
`data.attributes.trigger-prefixes`	array	(previous value)	List of trigger prefixes that describe the paths HCP Terraform monitors for changes, in addition to the working directory. Trigger prefixes are always appended to the root directory of the repository. HCP Terraform will start a run when files are changed in any directory path matching the provided set of prefixes.
`data.attributes.vcs-repo.branch`	string	(previous value)	The repository branch that Terraform will execute from.
`data.attributes.vcs-repo.identifier`	string	(previous value)	A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. The format for Azure DevOps is `:org/:project/_git/:repo`.
`data.attributes.vcs-repo.ingress-submodules`	boolean	(previous value)	Whether submodules should be fetched when cloning the VCS repository.
`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.tags-regex`	string	(previous value)	A regular expression used to match Git tags. HCP Terraform triggers a run when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression.
`data.attributes.vcs-repo`	object or null	(previous value)	To delete a workspace's existing VCS repo, specify `null` instead of an object. To modify a workspace's existing VCS repo, include whichever of the keys below you wish to modify. To add a new VCS repo to a workspace that didn't previously have one, include at least the `oauth-token-id` and `identifier` keys.
`data.attributes.working-directory`	string	(previous value)	A relative path that Terraform will execute within. This defaults to the root of your repository and is typically set to a subdirectory matching the environment when multiple environments exist within the same repository.
`data.attributes.setting-overwrites`	object		The keys in this object are attributes that have organization-level defaults. Each attribute key stores a boolean value which is `true` by default. To overwrite the default inherited value, set an attribute's value to `false`. For example, to set `execution-mode` as the organization default, you set `setting-overwrites.execution-mode = false`.
`data.relationships`	object	none	Specifies a group of workspace relationships.
`data.relationships.project.data.id`	string	existing value	The ID of the project to move the workspace to. If left blank or unchanged, the workspace will not be moved. You must have admin permissions on both the source project and destination project in order to move a workspace between projects.
`data.relationships.tag-bindings.data`	list of objects	none	Specifies a list of tags to attach to the workspace.
`data.relationships.tag-bindings.data.type`	string	none	Must be `tag-bindings` for each object in the list.
`data.relationships.tag-bindings.data.attributes.key`	string	none	Specifies the tag key for each object in the list.
`data.relationships.tag-bindings.data.attributes.value`	string	none	Specifies the tag value for each object in the list.

Sample Payload

{  "data": {    "attributes": {      "name": "workspace-2",      "resource-count": 0,      "terraform_version": "0.11.1",      "working-directory": "",      "vcs-repo": {        "identifier": "example/terraform-test-proj",        "branch": "",        "ingress-submodules": false,        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ"      },      "updated-at": "2017-11-29T19:18:09.976Z"    },    "relationships": {      "project": {        "data": {          "type": "projects",          "id": "prj-7HWWPGY3fYxztELU"        }      },      "tag-bindings": {        "data": [          {            "type": "tag-bindings",            "attributes": {              "key": "environment",              "value": "development"            }          },        ]      }    },    "type": "workspaces"  }}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request PATCH \  --data @payload.json \  https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-2

Sample Response

{  "data": {    "id": "ws-KTuq99JSzgmDSvYj",    "type": "workspaces",    "attributes": {      "actions": {        "is-destroyable": true      },      "allow-destroy-plan": true,      "apply-duration-average": null,      "assessments-enabled": false,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-activity-duration": null,      "created-at": "2021-08-16T21:50:58.726Z",      "description": null,      "environment": "default",      "execution-mode": "remote",      "file-triggers-enabled": true,      "global-remote-state": false,      "latest-change-at": "2021-08-16T21:50:58.726Z",      "locked": false,      "locked-reason": "",      "name": "workspace-2",      "oauth-client-name": "github example",      "operations": true,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": true,        "can-force-delete": true,        "can-manage-assessments": true,        "can-manage-ephemeral-workspaces": false,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "apply-duration-average": 35000,      "plan-duration-average": 53000,      "policy-check-failures": null,      "queue-all-runs": false,      "resource-count": 10,      "run-failures": 3,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "tag-names": [],      "terraform-version": "1.9.4",      "trigger-prefixes": [],      "vcs-repo": {        "branch": "",        "display-identifier": "example/terraform-test-proj",        "identifier": "example/terraform-test-proj",        "ingress-submodules": false,        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",        "repository-http-url": "https://github.com/example/terraform-test-proj",        "service-provider": "github",        "tags-regex": null,        "webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"      },      "vcs-repo-identifier": "example/terraform-test-proj",      "working-directory": "",      "workspace-kpis-runs-count": null,      "setting-overwrites": {        "execution-mode": true,        "agent-pool": true      }    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-2",      "self-html": "/app/my-organization/workspaces/workspace-2"    },    "relationships": {      "relationships": {      "agent-pool": {        "data": null      },      "current-configuration-version": {        "data": null      },      "current-run": {        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"        }      },      "latest-run": { // Deprecated; same as current-run        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "current-state-version": {        "data": {          "id": "sv-hjy7ndEkmCtn31ps",          "type": "state-versions"        },        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"        }      },      "current-configuration-version": {        "data": {          "id": "cv-hjy7ndEkmCtn31ps",          "type": "configuration-versions"        },        "links": {          "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"        }      },      "current-assessment-result": {        "data": null      },      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "outputs": {        "data": [          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          }        ],        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"        }      },      "project": {        "data": {          "id": "prj-hjy7ndEkmCtn31ps",          "type": "projects"        }      },      "readme": {        "data": null      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"        }      },      "ssh-key": {        "data": {          "id": "sshkey-hjy7ndEkmCtn31ps",          "type": "ssh-keys"        },        "links": {          "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"        }      },      "locked-by": {        "data": {          "id": "user-hjy7ndEkmCtn31ps",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"        }      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"        }      },      "vars": {        "data": [          {            "id": "var-hjy7ndEkmCtn31ps",            "type": "vars"          }        ]      },    }  }}

List workspaces

This endpoint lists workspaces in the organization.

GET /organizations/:organization_name/workspaces

Parameter	Description
`:organization_name`	The name of the organization to list the workspaces of.

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 workspaces per page.
`search[name]`	Optional. If specified, restricts results to workspaces with a name that matches the search string using a fuzzy search.
`search[tags]`	Optional. If specified, restricts results to workspaces with that tag. If multiple comma separated values are specified, results matching all of the tags are returned.
`search[exclude-tags]`	Optional. If specified, results exclude workspaces with that tag. If multiple comma separated values are specified, workspaces with tags matching any of the tags are excluded.
`search[wildcard-name]`	Optional. If specified, restricts results to workspaces with partial matching, using `` on prefix, suffix, or both. For example, `search[wildcard-name]=-prod` returns all workspaces ending in `-prod`, `search[wildcard-name]=prod-` returns all workspaces beginning with `prod-`, and `search[wildcard-name]=-prod-*` returns all workspaces with substring `-prod-` regardless of prefix and/or suffix.
`sort`	Optional. Allows sorting the organization's workspaces by a provided value. You can sort by `"name"`, `"current-run.created-at"` (the time of the current run), and `"latest-change-at"` (the creation time of the latest state version or the workspace itself if no state version exists). Prepending a hyphen to the sort parameter reverses the order. For example, `"-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable.
`filter[project][id]`	Optional. If specified, restricts results to workspaces in the specific project.
`filter[current-run][status]`	Optional. If specified, restricts results to workspaces that match the status of a current run.
`filter[tagged][i][key]`	Optional. If specified, restricts results to workspaces that are tagged with the provided key. Use a value of "0" for `i` if you are only using a single filter. For multiple tag filters, use an incrementing integer value for each filter. Multiple tag filters will be combined together with a logical AND when filtering results.
`filter[tagged][i][value]`	Optional. If specified, restricts results to workspaces that are tagged with the provided value. This is useful when combined with a `key` filter for more specificity. Use a value of "0" for `i` if you are only using a single filter. For multiple tag filters, use an incrementing integer value for each filter. Multiple tag filters will be combined together with a logical AND when filtering results.

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/organizations/my-organization/workspaces

With multiple tag filters

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/organizations/my-organization/workspaces?filter%5B%tagged5D%5B0%5D%5Bkey%5D=environment&filter%5B%tagged5D%5B0%5D%5Bvalue%5D=development&filter%5B%tagged5D%5B1%5D%5Bkey%5D=meets-compliance

Sample Response

{  "data": [    {      "id": "ws-6jrRyVDv1J8zQMB5",      "type": "workspaces",      "attributes": {        "actions": {          "is-destroyable": true        },        "allow-destroy-plan": true,        "assessments-enabled": false,        "auto-apply": false,        "auto-apply-run-trigger": false,        "auto-destroy-at": null,        "auto-destroy-status": null,        "auto-destroy-activity-duration": null,        "inherits-project-auto-destroy": null,        "created-at": "2021-08-16T21:22:49.566Z",        "description": null,        "environment": "default",        "execution-mode": "agent",        "file-triggers-enabled": true,        "global-remote-state": false,        "latest-change-at": "2021-08-16T21:22:49.566Z",        "last-assessment-result-at" : "2021-08-17T21:20:12.908Z",        "locked": true,        "locked-reason": null,        "name": "workspace-1",        "oauth-client-name": null,        "operations": true,        "permissions": {          "can-update": true,          "can-destroy": true,          "can-queue-run": true,          "can-read-run": true,          "can-read-variable": true,          "can-update-variable": true,          "can-read-state-versions": true,          "can-read-state-outputs": true,          "can-create-state-versions": true,          "can-queue-apply": true,          "can-lock": true,          "can-unlock": true,          "can-force-unlock": true,          "can-read-settings": true,          "can-manage-tags": true,          "can-manage-run-tasks": true,          "can-force-delete": true,          "can-manage-assessments": true,          "can-manage-ephemeral-workspaces": false,          "can-read-assessment-results": true,          "can-queue-destroy": true        },        "apply-duration-average": 35000,        "plan-duration-average": 53000,        "policy-check-failures": null,        "queue-all-runs": false,        "resource-count": 10,        "run-failures": 3,        "source": "tfe-api",        "source-name": null,        "source-url": null,        "speculative-enabled": true,        "structured-run-output-enabled": true,        "tag-names": [],        "terraform-version": "1.9.4",        "trigger-prefixes": [],        "updated-at": "2021-08-16T21:22:49.566Z",        "vcs-repo": null,        "vcs-repo-identifier": null,        "working-directory": null,        "workspace-kpis-runs-count": 8,        "setting-overwrites": {          "execution-mode": true,          "agent-pool": true        }      },      "links": {        "self": "/api/v2/organizations/my-organization/workspaces/workspace-1",        "self-html": "/app/my-organization/workspaces/workspace-1"      },      "relationships": {        "agent-pool": {          "data": {            "id": "apool-QxGd2tRjympfMvQc",            "type": "agent-pools"          }        },        "current-configuration-version": {          "data": null        },        "current-run": {          "data": {            "id": "run-hjy7ndEkmCtn31ps",            "type": "runs"          },          "links": {            "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"          }        },        "effective-tag-bindings": {          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"          }        },        "latest-run": { // Deprecated; same as current-run          "data": {            "id": "run-hjy7ndEkmCtn31ps",            "type": "runs"          },          "links": {            "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"          }        },        "current-state-version": {          "data": {            "id": "sv-hjy7ndEkmCtn31ps",            "type": "state-versions"          },          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"          }        },        "current-configuration-version": {          "data": {            "id": "cv-hjy7ndEkmCtn31ps",            "type": "configuration-versions"          },          "links": {            "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"          }        },        "current-assessment-result": {          "data": null        },        "organization": {          "data": {            "id": "my-organization",            "type": "organizations"          }        },        "outputs": {          "data": [            {              "id": "wsout-hjy7ndEkmCtn31ps",              "type": "workspace-outputs"            },            {              "id": "wsout-hjy7ndEkmCtn31ps",              "type": "workspace-outputs"            }          ],          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"          }        },        "project": {          "data": {            "id": "prj-hjy7ndEkmCtn31ps",            "type": "projects"          }        },        "readme": {          "data": null        },        "remote-state-consumers": {          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"          }        },        "ssh-key": {          "data": {            "id": "sshkey-hjy7ndEkmCtn31ps",            "type": "ssh-keys"          },          "links": {            "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"          }        },        "locked-by": {          "data": {            "id": "user-hjy7ndEkmCtn31ps",            "type": "users"          },          "links": {            "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"          }        },        "tag-bindings": {          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"          }        },        "vars": {          "data": [            {              "id": "var-hjy7ndEkmCtn31ps",              "type": "vars"            }          ]        },      }    },  ],  "links": {    "first": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "last": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "next": null,    "prev": null,    "self": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20"  },  "meta": {    "pagination": {      "current-page": 1,      "next-page": null,      "page-size": 20,      "prev-page": null,      "total-count": 1,      "total-pages": 1    }  }}

Show workspace

Details on a workspace can be retrieved from two endpoints, which behave identically.

One refers to a workspace by its ID:

GET /workspaces/:workspace_id

Parameter	Description
`:workspace_id`	The workspace ID

The other refers to a workspace by its name and organization:

GET /organizations/:organization_name/workspaces/:name

Parameter	Description
`:organization_name`	The name of the organization the workspace belongs to.
`:name`	The name of the workspace to show details for, which can only include letters, numbers, `-`, and `_`.

Workspace performance attributes

The following attributes are helpful in determining the overall health and performance of your workspace configuration. These metrics refer to the past 30 runs that have either resulted in an error or successfully applied.

Parameter	Type	Description
`data.attributes.apply-duration-average`	number	This is the average time runs spend in the apply phase, represented in milliseconds
`data.attributes.plan-duration-average`	number	This is the average time runs spend in the plan phase, represented in milliseconds
`data.attributes.policy-check-failures`	number	Reports the number of run failures resulting from a policy check failure
`data.attributes.run-failures`	number	Reports the number of failed runs
`data.attributes.workspace-kpis-run-count`	number	Total number of runs taken into account by these metrics

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-1

Sample Response

{  "data": {    "id": "ws-6jrRyVDv1J8zQMB5",    "type": "workspaces",    "attributes": {      "actions": {        "is-destroyable": true      },      "allow-destroy-plan": true,      "assessments-enabled": false,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-status": null,      "auto-destroy-activity-duration": null,      "inherits-project-auto-destroy": null,      "created-at": "2021-08-16T21:22:49.566Z",      "description": null,      "environment": "default",      "execution-mode": "agent",      "file-triggers-enabled": true,      "global-remote-state": false,      "latest-change-at": "2021-08-16T21:22:49.566Z",      "last-assessment-result-at" : "2021-08-17T21:20:12.908Z",      "locked": true,      "locked-reason": null,      "name": "workspace-1",      "oauth-client-name": null,      "operations": true,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": true,        "can-force-delete": true,        "can-manage-assessments": true,        "can-manage-ephemeral-workspaces": false,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "apply-duration-average": 35000,      "plan-duration-average": 53000,      "policy-check-failures": null,      "queue-all-runs": false,      "resource-count": 10,      "run-failures": 3,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "tag-names": [],      "terraform-version": "1.9.4",      "trigger-prefixes": [],      "updated-at": "2021-08-16T21:22:49.566Z",      "vcs-repo": null,      "vcs-repo-identifier": null,      "working-directory": null,      "workspace-kpis-runs-count": 8,      "setting-overwrites": {        "execution-mode": true,        "agent-pool": true      }    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-1",      "self-html": "/app/my-organization/workspaces/workspace-1"    },    "relationships": {      "agent-pool": {        "data": {          "id": "apool-QxGd2tRjympfMvQc",          "type": "agent-pools"        }      },      "current-configuration-version": {        "data": null      },      "current-run": {        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"        }      },      "latest-run": { // Deprecated; same as current-run        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "current-state-version": {        "data": {          "id": "sv-hjy7ndEkmCtn31ps",          "type": "state-versions"        },        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"        }      },      "current-configuration-version": {        "data": {          "id": "cv-hjy7ndEkmCtn31ps",          "type": "configuration-versions"        },        "links": {          "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"        }      },      "current-assessment-result": {        "data": null      },      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "outputs": {        "data": [          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          },          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          }        ],        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"        }      },      "project": {        "data": {          "id": "prj-hjy7ndEkmCtn31ps",          "type": "projects"        }      },      "readme": {        "data": null      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"        }      },      "ssh-key": {        "data": {          "id": "sshkey-hjy7ndEkmCtn31ps",          "type": "ssh-keys"        },        "links": {          "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"        }      },      "locked-by": {        "data": {          "id": "user-hjy7ndEkmCtn31ps",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"        }      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"        }      },      "vars": {        "data": [          {            "id": "var-hjy7ndEkmCtn31ps",            "type": "vars"          }        ]      },    }  }}

Safe Delete a workspace

When you delete an HCP Terraform workspace with resources, Terraform can no longer track or manage that infrastructure. During a safe delete, HCP Terraform only deletes the workspace if it is not managing resources.

You can safe delete a workspace using two endpoints that behave identically. The first endpoint identifies a workspace with the workspace ID, and the other identifies the workspace by its name and organization.

POST /workspaces/:workspace_id/actions/safe-delete

Parameter	Description
`:workspace_id`	The ID of the workspace to delete.

POST /organizations/:organization_name/workspaces/:name/actions/safe-delete

Parameter	Description
`:organization_name`	The name of the workspace's organization.
`:name`	The name of the workspace to delete, which can only include letters, numbers, `-`, and `_`.

Status	Response	Reason(s)
204	No Content	Successfully deleted the workspace
404	JSON API error object	Workspace not found, or user unauthorized to perform workspace delete
409	JSON API error object	Workspace is not safe to delete because it is managing resources

Force Delete a workspace

During a force delete, HCP Terraform removes the specified workspace without checking whether it is managing resources. We recommend using the safe delete endpoint instead, when possible.

Warning: Terraform cannot track or manage the workspace's infrastructure after deletion. We recommend destroying the workspace's infrastructure before you delete it.

By default, only organization owners can force delete workspaces. Organization owners can also update [organization's settings](/terraform/cloud-docs/users-teams organizations/organizations#general) to let workspace admins force delete their own workspaces.

You can use two endpoints to force delete a workspace, which behave identically. One endpoint identifies the workspace with its workspace ID and the other endpoint identifies the workspace with its name and organization.

DELETE /workspaces/:workspace_id

Parameter	Description
`:workspace_id`	The ID of the workspace to delete

DELETE /organizations/:organization_name/workspaces/:name

Parameter	Description
`:organization_name`	The name of the organization the workspace belongs to.
`:name`	The name of the workspace to delete, which can only include letters, numbers, `-`, and `_`.

Status	Response	Reason(s)
204	No Content	Successfully deleted the workspace
403	JSON API error object	Not authorized to perform a force delete on the workspace
404	JSON API error object	Workspace not found, or user unauthorized to perform workspace delete

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request DELETE \  https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-1

Lock a workspace

This endpoint locks a workspace.

POST /workspaces/:workspace_id/actions/lock

Parameter	Description
`:workspace_id`	The workspace ID to lock. Obtain this from the workspace settings or the Show Workspace endpoint.

Status	Response	Reason(s)
200	JSON API document (`type: "workspaces"`)	Successfully locked the workspace
404	JSON API error object	Workspace not found, or user unauthorized to perform action
409	JSON API error object	Workspace already locked

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
`reason`	string	`""`	The reason for locking the workspace.

Sample Payload

{  "reason": "Locking workspace-1"}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/lock

Sample Response

{  "data": {    "id": "ws-6jrRyVDv1J8zQMB5",    "type": "workspaces",    "attributes": {      "actions": {        "is-destroyable": true      },      "allow-destroy-plan": true,      "assessments-enabled": false,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-status": null,      "auto-destroy-activity-duration": null,      "inherits-project-auto-destroy": null,      "created-at": "2021-08-16T21:22:49.566Z",      "description": null,      "environment": "default",      "execution-mode": "agent",      "file-triggers-enabled": true,      "global-remote-state": false,      "latest-change-at": "2021-08-16T21:22:49.566Z",      "last-assessment-result-at" : "2021-08-17T21:20:12.908Z",      "locked": true,      "locked-reason": null,      "name": "workspace-1",      "oauth-client-name": null,      "operations": true,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": true,        "can-force-delete": true,        "can-manage-assessments": true,        "can-manage-ephemeral-workspaces": false,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "apply-duration-average": 35000,      "plan-duration-average": 53000,      "policy-check-failures": null,      "queue-all-runs": false,      "resource-count": 10,      "run-failures": 3,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "tag-names": [],      "terraform-version": "1.9.4",      "trigger-prefixes": [],      "updated-at": "2021-08-16T21:22:49.566Z",      "vcs-repo": null,      "vcs-repo-identifier": null,      "working-directory": null,      "workspace-kpis-runs-count": 8,      "setting-overwrites": {        "execution-mode": true,        "agent-pool": true      }    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-1",      "self-html": "/app/my-organization/workspaces/workspace-1"    },    "relationships": {      "agent-pool": {        "data": {          "id": "apool-QxGd2tRjympfMvQc",          "type": "agent-pools"        }      },      "current-configuration-version": {        "data": null      },      "current-run": {        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"        }      },      "latest-run": { // Deprecated; same as current-run        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "current-state-version": {        "data": {          "id": "sv-hjy7ndEkmCtn31ps",          "type": "state-versions"        },        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"        }      },      "current-configuration-version": {        "data": {          "id": "cv-hjy7ndEkmCtn31ps",          "type": "configuration-versions"        },        "links": {          "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"        }      },      "current-assessment-result": {        "data": null      },      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "outputs": {        "data": [          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          },          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          }        ],        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"        }      },      "project": {        "data": {          "id": "prj-hjy7ndEkmCtn31ps",          "type": "projects"        }      },      "readme": {        "data": null      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"        }      },      "ssh-key": {        "data": {          "id": "sshkey-hjy7ndEkmCtn31ps",          "type": "ssh-keys"        },        "links": {          "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"        }      },      "locked-by": {        "data": {          "id": "user-hjy7ndEkmCtn31ps",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"        }      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"        }      },      "vars": {        "data": [          {            "id": "var-hjy7ndEkmCtn31ps",            "type": "vars"          }        ]      },    }  }}

Unlock a workspace

This endpoint unlocks a workspace. Unlocking a workspace sets the current state version to the latest finalized intermediate state version. If intermediate state versions are available, but HCP Terraform has not yet finalized the latest intermediate state version, the unlock will fail with a 503 response. For this particular error, it's recommended to retry the unlock operation for a short period of time until the platform finalizes the state version. If you must force-unlock a workspace under these conditions, ensure that state was saved successfully by inspecting the latest state version using the State Version List API

POST /workspaces/:workspace_id/actions/unlock

Parameter	Description
`:workspace_id`	The workspace ID to unlock. Obtain this from the workspace settings or the Show Workspace endpoint.

Status	Response	Reason(s)
200	JSON API document (`type: "workspaces"`)	Successfully unlocked the workspace
404	JSON API error object	Workspace not found, or user unauthorized to perform action
409	JSON API error object	Workspace already unlocked, or locked by a different user

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/unlock

Sample Response

{  "data": {    "id": "ws-6jrRyVDv1J8zQMB5",    "type": "workspaces",    "attributes": {      "actions": {        "is-destroyable": true      },      "allow-destroy-plan": true,      "assessments-enabled": false,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-status": null,      "auto-destroy-activity-duration": null,      "inherits-project-auto-destroy": null,      "created-at": "2021-08-16T21:22:49.566Z",      "description": null,      "environment": "default",      "execution-mode": "agent",      "file-triggers-enabled": true,      "global-remote-state": false,      "latest-change-at": "2021-08-16T21:22:49.566Z",      "last-assessment-result-at" : "2021-08-17T21:20:12.908Z",      "locked": true,      "locked-reason": null,      "name": "workspace-1",      "oauth-client-name": null,      "operations": true,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": true,        "can-force-delete": true,        "can-manage-assessments": true,        "can-manage-ephemeral-workspaces": false,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "apply-duration-average": 35000,      "plan-duration-average": 53000,      "policy-check-failures": null,      "queue-all-runs": false,      "resource-count": 10,      "run-failures": 3,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "tag-names": [],      "terraform-version": "1.9.4",      "trigger-prefixes": [],      "updated-at": "2021-08-16T21:22:49.566Z",      "vcs-repo": null,      "vcs-repo-identifier": null,      "working-directory": null,      "workspace-kpis-runs-count": 8,      "setting-overwrites": {        "execution-mode": true,        "agent-pool": true      }    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-1",      "self-html": "/app/my-organization/workspaces/workspace-1"    },    "relationships": {      "agent-pool": {        "data": {          "id": "apool-QxGd2tRjympfMvQc",          "type": "agent-pools"        }      },      "current-configuration-version": {        "data": null      },      "current-run": {        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"        }      },      "latest-run": { // Deprecated; same as current-run        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "current-state-version": {        "data": {          "id": "sv-hjy7ndEkmCtn31ps",          "type": "state-versions"        },        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"        }      },      "current-configuration-version": {        "data": {          "id": "cv-hjy7ndEkmCtn31ps",          "type": "configuration-versions"        },        "links": {          "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"        }      },      "current-assessment-result": {        "data": null      },      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "outputs": {        "data": [          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          },          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          }        ],        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"        }      },      "project": {        "data": {          "id": "prj-hjy7ndEkmCtn31ps",          "type": "projects"        }      },      "readme": {        "data": null      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"        }      },      "ssh-key": {        "data": {          "id": "sshkey-hjy7ndEkmCtn31ps",          "type": "ssh-keys"        },        "links": {          "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"        }      },      "locked-by": {        "data": {          "id": "user-hjy7ndEkmCtn31ps",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"        }      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"        }      },      "vars": {        "data": [          {            "id": "var-hjy7ndEkmCtn31ps",            "type": "vars"          }        ]      },    }  }}

Force Unlock a workspace

This endpoint force unlocks a workspace. Only users with admin access are authorized to force unlock a workspace.

POST /workspaces/:workspace_id/actions/force-unlock

Parameter	Description
`:workspace_id`	The workspace ID to force unlock. Obtain this from the workspace settings or the Show Workspace endpoint.

Status	Response	Reason(s)
200	JSON API document (`type: "workspaces"`)	Successfully force unlocked the workspace
404	JSON API error object	Workspace not found, or user unauthorized to perform action
409	JSON API error object	Workspace already unlocked

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/force-unlock

Sample Response

{  "data": {    "id": "ws-KTuq99JSzgmDSvYj",    "type": "workspaces",    "attributes": {      "actions": {        "is-destroyable": true      },      "allow-destroy-plan": true,      "apply-duration-average": null,      "assessments-enabled": false,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-activity-duration": null,      "created-at": "2021-08-16T21:50:58.726Z",      "description": null,      "environment": "default",      "execution-mode": "remote",      "file-triggers-enabled": true,      "global-remote-state": false,      "latest-change-at": "2021-08-16T21:50:58.726Z",      "locked": false,      "locked-reason": "",      "name": "workspace-2",      "oauth-client-name": "github example",      "operations": true,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": true,        "can-force-delete": true,        "can-manage-assessments": true,        "can-manage-ephemeral-workspaces": false,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "apply-duration-average": 35000,      "plan-duration-average": 53000,      "policy-check-failures": null,      "queue-all-runs": false,      "resource-count": 10,      "run-failures": 3,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "tag-names": [],      "terraform-version": "1.9.4",      "trigger-prefixes": [],      "vcs-repo": {        "branch": "",        "display-identifier": "example/terraform-test-proj",        "identifier": "example/terraform-test-proj",        "ingress-submodules": false,        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",        "repository-http-url": "https://github.com/example/terraform-test-proj",        "service-provider": "github",        "tags-regex": null,        "webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"      },      "vcs-repo-identifier": "example/terraform-test-proj",      "working-directory": "",      "workspace-kpis-runs-count": null,      "setting-overwrites": {        "execution-mode": true,        "agent-pool": true      }    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-2",      "self-html": "/app/my-organization/workspaces/workspace-2"    },    "relationships": {      "relationships": {      "agent-pool": {        "data": null      },      "current-configuration-version": {        "data": null      },      "current-run": {        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"        }      },      "latest-run": { // Deprecated; same as current-run        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "current-state-version": {        "data": {          "id": "sv-hjy7ndEkmCtn31ps",          "type": "state-versions"        },        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"        }      },      "current-configuration-version": {        "data": {          "id": "cv-hjy7ndEkmCtn31ps",          "type": "configuration-versions"        },        "links": {          "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"        }      },      "current-assessment-result": {        "data": null      },      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "outputs": {        "data": [          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          }        ],        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"        }      },      "project": {        "data": {          "id": "prj-hjy7ndEkmCtn31ps",          "type": "projects"        }      },      "readme": {        "data": null      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"        }      },      "ssh-key": {        "data": {          "id": "sshkey-hjy7ndEkmCtn31ps",          "type": "ssh-keys"        },        "links": {          "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"        }      },      "locked-by": {        "data": {          "id": "user-hjy7ndEkmCtn31ps",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"        }      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"        }      },      "vars": {        "data": [          {            "id": "var-hjy7ndEkmCtn31ps",            "type": "vars"          }        ]      },    }  }}

Assign an SSH key to a workspace

This endpoint assigns an SSH key to a workspace.

PATCH /workspaces/:workspace_id/relationships/ssh-key

Parameter	Description
`:workspace_id`	The workspace ID to assign the SSH key to. Obtain this from the workspace settings or the Show Workspace endpoint.

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 `"workspaces"`.
`data.attributes.id`	string		The SSH key ID to assign. Obtain this from the ssh-keys endpoint.

Sample Payload

{  "data": {    "attributes": {      "id": "sshkey-GxrePWre1Ezug7aM"    },    "type": "workspaces"  }}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request PATCH \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/ssh-key

Sample Response

{  "data": {    "id": "ws-KTuq99JSzgmDSvYj",    "type": "workspaces",    "attributes": {      "actions": {        "is-destroyable": true      },      "allow-destroy-plan": true,      "apply-duration-average": null,      "assessments-enabled": false,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-activity-duration": null,      "created-at": "2021-08-16T21:50:58.726Z",      "description": null,      "environment": "default",      "execution-mode": "remote",      "file-triggers-enabled": true,      "global-remote-state": false,      "latest-change-at": "2021-08-16T21:50:58.726Z",      "locked": false,      "locked-reason": "",      "name": "workspace-2",      "oauth-client-name": "github example",      "operations": true,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": true,        "can-force-delete": true,        "can-manage-assessments": true,        "can-manage-ephemeral-workspaces": false,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "apply-duration-average": 35000,      "plan-duration-average": 53000,      "policy-check-failures": null,      "queue-all-runs": false,      "resource-count": 10,      "run-failures": 3,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "tag-names": [],      "terraform-version": "1.9.4",      "trigger-prefixes": [],      "vcs-repo": {        "branch": "",        "display-identifier": "example/terraform-test-proj",        "identifier": "example/terraform-test-proj",        "ingress-submodules": false,        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",        "repository-http-url": "https://github.com/example/terraform-test-proj",        "service-provider": "github",        "tags-regex": null,        "webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"      },      "vcs-repo-identifier": "example/terraform-test-proj",      "working-directory": "",      "workspace-kpis-runs-count": null,      "setting-overwrites": {        "execution-mode": true,        "agent-pool": true      }    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-2",      "self-html": "/app/my-organization/workspaces/workspace-2"    },    "relationships": {      "relationships": {      "agent-pool": {        "data": null      },      "current-configuration-version": {        "data": null      },      "current-run": {        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"        }      },      "latest-run": { // Deprecated; same as current-run        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "current-state-version": {        "data": {          "id": "sv-hjy7ndEkmCtn31ps",          "type": "state-versions"        },        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"        }      },      "current-configuration-version": {        "data": {          "id": "cv-hjy7ndEkmCtn31ps",          "type": "configuration-versions"        },        "links": {          "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"        }      },      "current-assessment-result": {        "data": null      },      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "outputs": {        "data": [          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          }        ],        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"        }      },      "project": {        "data": {          "id": "prj-hjy7ndEkmCtn31ps",          "type": "projects"        }      },      "readme": {        "data": null      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"        }      },      "ssh-key": {        "data": {          "id": "sshkey-hjy7ndEkmCtn31ps",          "type": "ssh-keys"        },        "links": {          "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"        }      },      "locked-by": {        "data": {          "id": "user-hjy7ndEkmCtn31ps",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"        }      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"        }      },      "vars": {        "data": [          {            "id": "var-hjy7ndEkmCtn31ps",            "type": "vars"          }        ]      },    }  }}

Unassign an SSH key from a workspace

This endpoint unassigns the currently assigned SSH key from a workspace.

PATCH /workspaces/:workspace_id/relationships/ssh-key

Parameter	Description
`:workspace_id`	The workspace ID to assign the SSH key to. Obtain this from the workspace settings or the Show Workspace endpoint.

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 `"workspaces"`.
`data.attributes.id`	string		Must be `null`.

Sample Payload

{  "data": {    "attributes": {      "id": null    },    "type": "workspaces"  }}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request PATCH \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/ssh-key

Sample Response

{  "data": {    "id": "ws-KTuq99JSzgmDSvYj",    "type": "workspaces",    "attributes": {      "actions": {        "is-destroyable": true      },      "allow-destroy-plan": true,      "apply-duration-average": null,      "assessments-enabled": false,      "auto-apply": false,      "auto-apply-run-trigger": false,      "auto-destroy-at": null,      "auto-destroy-activity-duration": null,      "created-at": "2021-08-16T21:50:58.726Z",      "description": null,      "environment": "default",      "execution-mode": "remote",      "file-triggers-enabled": true,      "global-remote-state": false,      "latest-change-at": "2021-08-16T21:50:58.726Z",      "locked": false,      "locked-reason": "",      "name": "workspace-2",      "oauth-client-name": "github example",      "operations": true,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-queue-run": true,        "can-read-run": true,        "can-read-variable": true,        "can-update-variable": true,        "can-read-state-versions": true,        "can-read-state-outputs": true,        "can-create-state-versions": true,        "can-queue-apply": true,        "can-lock": true,        "can-unlock": true,        "can-force-unlock": true,        "can-read-settings": true,        "can-manage-tags": true,        "can-manage-run-tasks": true,        "can-force-delete": true,        "can-manage-assessments": true,        "can-manage-ephemeral-workspaces": false,        "can-read-assessment-results": true,        "can-queue-destroy": true      },      "apply-duration-average": 35000,      "plan-duration-average": 53000,      "policy-check-failures": null,      "queue-all-runs": false,      "resource-count": 10,      "run-failures": 3,      "source": "tfe-api",      "source-name": null,      "source-url": null,      "speculative-enabled": true,      "structured-run-output-enabled": true,      "tag-names": [],      "terraform-version": "1.9.4",      "trigger-prefixes": [],      "vcs-repo": {        "branch": "",        "display-identifier": "example/terraform-test-proj",        "identifier": "example/terraform-test-proj",        "ingress-submodules": false,        "oauth-token-id": "ot-hmAyP66qk2AMVdbJ",        "repository-http-url": "https://github.com/example/terraform-test-proj",        "service-provider": "github",        "tags-regex": null,        "webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"      },      "vcs-repo-identifier": "example/terraform-test-proj",      "working-directory": "",      "workspace-kpis-runs-count": null,      "setting-overwrites": {        "execution-mode": true,        "agent-pool": true      }    },    "links": {      "self": "/api/v2/organizations/my-organization/workspaces/workspace-2",      "self-html": "/app/my-organization/workspaces/workspace-2"    },    "relationships": {      "relationships": {      "agent-pool": {        "data": null      },      "current-configuration-version": {        "data": null      },      "current-run": {        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "effective-tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"        }      },      "latest-run": { // Deprecated; same as current-run        "data": {          "id": "run-hjy7ndEkmCtn31ps",          "type": "runs"        },        "links": {          "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"        }      },      "current-state-version": {        "data": {          "id": "sv-hjy7ndEkmCtn31ps",          "type": "state-versions"        },        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"        }      },      "current-configuration-version": {        "data": {          "id": "cv-hjy7ndEkmCtn31ps",          "type": "configuration-versions"        },        "links": {          "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"        }      },      "current-assessment-result": {        "data": null      },      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        }      },      "outputs": {        "data": [          {            "id": "wsout-hjy7ndEkmCtn31ps",            "type": "workspace-outputs"          }        ],        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"        }      },      "project": {        "data": {          "id": "prj-hjy7ndEkmCtn31ps",          "type": "projects"        }      },      "readme": {        "data": null      },      "remote-state-consumers": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"        }      },      "ssh-key": {        "data": {          "id": "sshkey-hjy7ndEkmCtn31ps",          "type": "ssh-keys"        },        "links": {          "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"        }      },      "locked-by": {        "data": {          "id": "user-hjy7ndEkmCtn31ps",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"        }      },      "tag-bindings": {        "links": {          "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"        }      },      "vars": {        "data": [          {            "id": "var-hjy7ndEkmCtn31ps",            "type": "vars"          }        ]      },    }  }}

Get Remote State Consumers

GET /workspaces/:workspace_id/relationships/remote-state-consumers

Parameter	Description
`:workspace_id`	The workspace ID to get remote state consumers for. Obtain this from the workspace settings or the Show Workspace endpoint.

This endpoint retrieves the list of other workspaces that are allowed to access the given workspace's state during runs.

If global-remote-state is set to false for the workspace, this will return the list of other workspaces that are specifically authorized to access the workspace's state.
If global-remote-state is set to true, this will return a list of every workspace in the organization except for the subject workspace.

The list returned by this endpoint is subject to the caller's normal workspace permissions; it will not include workspaces that the provided API token is unable to read.

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 workspaces per page.

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/remote-state-consumers

Sample Response

{  "data": [    {      "id": "ws-6jrRyVDv1J8zQMB5",      "type": "workspaces",      "attributes": {        "actions": {          "is-destroyable": true        },        "allow-destroy-plan": true,        "assessments-enabled": false,        "auto-apply": false,        "auto-apply-run-trigger": false,        "auto-destroy-at": null,        "auto-destroy-status": null,        "auto-destroy-activity-duration": null,        "inherits-project-auto-destroy": null,        "created-at": "2021-08-16T21:22:49.566Z",        "description": null,        "environment": "default",        "execution-mode": "agent",        "file-triggers-enabled": true,        "global-remote-state": false,        "latest-change-at": "2021-08-16T21:22:49.566Z",        "last-assessment-result-at" : "2021-08-17T21:20:12.908Z",        "locked": true,        "locked-reason": null,        "name": "workspace-1",        "oauth-client-name": null,        "operations": true,        "permissions": {          "can-update": true,          "can-destroy": true,          "can-queue-run": true,          "can-read-run": true,          "can-read-variable": true,          "can-update-variable": true,          "can-read-state-versions": true,          "can-read-state-outputs": true,          "can-create-state-versions": true,          "can-queue-apply": true,          "can-lock": true,          "can-unlock": true,          "can-force-unlock": true,          "can-read-settings": true,          "can-manage-tags": true,          "can-manage-run-tasks": true,          "can-force-delete": true,          "can-manage-assessments": true,          "can-manage-ephemeral-workspaces": false,          "can-read-assessment-results": true,          "can-queue-destroy": true        },        "apply-duration-average": 35000,        "plan-duration-average": 53000,        "policy-check-failures": null,        "queue-all-runs": false,        "resource-count": 10,        "run-failures": 3,        "source": "tfe-api",        "source-name": null,        "source-url": null,        "speculative-enabled": true,        "structured-run-output-enabled": true,        "tag-names": [],        "terraform-version": "1.9.4",        "trigger-prefixes": [],        "updated-at": "2021-08-16T21:22:49.566Z",        "vcs-repo": null,        "vcs-repo-identifier": null,        "working-directory": null,        "workspace-kpis-runs-count": 8,        "setting-overwrites": {          "execution-mode": true,          "agent-pool": true        }      },      "links": {        "self": "/api/v2/organizations/my-organization/workspaces/workspace-1",        "self-html": "/app/my-organization/workspaces/workspace-1"      },      "relationships": {        "agent-pool": {          "data": {            "id": "apool-QxGd2tRjympfMvQc",            "type": "agent-pools"          }        },        "current-configuration-version": {          "data": null        },        "current-run": {          "data": {            "id": "run-hjy7ndEkmCtn31ps",            "type": "runs"          },          "links": {            "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"          }        },        "effective-tag-bindings": {          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/effective-tag-bindings"          }        },        "latest-run": { // Deprecated; same as current-run          "data": {            "id": "run-hjy7ndEkmCtn31ps",            "type": "runs"          },          "links": {            "related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"          }        },        "current-state-version": {          "data": {            "id": "sv-hjy7ndEkmCtn31ps",            "type": "state-versions"          },          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"          }        },        "current-configuration-version": {          "data": {            "id": "cv-hjy7ndEkmCtn31ps",            "type": "configuration-versions"          },          "links": {            "related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"          }        },        "current-assessment-result": {          "data": null        },        "organization": {          "data": {            "id": "my-organization",            "type": "organizations"          }        },        "outputs": {          "data": [            {              "id": "wsout-hjy7ndEkmCtn31ps",              "type": "workspace-outputs"            },            {              "id": "wsout-hjy7ndEkmCtn31ps",              "type": "workspace-outputs"            }          ],          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"          }        },        "project": {          "data": {            "id": "prj-hjy7ndEkmCtn31ps",            "type": "projects"          }        },        "readme": {          "data": null        },        "remote-state-consumers": {          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"          }        },        "ssh-key": {          "data": {            "id": "sshkey-hjy7ndEkmCtn31ps",            "type": "ssh-keys"          },          "links": {            "related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"          }        },        "locked-by": {          "data": {            "id": "user-hjy7ndEkmCtn31ps",            "type": "users"          },          "links": {            "related": "/api/v2/users/user-hjy7ndEkmCtn31ps"          }        },        "tag-bindings": {          "links": {            "related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/tag-bindings"          }        },        "vars": {          "data": [            {              "id": "var-hjy7ndEkmCtn31ps",              "type": "vars"            }          ]        },      }    },  ],  "links": {    "first": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "last": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "next": null,    "prev": null,    "self": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20"  },  "meta": {    "pagination": {      "current-page": 1,      "next-page": null,      "page-size": 20,      "prev-page": null,      "total-count": 1,      "total-pages": 1    }  }}

Replace Remote State Consumers

PATCH /workspaces/:workspace_id/relationships/remote-state-consumers

Parameter	Description
`:workspace_id`	The workspace ID to replace remote state consumers for. Obtain this from the workspace settings or the Show Workspace endpoint.

This endpoint updates the workspace's remote state consumers to be exactly the list of workspaces specified in the payload. It can only be used for workspaces where global-remote-state is false.

This endpoint can only be used by teams with permission to manage workspaces for the entire organization — only those who can view the entire list of consumers can replace the entire list. (More about permissions.) Teams with admin permissions on specific workspaces can still modify remote state consumers for those workspaces, but must use the add (POST) and remove (DELETE) endpoints listed below instead of this PATCH endpoint.

Status	Response	Reason(s)
204	No Content	Successfully updated remote state consumers
404	JSON API error object	Workspace not found, or user unauthorized to perform action
422	JSON API error object	Problem with payload or request; details provided in the error object

Request Body

This PATCH 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 `"workspaces"`.
`data[].id`	string		The ID of a workspace to be set as a remote state consumer.

Sample Payload

{  "data": [    {      "id": "ws-7aiqKYf6ejMFdtWS",      "type": "workspaces"    }  ]}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request PATCH \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/remote-state-consumers

Response

No response body.

Status code 204.

Add Remote State Consumers

POST /workspaces/:workspace_id/relationships/remote-state-consumers

Parameter	Description
`:workspace_id`	The workspace ID to add remote state consumers for. Obtain this from the workspace settings or the Show Workspace endpoint.

This endpoint adds one or more remote state consumers to the workspace. It can only be used for workspaces where global-remote-state is false.

The workspaces specified as consumers must be readable to the API token that makes the request.
A workspace cannot be added as a consumer of itself. (A workspace can always read its own state, regardless of access settings.)
You can safely add a consumer workspace that is already present; it will be ignored, and the rest of the consumers in the request will be processed normally.

Status	Response	Reason(s)
204	No Content	Successfully updated remote state consumers
404	JSON API error object	Workspace not found, or user unauthorized to perform action
422	JSON API error object	Problem with payload or request; details provided in the error object

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 `"workspaces"`.
`data[].id`	string		The ID of a workspace to be set as a remote state consumer.

Sample Payload

{  "data": [    {      "id": "ws-7aiqKYf6ejMFdtWS",      "type": "workspaces"    }  ]}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/remote-state-consumers

Response

No response body.

Status code 204.

Delete Remote State Consumers

DELETE /workspaces/:workspace_id/relationships/remote-state-consumers

Parameter	Description
`:workspace_id`	The workspace ID to remove remote state consumers for. Obtain this from the workspace settings or the Show Workspace endpoint.

This endpoint removes one or more remote state consumers from a workspace, according to the contents of the payload. It can only be used for workspaces where global-remote-state is false.

The workspaces specified as consumers must be readable to the API token that makes the request.
You can safely remove a consumer workspace that is already absent; it will be ignored, and the rest of the consumers in the request will be processed normally.

Status	Response	Reason(s)
204	No Content	Successfully updated remote state consumers
404	JSON API error object	Workspace not found, or user unauthorized to perform action
422	JSON API error object	Problem with payload or request; details provided in the error object

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 `"workspaces"`.
`data[].id`	string		The ID of a workspace to remove from the remote state consumers.

Sample Payload

{  "data": [    {      "id": "ws-7aiqKYf6ejMFdtWS",      "type": "workspaces"    }  ]}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request DELETE \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/remote-state-consumers

Response

No response body.

Status code 204.

List workspace tags

Workspace tags are organization tags added to a workspace. They are a flat list of keys that can only be applied to workspaces when using the tags attribute in the Terraform CLI cloud block < 1.10. The more contemporary form of key/value tags can be listed using List workspace tag bindings - See below.

GET /workspaces/:workspace_id/relationships/tags: Paginated list of flat string tags attached to the workspace.

Path parameters

Parameter	Description
`:workspace_id`	The workspace ID to fetch tags for. Obtain this from the workspace settings or the Show Workspace endpoint.

Query Parameters

Only the flat string tags endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs. Conversely, all tags are returned when using fetching tag-bindings or effective-tag-bindings endpoints.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 workspaces per page.

Sample Requests

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/workspaces/ws-db61c9eb5cab5ae2/relationships/tags

Sample Responses

{  "data": [    {      "id": "tag-1",      "type": "tags",      "attributes": {        "name": "tag1",        "created-at":  "2022-03-09T06:04:39.585Z",        "instance-count": 1      },      "relationships": {        "organization": {          "data": {            "id": "my-organization",            "type": "organizations"          }        }      }    },    {      "id": "tag-2",      "type": "tags",      "attributes": {        "name": "tag2",        "created-at":  "2022-03-09T06:04:39.585Z",        "instance-count": 2      },      "relationships": {        "organization": {          "data": {            "id": "my-organization",            "type": "organizations"          }        }      }    }  ]}

List workspace tag bindings

Call the following endpoints to list the tags attached to a workspace:

GET /workspaces/:workspace_id/tag-bindings: Lists key-value tags directly bound to the workspace.
GET /workspaces/:workspace_id/effective-tag-bindings: Lists all key-value tags bound to the workspace, including those inherited from the parent project.

Path parameters

Parameter	Description
`:workspace_id`	The workspace ID to fetch tags for. Obtain this from the workspace settings or the Show Workspace endpoint.

Sample Requests

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/workspaces/ws-db61c9eb5cab5ae2/tag-bindings

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/workspaces/ws-db61c9eb5cab5ae2/effective-tag-bindings

Sample Responses

{  "data": [    {      "id": "tb-232e23631380f79e",      "type": "tag-bindings",      "attributes": {        "key": "costcenter",        "value": "123",        "created-at": "2024-11-19T23:59:24.648Z"      }    }  ],  "links": {    "target": "/api/v2/workspaces/ws-db61c9eb5cab5ae2"  }}

{  "data": [    {      "id": "07cc44202a430fc2",      "type": "effective-tag-bindings",      "attributes": {        "key": "costcenter",        "value": "123"      }    },    {      "id": "f8b11951f98e11f8",      "type": "effective-tag-bindings",      "attributes": {        "key": "dept",        "value": "r+d"      },      "relationships": {        "inherited-from": {          "links": {            "related": "/api/v2/projects/prj-af7d174fa1ea7423"          }        }      }    }  ]}

Add flat string tags to a workspace

POST /workspaces/:workspace_id/relationships/tags

To add key-value tags to an existing workspace, call the PATCH /workspaces/:workspace_id and provide workspace tag bindings in the JSON payload. Refer to Update a workspace for additional information.

You can also bind key-value tags when creating a workspace. Refer to Create a workspace for additional information.

Refer to Define project tags for information about supported tag values.

Parameter	Description
`:workspace_id`	The workspace ID to add tags to. Obtain this from the workspace settings or the Show Workspace endpoint.

Status	Response	Reason(s)
204	No Content	Successfully added tags to workspace
404	JSON API error object	Workspace not found, or user unauthorized to perform action

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

It is important to note that type, as well as one of id or attributes.name is required.

Key path	Type	Description
`data[].type`	string	Must be `"tags"`.
`data[].id`	string	The ID of the tag to add.
`data[].attributes.name`	string	The name of the tag to add.

Sample Payload

{  "data": [    {      "type": "tags",      "attributes": {        "name": "foo"      }    },    {      "type": "tags",      "attributes": {        "name": "bar"      }    }  ]}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/workspace-2/relationships/tags

Sample Response

No response body.

Status code 204.

Remove tags from workspace

This endpoint removes one or more tags from a workspace. The workspace must already exist, and tag element that supplies an id attribute must exist. If the name attribute is used, and no matching organization tag is found, no action will occur for that entry. Tags removed from all workspaces will be removed from the organization-wide list.

To remove key-value tags to an existing workspace, call the PATCH /workspaces/:workspace_id and provide workspace tag bindings in the JSON payload. Refer to Update a workspace for additional information.

DELETE /workspaces/:workspace_id/relationships/tags

Parameter	Description
`:workspace_id`	The workspace ID to remove tags from. Obtain this from the workspace settings or the Show Workspace endpoint.

Status	Response	Reason(s)
204	No Content	Successfully removed tags to workspace
404	JSON API error object	Workspace not found, or user unauthorized to perform action

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

It is important to note that type, as well as one of id or attributes.name is required.

Key path	Type	Description
`data[].type`	string	Must be `"tags"`.
`data[].id`	string	The ID of the tag to remove.
`data[].attributes.name`	string	The name of the tag to remove.

Sample Payload

{  "data": [    {      "type": "tags",      "id": "tag-Yfha4YpPievQ8wJw"    }  ]}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request DELETE \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/workspace-2/relationships/tags

Sample Response

No response body.

Status code 204.

Add/update tag-bindings on a workspace

This endpoint adds keys and values or updates values of tag-bindings on an existing resource by key. It does not remove any keys from the collection. This endpoint is useful when you want to ensure a modification is additive.

Tag Bindings have special constraints:

Up to 10 tags can be applied to a workspace, but an additional 10 tags may be inherited from its project.
Keys must be no more than 128 characters, allowing all alphanumeric characters plus the symbols _, ., =, +, -, @, :.
Values allow the same characters, but can be up to 256 characters.
Certain key prefixes, including hc: and hcp: are not allowed.

PATCH /workspaces/:workspace_id/tag-bindings

Parameter	Description
`:workspace_id`	The ID of the workspace to update

Request Body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

It is important to note that for each data item, type, as well as attributes.key is required.

Key path	Type	Description
`data[].type`	string	Must be `"tag-bindings"`.
`data[].attributes.key`	string	The key of the tag to add/update.
`data[].attributes.value`	string	The name of the tag to add/update.

Sample Payload

{  "data": [    {      "type": "tag-bindings",      "attributes": {        "key": "costcenter",        "value": "123"      }    },    {      "type": "tag-bindings",      "attributes": {        "key": "bar",        "value": "baz"      }    }  ]}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request PATCH \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-82d2281aa259ba09/tag-bindings

Sample Response

Status Code 200

{  "data": [    {      "id": "tb-e4a5847b2cf06559",      "type": "tag-bindings",      "attributes": {        "key": "costcenter",        "value": "123"      }    },    {      "id": "tb-97ce954636f93a6c",      "type": "tag-bindings",      "attributes": {        "key": "bar",        "value": "baz"      }    }  ]}

Show data retention policy

This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform.

GET /workspaces/:workspace_id/relationships/data-retention-policy

Parameter	Description
`:workspace_id`	The ID of the workspace to show the data retention policy for. Obtain this from the workspace settings or by sending a `GET` request to the `/workspaces` endpoint.

This endpoint shows the data retention policy set explicitly on the workspace. When no data retention policy is set for the workspace, the endpoint returns the default policy configured for the organization. Refer to Data Retention Policies for instructions on configuring data retention policies for workspaces.

Refer to Data Retention Policy API in the Terraform Enterprise documentation for details.

Create or update data retention policy

This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform.

POST /workspaces/:workspace_id/relationships/data-retention-policy

Parameter	Description
`:workspace_id`	The workspace ID to update the data retention policy for. Obtain this from the workspace settings or by sending a `GET` request to the `/workspaces` endpoint.

This endpoint creates a data retention policy for a workspace or updates the existing policy. Refer to Data Retention Policies for additional information.

Refer to Data Retention Policy API in the Terraform Enterprise documentation for details.

Remove data retention policy

This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform.

DELETE /workspaces/:workspace_id/relationships/data-retention-policy

Parameter	Description
`:workspace_id`	The workspace ID to remove the data retenetion policy for. Obtain this from the workspace settings or by sending a `GET` request to the `/workspaces` endpoint.

This endpoint removes the data retention policy explicitly set on a workspace. When no data retention policy is set for the workspace, the endpoint returns the default policy configured for the organization. Refer to Data Retention Policies for instructions on configuring data retention policies for organizations.

Read more about workspace data retention policies.

Refer to Data Retention Policy API in the Terraform Enterprise documentation for details.

The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:

current_configuration_version - The last configuration this workspace received, excluding plan-only configurations. Terraform uses this configuration for new runs, unless you provide a different one.
current_configuration_version.ingress_attributes - The commit information for the current configuration version.
current_run - Additional information about the current run.
current_run.configuration_version - The configuration used in the current run.
current_run.configuration_version.ingress_attributes - The commit information used in the current run.
current_run.plan - The plan used in the current run.
locked_by - The user, team, or run responsible for locking the workspace, if the workspace is currently locked.
organization - The full organization record.
outputs - The outputs for the most recently applied run.
project - The full project record.
readme - The most recent workspace README.md.