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
| Action | What it does |
|---|---|
| Apply run | Confirm a run that is waiting for confirmation, so its plan is applied. |
| 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. |
| Create run | Start a run in a workspace: a plan, then an apply once confirmed (or straight away with auto apply). |
| Create variable | Add a Terraform variable or an environment variable to a workspace. |
| Create workspace | Create a workspace that is run from Lodol: upload its configuration with Upload configuration, then start runs with Create run. |
| Delete variable | Remove a variable from a workspace. |
| Delete workspace | Delete a workspace. |
| Discard run | Discard a run that is pending or waiting for confirmation, so it is never applied. |
| Get outputs | Get the outputs of a workspace's latest state, such as an IP address or a URL the configuration produced. |
| Get run | Get a run's status and what its plan and apply add, change and destroy. |
| Get workspace | Get a workspace's settings, lock state, resource count and current run, by its id, its name or its link. |
| List organizations | List the HCP Terraform organizations the token's user belongs to, with each one's plan. |
| List runs | List a workspace's runs, newest first. |
| List variables | List a workspace's Terraform and environment variables. |
| List workspaces | List an organization's workspaces, optionally searched by name or filtered by project, tag or the status of their current run. |
| Lock workspace | Lock a workspace so no new run can start in it until it is unlocked. |
| Unlock workspace | Unlock a workspace. |
| Update variable | Change a workspace variable's key, value, description or category. |
| Update workspace | Change a workspace's settings. |
| Upload configuration | Upload 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
- Run
run_idtextRequired - The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.
- Comment
commenttext - 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
- Run
run_idtextRequired - The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.
- Comment
commenttext - 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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization
organizationtext - 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.
- Message
messagetext - A note shown on the run in HCP Terraform.
- Configuration version
configuration_version_idtext - The configuration to run (cv-...), from Upload configuration. Empty uses the workspace's latest.
- Destroy
is_destroytrue/false - Plan to destroy every resource the workspace manages.Default:
false. - Refresh only
refresh_onlytrue/false - Only update the state to match real infrastructure. Can't be combined with Destroy.Default:
false. - Plan only
plan_onlytrue/false - Plan without ever applying.Default:
false. - Auto apply
auto_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 resources
target_addrslist - Limit the run to these resource addresses, such as aws_instance.web, one per line or separated by commas.
- Replace resources
replace_addrslist - Resource addresses to destroy and create again, one per line or separated by commas.
- Variables
variablesobject - 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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Key
keytextRequired - The variable's name, such as region or AWS_REGION. One per category in a workspace.
- Category
categorytextRequired - 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). - Organization
organizationtext - 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.
- Value
valuetext - The value. Empty sets an empty value.
- Description
descriptiontext - A description shown in HCP Terraform.
- HCL
hcltrue/false - Read the value as HCL code, such as a list or map. Has no effect on environment variables.Default:
false. - Sensitive
sensitivetrue/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
- Organization
organizationtextRequired - The HCP Terraform organization. Pick one, or type its name.
- Name
nametextRequired - The workspace name: letters, numbers, - and _, unique in the organization.
- Description
descriptiontext - A description of the workspace.
- Project
project_idtext - The project to put it in. Empty means the organization's default project.
- Execution mode
execution_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 apply
auto_applytrue/false - Apply a successful plan without waiting for confirmation.Default:
false. - Terraform version
terraform_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 directory
working_directorytext - The folder Terraform runs in, relative to the root of the uploaded configuration. Empty means the root.
- Tags
tagsobject - 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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Variable
variable_idtextRequired - The variable. Pick one of the workspace's, or give its id (var-...).
- Organization
organizationtext - 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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization
organizationtext - 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 delete
forcetrue/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
- Run
run_idtextRequired - The run's id (run-...), or its link from HCP Terraform. Create run and List runs give it.
- Comment
commenttext - 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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization
organizationtext - 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
- Run
run_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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization
organizationtext - 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
- Search
searchtext - Only organizations whose name or email contains this.
- Page
pagenumber - Which page of results to return, starting at 1.At least 1.
- Page size
page_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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization
organizationtext - 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.
- Statuses
statuseslist - 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. - Operations
operationslist - 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 group
status_grouptext - Only runs in progress, finished, or able to be discarded.One of:
non_final(Still in progress),final(Finished),discardable(Can be discarded). - Source
sourcetext - Only runs started this way.One of:
tfe-ui(HCP Terraform website),tfe-api(API (including Lodol)),tfe-configuration-version(Configuration upload). - Page
pagenumber - Which page of results to return, starting at 1.At least 1.
- Page size
page_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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization
organizationtext - 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.
- Category
categorytext - 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
- Organization
organizationtextRequired - The HCP Terraform organization. Pick one, or type its name.
- Search
searchtext - Part of a workspace name. Use * as a wildcard, as in prod-* or *-network.
- Project
project_idtext - Only workspaces in this project.
- Current run status
current_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 key
tag_keytext - Only workspaces with a tag of this key.
- Tag value
tag_valuetext - With Tag key: only that tag with this value.
- Sort by
sorttext - 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). - Page
pagenumber - Which page of results to return, starting at 1.At least 1.
- Page size
page_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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization
organizationtext - 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.
- Reason
reasontext - 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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization
organizationtext - 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 unlock
forcetrue/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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Variable
variable_idtextRequired - The variable. Pick one of the workspace's, or give its id (var-...).
- Organization
organizationtext - 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 key
keytext - A new name for the variable.
- Value
valuetext - A new value. Empty keeps the current one.
- Description
descriptiontext - A new description.
- Category
categorytext - Move it to the other category.One of:
terraform(Terraform variable),env(Environment variable). - HCL
hcltext - Read the value as HCL code (On) or as text (Off). Empty keeps the current setting.One of:
true(On),false(Off). - Make sensitive
sensitivetrue/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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Organization
organizationtext - 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 name
nametext - A new name: letters, numbers, - and _.
- Description
descriptiontext - A description of the workspace.
- Execution mode
execution_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 apply
auto_applytext - Turn applying without confirmation on or off. Empty keeps the current setting.One of:
true(On),false(Off). - Terraform version
terraform_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 directory
working_directorytext - The folder Terraform runs in, relative to the root of the uploaded configuration. Empty means the root.
- Move to project
project_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
- Workspace
workspacetextRequired - The workspace. Pick one, or give its id (ws-...), its name, or its link from HCP Terraform.
- Configuration
configurationtextRequired - The Terraform code, uploaded as main.tf.
- Organization
organizationtext - 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 files
additional_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 run
auto_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. - Speculative
speculativetrue/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"
}