Terraform

App · 20 actions

Run HCP Terraform from your workflows: create and configure workspaces, set their variables, upload Terraform configuration, start plans and apply, discard or cancel runs, and read the outputs your infrastructure produces.

Actions

ActionWhat it does
Apply runConfirm a run that is waiting for confirmation, so its plan is applied.
Cancel runInterrupt a run that is planning or applying, like pressing Ctrl+C. A run that is pending or waiting for confirmation is stopped with Discard run instead.
Create runStart a run in a workspace: a plan, then an apply once confirmed (or straight away with auto apply).
Create variableAdd a Terraform variable or an environment variable to a workspace.
Create workspaceCreate a workspace that is run from Lodol: upload its configuration with Upload configuration, then start runs with Create run.
Delete variableRemove a variable from a workspace.
Delete workspaceDelete a workspace.
Discard runDiscard a run that is pending or waiting for confirmation, so it is never applied.
Get outputsGet the outputs of a workspace's latest state, such as an IP address or a URL the configuration produced.
Get runGet a run's status and what its plan and apply add, change and destroy.
Get workspaceGet a workspace's settings, lock state, resource count and current run, by its id, its name or its link.
List organizationsList the HCP Terraform organizations the token's user belongs to, with each one's plan.
List runsList a workspace's runs, newest first.
List variablesList a workspace's Terraform and environment variables.
List workspacesList an organization's workspaces, optionally searched by name or filtered by project, tag or the status of their current run.
Lock workspaceLock a workspace so no new run can start in it until it is unlocked.
Unlock workspaceUnlock a workspace.
Update variableChange a workspace variable's key, value, description or category.
Update workspaceChange a workspace's settings.
Upload configurationUpload Terraform files to a workspace and wait until HCP Terraform has read them, so the next Create run uses them.

Apply run

Confirm a run that is waiting for confirmation, so its plan is applied. The apply is queued; use Get run to see it finish.

Inputs

Runrun_idtextRequired
The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.
Commentcommenttext
A note shown on the run in HCP Terraform.

Outputs

queuedtrue/false
True once HCP Terraform accepted the request
run_idtext
Id of the run
Example output
{
  "queued": true,
  "run_id": "run-CZcmD7eagjhyX0vN"
}

Cancel run

Interrupt a run that is planning or applying, like pressing Ctrl+C. A run that is pending or waiting for confirmation is stopped with Discard run instead.

Inputs

Runrun_idtextRequired
The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.
Commentcommenttext
A note shown on the run in HCP Terraform.

Outputs

queuedtrue/false
True once HCP Terraform accepted the request
run_idtext
Id of the run
Example output
{
  "queued": true,
  "run_id": "run-CZcmD7eagjhyX0vN"
}

Create run

Start a run in a workspace: a plan, then an apply once confirmed (or straight away with auto apply). Use Get run to follow it. A free organization runs one at a time, so others wait their turn.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
Messagemessagetext
A note shown on the run in HCP Terraform.
Configuration versionconfiguration_version_idtext
The configuration to run (cv-...), from Upload configuration. Empty uses the workspace's latest.
Destroyis_destroytrue/false
Plan to destroy every resource the workspace manages.Default: false.
Refresh onlyrefresh_onlytrue/false
Only update the state to match real infrastructure. Can't be combined with Destroy.Default: false.
Plan onlyplan_onlytrue/false
Plan without ever applying.Default: false.
Auto applyauto_applytext
Apply this run without confirmation (On) or wait for it (Off). Empty follows the workspace's setting.One of: true (On), false (Off).
Target resourcestarget_addrslist
Limit the run to these resource addresses, such as aws_instance.web, one per line or separated by commas.
Replace resourcesreplace_addrslist
Resource addresses to destroy and create again, one per line or separated by commas.
Variablesvariablesobject
Values for this run only, each a Terraform variable name and a value. Text is quoted for you; write a list or map as HCL, such as ["a", "b"].

Outputs

