How to run Terraform Actions using API

Steps

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):

{
    "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.