How to run Terraform Actions using API – HashiCorp Help Center

Introduction

Terraform Actions allow you to perform Terraform workflow without altering resource state. While these are often triggered via the CLI using the -invoke flag, they can also be initiated via the HCP Terraform Runs API.

Expected Outcome

After following this guide, you will be able to trigger a specific Terraform Action in a VCS-connected workspace using a single API call, bypassing the standard plan/apply lifecycle for the rest of your infrastructure.

Prerequisites

Terraform Version: v1.14.0 or higher
Provider Support: A provider that implements Actions
Authentication: A valid HCP Terraform API Token (User, Team, or Organization)
Workspace: A VCS-connected workspace with a configuration already uploaded / linked. Here is an example: https://developer.hashicorp.com/terraform/tutorials/configuration-language/actions#review-example-configuration

Use Case

You need to trigger a specific operational task on demand from an external orchestration tool or CI/CD pipeline without triggering a full infrastructure deployment.

Procedure

Step 1: Identify the Action Address

The API requires the full address of the action defined in your .tf files. The syntax depends on where the action is defined:

Root Module: action.action_type.action_name

Example: action.aws_lambda_invoke.testing

Inside a Module: module.module_name.action.action_type.action_name

Example: module.utils.action.aws_lambda_invoke.cleanup

Step 2: Prepare the API Payload

Construct a JSON body for the runs endpoint.

Important: The invoke-action-addrs attribute is an array, but only one action is allowed per run. Including multiple elements in this array will result in an API error.

Example Payload (payload.json):

JSON

{
    "data": {
        "type": "runs",
        "attributes": {
            "message": "Triggering maintenance action via API",
            "invoke-action-addrs": [
                "action.aws_lambda_invoke.testing"
            ]
        },
        "relationships": {
            "workspace": {
                "data": {
                    "type": "workspaces",
                    "id": "ws-xxxxxxxxxxxxxx"
                }
            }
        }
    }
}

Step 3: Execute the API Call

Send a POST request to the HCP Terraform API. Replace $TOKEN with your API key and ensure the Content-Type header is set to the specific JSON:API format required by HashiCorp.

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

Step 4: Monitor the Run

Once triggered, the workspace will enter a "Plan" state. Because you specified an action address, Terraform will focus only on that action. You can follow the run status in the HCP Terraform UI or via the GET /api/v2/runs/run_id endpoint.

Additional Information

HCP Terraform API Documentation: Runs API Reference
Terraform Language: Invoke Actions Overview
Constraint Note: If the workspace is currently locked or has a run in progress, the API request will fail with a 409 Conflict.