applyobject
The run's apply
auto_applytrue/false
Whether it applies without confirmation
configuration_version_idtext
Id of the configuration it runs (cv-...)
created_attext
When it was created (ISO 8601)
has_changestrue/false
Whether its plan has changes
idtext
Run id (run-...)
is_cancelabletrue/false
True when Cancel run will work
is_confirmabletrue/false
True when it is waiting for confirmation, so Apply run will work
is_destroytrue/false
Whether it destroys every resource
is_discardabletrue/false
True when Discard run will work
is_finaltrue/false
True once the run has stopped and won't move on by itself, such as applied, discarded, errored or canceled
messagetext
The run's message
planobject
The run's plan
plan_onlytrue/false
Whether it only plans
refresh_onlytrue/false
Whether it only refreshes state
replace_addrslist
Resources it replaces
sourcetext
Where it was started, such as tfe-api or tfe-ui
statustext
Run status, such as planning, planned, applied or errored
status_timestampsobject
When the run reached each status, keyed like planned_at or applied_at
target_addrslist
Resources it is limited to
trigger_reasontext
Why it was started
workspace_idtext
Id of its workspace (ws-...)
Example output
{
  "apply": {
    "id": "apply-ywLgq6wmfgPBE4QQ",
    "resource_additions": null,
    "resource_changes": null,
    "resource_destructions": null,
    "resource_imports": null,
    "status": null
  },
  "auto_apply": false,
  "configuration_version_id": "cv-ntv3HbhJqvFzamy7",
  "created_at": "2026-10-20T08:00:00.000Z",
  "has_changes": false,
  "id": "run-CZcmD7eagjhyX0vN",
  "is_cancelable": false,
  "is_confirmable": false,
  "is_destroy": false,
  "is_discardable": true,
  "is_final": false,
  "message": "Queued from Lodol",
  "plan": {
    "id": "plan-6JmHBoKKeBDvnQyW",
    "resource_additions": null,
    "resource_changes": null,
    "resource_destructions": null,
    "resource_imports": null,
    "status": null
  },
  "plan_only": false,
  "refresh_only": false,
  "replace_addrs": null,
  "source": "tfe-api",
  "status": "pending",
  "status_timestamps": {
    "plan_queueable_at": "2026-10-20T08:00:01+00:00"
  },
  "target_addrs": null,
  "trigger_reason": "manual",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}

Create variable

Add a Terraform variable or an environment variable to a workspace. Every later run uses it.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
KeykeytextRequired
The variable's name, such as region or AWS_REGION. One per category in a workspace.
CategorycategorytextRequired
A Terraform variable fills a variable block in the configuration; an environment variable is set in the run's shell.One of: terraform (Terraform variable), env (Environment variable).
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
Valuevaluetext
The value. Empty sets an empty value.
Descriptiondescriptiontext
A description shown in HCP Terraform.
HCLhcltrue/false
Read the value as HCL code, such as a list or map. Has no effect on environment variables.Default: false.
Sensitivesensitivetrue/false
Hide the value: it is written once and can't be read back.Default: false.

Outputs

categorytext
terraform or env
descriptiontext
Description
hcltrue/false
Whether the value is read as HCL
idtext
Variable id (var-...)
keytext
Variable name
sensitivetrue/false
Whether the value is hidden
valuetext
Its value; empty for a sensitive variable
version_idtext
Id of this version of the variable
workspace_idtext
Id of its workspace (ws-...)
Example output
{
  "category": "terraform",
  "description": "Where to deploy",
  "hcl": false,
  "id": "var-EavQ1LztoRTQHSNT",
  "key": "region",
  "sensitive": false,
  "value": "us-east-1",
  "version_id": "1aa07d63ea8ff4df941c94ca9ac39a0d2f6e5f9d",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}

Create workspace

Create a workspace that is run from Lodol: upload its configuration with Upload configuration, then start runs with Create run.

Inputs

OrganizationorganizationtextRequired
The HCP Terraform organization. Pick one, or type its name.
NamenametextRequired
The workspace name: letters, numbers, - and _, unique in the organization.
Descriptiondescriptiontext
A description of the workspace.
Projectproject_idtext
The project to put it in. Empty means the organization's default project.
Execution modeexecution_modetext
Where Terraform runs. Leave empty for the organization's default.One of: remote (Remote (HCP Terraform runs Terraform)), local (Local (HCP Terraform only stores state)).
Auto applyauto_applytrue/false
Apply a successful plan without waiting for confirmation.Default: false.
Terraform versionterraform_versiontext
An exact version such as 1.9.8, or a constraint such as ~> 1.9.0. A new workspace gets the latest version when this is empty.
Working directoryworking_directorytext
The folder Terraform runs in, relative to the root of the uploaded configuration. Empty means the root.
Tagstagsobject
Up to 10 tags, each a key and a value, such as env = prod.

Outputs

auto_applytrue/false
Whether a successful plan is applied without confirmation
created_attext
When it was created (ISO 8601)
current_run_idtext
Id of its current run (run-...)
descriptiontext
Description
execution_modetext
Where Terraform runs: remote, local or agent
idtext
Workspace id (ws-...)
latest_change_attext
When its state or configuration last changed (ISO 8601)
lockedtrue/false
Whether the workspace is locked
locked_reasontext
Why it was locked
nametext
Workspace name
organizationtext
Organization name
project_idtext
Id of the project it is in (prj-...)
resource_countnumber
How many resources its state manages
terraform_versiontext
Terraform version it runs
updated_attext
When it was last changed (ISO 8601)
urltext
Link to the workspace in HCP Terraform
working_directorytext
Directory Terraform runs in, relative to the configuration root
Example output
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": false,
  "locked_reason": "",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}

Delete variable

Remove a variable from a workspace.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Variablevariable_idtextRequired
The variable. Pick one of the workspace's, or give its id (var-...).
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.

Outputs

deletedtrue/false
True once the variable is deleted
variable_idtext
Id of the deleted variable
workspace_idtext
Id of its workspace (ws-...)
Example output
{
  "deleted": true,
  "variable_id": "var-EavQ1LztoRTQHSNT",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}

Delete workspace

Delete a workspace. By default it is only deleted when it manages no resources; Force delete removes it anyway, leaving its infrastructure in place but no longer tracked.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
Force deleteforcetrue/false
Delete it even if it still manages resources. Those resources are not destroyed. Only organization owners can force delete.Default: false.

Outputs

deletedtrue/false
True once the workspace is deleted
forcedtrue/false
Whether it was force deleted
workspace_idtext
Id of the deleted workspace
Example output
{
  "deleted": true,
  "forced": false,
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}

Discard run

Discard a run that is pending or waiting for confirmation, so it is never applied. A run that is planning or applying is stopped with Cancel run instead.

Inputs

Runrun_idtextRequired
The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.
Commentcommenttext
A note shown on the run in HCP Terraform.

Outputs

queuedtrue/false
True once HCP Terraform accepted the request
run_idtext
Id of the run
Example output
{
  "queued": true,
  "run_id": "run-CZcmD7eagjhyX0vN"
}

Get outputs

Get the outputs of a workspace's latest state, such as an IP address or a URL the configuration produced. Sensitive outputs come back null.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.

Outputs

countnumber
How many outputs there are
itemslist
Each output with its type
outputsobject
Each output's value by its name, so @step.outputs.vpc_id reads the vpc_id output
workspace_idtext
Id of the workspace (ws-...)
Example output
{
  "count": 2,
  "items": [
    {
      "id": "wsout-xFAmCR3VkBGepcee",
      "name": "vpc_id",
      "sensitive": false,
      "type": "string",
      "value": "vpc-0a1b2c3d4e5f67890"
    },
    {
      "id": "wsout-tY7ZpQ9wNcA6kLmB",
      "name": "db_password",
      "sensitive": true,
      "type": "string",
      "value": null
    }
  ],
  "outputs": {
    "db_password": null,
    "vpc_id": "vpc-0a1b2c3d4e5f67890"
  },
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}

Get run

Get a run's status and what its plan and apply add, change and destroy. Repeat it to wait for a run to finish.

Inputs

Runrun_idtextRequired
The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.

Outputs

applyobject
The run's apply
auto_applytrue/false
Whether it applies without confirmation
configuration_version_idtext
Id of the configuration it runs (cv-...)
created_attext
When it was created (ISO 8601)
has_changestrue/false
Whether its plan has changes
idtext
Run id (run-...)
is_cancelabletrue/false
True when Cancel run will work
is_confirmabletrue/false
True when it is waiting for confirmation, so Apply run will work
is_destroytrue/false
Whether it destroys every resource
is_discardabletrue/false
True when Discard run will work
is_finaltrue/false
True once the run has stopped and won't move on by itself, such as applied, discarded, errored or canceled
messagetext
The run's message
planobject
The run's plan
plan_onlytrue/false
Whether it only plans
refresh_onlytrue/false
Whether it only refreshes state
replace_addrslist
Resources it replaces
sourcetext
Where it was started, such as tfe-api or tfe-ui
statustext
Run status, such as planning, planned, applied or errored
status_timestampsobject
When the run reached each status, keyed like planned_at or applied_at
target_addrslist
Resources it is limited to
trigger_reasontext
Why it was started
workspace_idtext
Id of its workspace (ws-...)
Example output
{
  "apply": {
    "id": "apply-ywLgq6wmfgPBE4QQ",
    "resource_additions": 0,
    "resource_changes": 0,
    "resource_destructions": 0,
    "resource_imports": 0,
    "status": "unreachable"
  },
  "auto_apply": false,
  "configuration_version_id": "cv-ntv3HbhJqvFzamy7",
  "created_at": "2026-10-20T08:00:00.000Z",
  "has_changes": true,
  "id": "run-CZcmD7eagjhyX0vN",
  "is_cancelable": false,
  "is_confirmable": true,
  "is_destroy": false,
  "is_discardable": true,
  "is_final": false,
  "message": "Queued from Lodol",
  "plan": {
    "id": "plan-6JmHBoKKeBDvnQyW",
    "resource_additions": 1,
    "resource_changes": 0,
    "resource_destructions": 0,
    "resource_imports": 0,
    "status": "finished"
  },
  "plan_only": false,
  "refresh_only": false,
  "replace_addrs": null,
  "source": "tfe-api",
  "status": "planned",
  "status_timestamps": {
    "plan_queueable_at": "2026-10-20T08:00:01+00:00",
    "planned_at": "2026-10-20T08:00:30+00:00"
  },
  "target_addrs": null,
  "trigger_reason": "manual",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}

Get workspace

Get a workspace's settings, lock state, resource count and current run, by its id, its name or its link.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.

Outputs

auto_applytrue/false
Whether a successful plan is applied without confirmation
created_attext
When it was created (ISO 8601)
current_run_idtext
Id of its current run (run-...)
descriptiontext
Description
execution_modetext
Where Terraform runs: remote, local or agent
idtext
Workspace id (ws-...)
latest_change_attext
When its state or configuration last changed (ISO 8601)
lockedtrue/false
Whether the workspace is locked
locked_reasontext
Why it was locked
nametext
Workspace name
organizationtext
Organization name
project_idtext
Id of the project it is in (prj-...)
resource_countnumber
How many resources its state manages
terraform_versiontext
Terraform version it runs
updated_attext
When it was last changed (ISO 8601)
urltext
Link to the workspace in HCP Terraform
working_directorytext
Directory Terraform runs in, relative to the configuration root
Example output
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": false,
  "locked_reason": "",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}

List organizations

List the HCP Terraform organizations the token's user belongs to, with each one's plan.

Inputs

Searchsearchtext
Only organizations whose name or email contains this.
Pagepagenumber
Which page of results to return, starting at 1.At least 1.
Page sizepage_sizenumber
How many to return per page, up to 100. The default is 20.From 1 to 100.

Outputs

countnumber
How many records are on this page
has_moretrue/false
True when there are more pages
next_pagenumber
The next page number, when there is one
organizationslist
The organizations
pagenumber
The page number
total_countnumber
How many records match in all
Example output
{
  "count": 1,
  "has_more": false,
  "next_page": null,
  "organizations": [
    {
      "can_create_workspace": true,
      "created_at": "2026-01-12T09:00:00.000Z",
      "default_execution_mode": "remote",
      "email": "platform@example.com",
      "name": "my-company",
      "plan_identifier": "free"
    }
  ],
  "page": 1,
  "total_count": 1
}

List runs

List a workspace's runs, newest first. Plan only runs are left out unless chosen under Operations. HCP Terraform allows this 30 times a minute, so follow one run with Get run instead.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
Statusesstatuseslist
Only runs with one of these statuses.One or more of: pending, fetching, fetching_completed (Fetching completed), pre_plan_running (Pre plan running), pre_plan_completed (Pre plan completed), queuing, plan_queued (Plan queued), planning, planned, cost_estimating (Cost estimating), and 17 more.
Operationsoperationslist
Only runs of these kinds.One or more of: plan_only (Plan only), plan_and_apply (Plan and apply), save_plan (Saved plan), refresh_only (Refresh only), destroy, empty_apply (Empty apply), action_only (Action only).
Status groupstatus_grouptext
Only runs in progress, finished, or able to be discarded.One of: non_final (Still in progress), final (Finished), discardable (Can be discarded).
Sourcesourcetext
Only runs started this way.One of: tfe-ui (HCP Terraform website), tfe-api (API (including Lodol)), tfe-configuration-version (Configuration upload).
Pagepagenumber
Which page of results to return, starting at 1.At least 1.
Page sizepage_sizenumber
How many to return per page, up to 100. The default is 20.From 1 to 100.

Outputs

countnumber
How many records are on this page
has_moretrue/false
True when there are more pages
next_pagenumber
The next page number, when there is one
pagenumber
The page number
runslist
The runs, newest first
total_countnumber
How many records match in all
Example output
{
  "count": 1,
  "has_more": false,
  "next_page": null,
  "page": 1,
  "runs": [
    {
      "apply": {
        "id": "apply-ywLgq6wmfgPBE4QQ",
        "resource_additions": null,
        "resource_changes": null,
        "resource_destructions": null,
        "resource_imports": null,
        "status": null
      },
      "auto_apply": false,
      "configuration_version_id": "cv-ntv3HbhJqvFzamy7",
      "created_at": "2026-10-20T08:00:00.000Z",
      "has_changes": true,
      "id": "run-CZcmD7eagjhyX0vN",
      "is_cancelable": false,
      "is_confirmable": true,
      "is_destroy": false,
      "is_discardable": true,
      "is_final": false,
      "message": "Queued from Lodol",
      "plan": {
        "id": "plan-6JmHBoKKeBDvnQyW",
        "resource_additions": null,
        "resource_changes": null,
        "resource_destructions": null,
        "resource_imports": null,
        "status": null
      },
      "plan_only": false,
      "refresh_only": false,
      "replace_addrs": null,
      "source": "tfe-api",
      "status": "planned",
      "status_timestamps": {
        "plan_queueable_at": "2026-10-20T08:00:01+00:00",
        "planned_at": "2026-10-20T08:00:30+00:00"
      },
      "target_addrs": null,
      "trigger_reason": "manual",
      "workspace_id": "ws-SihZTyXKfNXUWuUa"
    }
  ],
  "total_count": 1
}

List variables

List a workspace's Terraform and environment variables. Sensitive values come back empty.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
Categorycategorytext
Only Terraform variables, or only environment variables.One of: terraform (Terraform variable), env (Environment variable).

Outputs

countnumber
How many variables there are
variableslist
The variables
workspace_idtext
Id of the workspace (ws-...)
Example output
{
  "count": 2,
  "variables": [
    {
      "category": "terraform",
      "description": "Where to deploy",
      "hcl": false,
      "id": "var-EavQ1LztoRTQHSNT",
      "key": "region",
      "sensitive": false,
      "value": "us-east-1",
      "version_id": "1aa07d63ea8ff4df941c94ca9ac39a0d2f6e5f9d",
      "workspace_id": "ws-SihZTyXKfNXUWuUa"
    },
    {
      "category": "env",
      "description": null,
      "hcl": false,
      "id": "var-ffbP3LrZ9yPvdUXD",
      "key": "AWS_SECRET_ACCESS_KEY",
      "sensitive": true,
      "value": null,
      "version_id": "1aa07d63ea8ff4df941c94ca9ac39a0d2f6e5f9d",
      "workspace_id": "ws-SihZTyXKfNXUWuUa"
    }
  ],
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}

List workspaces

List an organization's workspaces, optionally searched by name or filtered by project, tag or the status of their current run.

Inputs

OrganizationorganizationtextRequired
The HCP Terraform organization. Pick one, or type its name.
Searchsearchtext
Part of a workspace name. Use * as a wildcard, as in prod-* or *-network.
Projectproject_idtext
Only workspaces in this project.
Current run statuscurrent_run_statustext
Only workspaces whose current run has this status.One of: pending, fetching, fetching_completed (Fetching completed), pre_plan_running (Pre plan running), pre_plan_completed (Pre plan completed), queuing, plan_queued (Plan queued), planning, planned, cost_estimating (Cost estimating), and 17 more.
Tag keytag_keytext
Only workspaces with a tag of this key.
Tag valuetag_valuetext
With Tag key: only that tag with this value.
Sort bysorttext
The order to list them in. The default is by name.One of: name (Name, A to Z), -name (Name, Z to A), -latest-change-at (Most recently changed first), latest-change-at (Least recently changed first), -current-run.created-at (Newest current run first), current-run.created-at (Oldest current run first).
Pagepagenumber
Which page of results to return, starting at 1.At least 1.
Page sizepage_sizenumber
How many to return per page, up to 100. The default is 20.From 1 to 100.

Outputs

countnumber
How many records are on this page
has_moretrue/false
True when there are more pages
next_pagenumber
The next page number, when there is one
pagenumber
The page number
total_countnumber
How many records match in all
workspaceslist
The workspaces
Example output
{
  "count": 1,
  "has_more": false,
  "next_page": null,
  "page": 1,
  "total_count": 1,
  "workspaces": [
    {
      "auto_apply": false,
      "created_at": "2026-09-01T10:15:00.000Z",
      "current_run_id": "run-CZcmD7eagjhyX0vN",
      "description": "VPC and subnets for production",
      "execution_mode": "remote",
      "id": "ws-SihZTyXKfNXUWuUa",
      "latest_change_at": "2026-10-20T08:00:00.000Z",
      "locked": false,
      "locked_reason": "",
      "name": "networking-prod",
      "organization": "my-company",
      "project_id": "prj-jT92VLSFpv8FwKtc",
      "resource_count": 12,
      "terraform_version": "1.9.8",
      "updated_at": "2026-10-20T08:00:00.000Z",
      "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
      "working_directory": ""
    }
  ]
}

Lock workspace

Lock a workspace so no new run can start in it until it is unlocked.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
Reasonreasontext
Why it is locked, shown in HCP Terraform.

Outputs

auto_applytrue/false
Whether a successful plan is applied without confirmation
created_attext
When it was created (ISO 8601)
current_run_idtext
Id of its current run (run-...)
descriptiontext
Description
execution_modetext
Where Terraform runs: remote, local or agent
idtext
Workspace id (ws-...)
latest_change_attext
When its state or configuration last changed (ISO 8601)
lockedtrue/false
Whether the workspace is locked
locked_reasontext
Why it was locked
nametext
Workspace name
organizationtext
Organization name
project_idtext
Id of the project it is in (prj-...)
resource_countnumber
How many resources its state manages
terraform_versiontext
Terraform version it runs
updated_attext
When it was last changed (ISO 8601)
urltext
Link to the workspace in HCP Terraform
working_directorytext
Directory Terraform runs in, relative to the configuration root
Example output
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": true,
  "locked_reason": "Maintenance window",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}

Unlock workspace

Unlock a workspace. Force unlock releases a lock held by another user or a run.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
Force unlockforcetrue/false
Release a lock someone else or a run holds. Needs admin access to the workspace.Default: false.

Outputs

auto_applytrue/false
Whether a successful plan is applied without confirmation
created_attext
When it was created (ISO 8601)
current_run_idtext
Id of its current run (run-...)
descriptiontext
Description
execution_modetext
Where Terraform runs: remote, local or agent
idtext
Workspace id (ws-...)
latest_change_attext
When its state or configuration last changed (ISO 8601)
lockedtrue/false
Whether the workspace is locked
locked_reasontext
Why it was locked
nametext
Workspace name
organizationtext
Organization name
project_idtext
Id of the project it is in (prj-...)
resource_countnumber
How many resources its state manages
terraform_versiontext
Terraform version it runs
updated_attext
When it was last changed (ISO 8601)
urltext
Link to the workspace in HCP Terraform
working_directorytext
Directory Terraform runs in, relative to the configuration root
Example output
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": false,
  "locked_reason": "",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}

Update variable

Change a workspace variable's key, value, description or category. Only the fields filled in change.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Variablevariable_idtextRequired
The variable. Pick one of the workspace's, or give its id (var-...).
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
New keykeytext
A new name for the variable.
Valuevaluetext
A new value. Empty keeps the current one.
Descriptiondescriptiontext
A new description.
Categorycategorytext
Move it to the other category.One of: terraform (Terraform variable), env (Environment variable).
HCLhcltext
Read the value as HCL code (On) or as text (Off). Empty keeps the current setting.One of: true (On), false (Off).
Make sensitivesensitivetrue/false
Hide the value from now on. A sensitive variable stays sensitive, so leaving this off keeps its current setting.Default: false.

Outputs

categorytext
terraform or env
descriptiontext
Description
hcltrue/false
Whether the value is read as HCL
idtext
Variable id (var-...)
keytext
Variable name
sensitivetrue/false
Whether the value is hidden
valuetext
Its value; empty for a sensitive variable
version_idtext
Id of this version of the variable
workspace_idtext
Id of its workspace (ws-...)
Example output
{
  "category": "terraform",
  "description": "Where to deploy",
  "hcl": false,
  "id": "var-EavQ1LztoRTQHSNT",
  "key": "region",
  "sensitive": false,
  "value": "us-east-1",
  "version_id": "1aa07d63ea8ff4df941c94ca9ac39a0d2f6e5f9d",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}

Update workspace

Change a workspace's settings. Only the fields filled in change. Renaming a workspace changes its link.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
New namenametext
A new name: letters, numbers, - and _.
Descriptiondescriptiontext
A description of the workspace.
Execution modeexecution_modetext
Where Terraform runs. Leave empty for the organization's default.One of: remote (Remote (HCP Terraform runs Terraform)), local (Local (HCP Terraform only stores state)).
Auto applyauto_applytext
Turn applying without confirmation on or off. Empty keeps the current setting.One of: true (On), false (Off).
Terraform versionterraform_versiontext
An exact version such as 1.9.8, or a constraint such as ~> 1.9.0. A new workspace gets the latest version when this is empty.
Working directoryworking_directorytext
The folder Terraform runs in, relative to the root of the uploaded configuration. Empty means the root.
Move to projectproject_idtext
Move the workspace to this project. Needs admin access to both projects.

Outputs

auto_applytrue/false
Whether a successful plan is applied without confirmation
created_attext
When it was created (ISO 8601)
current_run_idtext
Id of its current run (run-...)
descriptiontext
Description
execution_modetext
Where Terraform runs: remote, local or agent
idtext
Workspace id (ws-...)
latest_change_attext
When its state or configuration last changed (ISO 8601)
lockedtrue/false
Whether the workspace is locked
locked_reasontext
Why it was locked
nametext
Workspace name
organizationtext
Organization name
project_idtext
Id of the project it is in (prj-...)
resource_countnumber
How many resources its state manages
terraform_versiontext
Terraform version it runs
updated_attext
When it was last changed (ISO 8601)
urltext
Link to the workspace in HCP Terraform
working_directorytext
Directory Terraform runs in, relative to the configuration root
Example output
{
  "auto_apply": false,
  "created_at": "2026-09-01T10:15:00.000Z",
  "current_run_id": "run-CZcmD7eagjhyX0vN",
  "description": "VPC and subnets for production",
  "execution_mode": "remote",
  "id": "ws-SihZTyXKfNXUWuUa",
  "latest_change_at": "2026-10-20T08:00:00.000Z",
  "locked": false,
  "locked_reason": "",
  "name": "networking-prod",
  "organization": "my-company",
  "project_id": "prj-jT92VLSFpv8FwKtc",
  "resource_count": 12,
  "terraform_version": "1.9.8",
  "updated_at": "2026-10-20T08:00:00.000Z",
  "url": "https://app.terraform.io/app/my-company/workspaces/networking-prod",
  "working_directory": ""
}

Upload configuration

Upload Terraform files to a workspace and wait until HCP Terraform has read them, so the next Create run uses them.

Inputs

WorkspaceworkspacetextRequired
The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
ConfigurationconfigurationtextRequired
The Terraform code, uploaded as main.tf.
Organizationorganizationtext
The workspace's organization. Needed to pick the workspace from a list or to give it by name, not when the workspace is given by id.
Additional filesadditional_filesobject
More files, each a file name and its content, such as variables.tf. Use a path like modules/net/main.tf for a file in a folder.
Queue a runauto_queue_runstrue/false
Start a run as soon as the upload is ready. Leave off to start one with a Create run step.Default: false.
Speculativespeculativetrue/false
Use the upload only for plans that can't be applied, and don't make it the workspace's current configuration.Default: false.

Outputs

auto_queue_runstrue/false
Whether a run was queued with it
configuration_version_idtext
Id of the new configuration version (cv-...)
fileslist
The files that were uploaded
speculativetrue/false
Whether it is for plans only
statustext
Its status, uploaded once it is ready
workspace_idtext
Id of the workspace (ws-...)
Example output
{
  "auto_queue_runs": false,
  "configuration_version_id": "cv-ntv3HbhJqvFzamy7",
  "files": [
    "main.tf",
    "variables.tf"
  ],
  "speculative": false,
  "status": "uploaded",
  "workspace_id": "ws-SihZTyXKfNXUWuUa"
}

On this page