No-code provisioning API reference

The no-code provisioning API allows you to create, configure, and deploy Terraform modules in the no-code provisioning workflows within HCP Terraform. For more information on no-code modules, refer to Designing No-Code Ready Modules.

Enable no-code provisioning for a module

POST /organizations/:organization_name/no-code-modules

Parameter	Description
`:organization_name`	The name of the organization the module belongs to.

To deploy a module using the no-code provisioning workflow, the module must meet the following requirement:

The module must exist in your organization's private registry.
The module must meet the design requirements for a no-code module.
You must enable no-code provisioning for the module.

You can send a POST request to the /no-code-modules endpoint to enable no-code provisioning for a specific module. You can also call this endpoint to set options for the allowed values of a variable for a no-code module in your organization.

Note: This endpoint can not be accessed with organization tokens. You must access it with a user token or team token.

Status	Response	Reason
200	JSON API document (`type: "no-code-modules"`)	Successfully enabled a module for no-code provisioning.
404	JSON API error object	Not found, or the user is unauthorized to perform this action.
422	JSON API error object	Malformed request body (e.g., missing attributes, wrong types, etc.).
500	JSON API error object	Internal system failure.

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 `"no-code-modules"`.
`data.attributes.version-pin`	string	Latest version of the module	The module version to use in no-code provisioning workflows.
`data.attributes.enabled`	boolean	`false`	Set to `true` to enable no-code provisioning workflows.
`data.relationships.registry-module.data.id`	string		The ID of a module in the organization's private registry.
`data.relationships.registry-module.data.type`	string		Must be `"registry-module"`.
`data.relationships.variable-options.data[].type`	string		Must be `"variable-options"`.
`data.relationships.variable-options.data[].attributes.variable-name`	string		The name of a variable within the module.
`data.relationships.variable-options.data[].attributes.variable-type`	string		The data type for the variable. Can be any type supported by Terraform.
`data.relationships.variable-options.data[].attributes.options`	Any[]		A list of allowed values for the variable.

Sample Payload

{
  "data": {
    "type": "no-code-modules",
    "attributes": {
      "version-pin":  "1.0.1",
      "enabled": true
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "mod-2aaFrmRPZs2N9epr",
          "type": "registry-module"
        }
      },
      "variable-options": {
        "data": [
          {
            "type": "variable-options",
            "attributes": {
              "variable-name": "amis",
              "variable-type": "string",
              "options": [
                "ami-1",
                "ami-2",
                "ami-3"
              ]
            }
          },
          {
            "type": "variable-options",
            "attributes": {
              "variable-name": "region",
              "variable-type": "string",
              "options": [
                "eu-north-1",
                "us-east-2",
                "us-west-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/organizations/my-organization/no-code-modules

Sample Response

{
  "data": {
    "id": "nocode-9HE91XDNY3faePn2",
    "type": "no-code-modules",
    "attributes": {
      "enabled": true,
      "version-pin": "1.0.1"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
      "registry-module": {
        "data": {
          "id": "mod-2aaFrmRPZs2N9epr",
          "type": "registry-modules"
        },
        "links": {
          "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr"
        }
      },
      "variable-options": {
        "data": [
          {
            "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
            "type": "variable-options"
          },
          {
            "id": "ncvaropt-dZMfdh9KBcwFjyv2",
            "type": "variable-options"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2"
    }
  }
}

Update no-code provisioning settings

PATCH /no-code-modules/:id

Parameter	Description
`:id`	The unique identifier of the no-code module.

Send a PATCH request to the /no-code-modules/:id endpoint to update the settings for the no-code provisioning of a module. You can update the following settings:

Enable or disable no-code provisioning.
Adjust the set of options for allowed variable values.
Change the module version being provisioned.
Change the module being provisioned.

The API call that enables no-code provisioning for a module returns that module's unique identifier.

Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

Status	Response	Reason
200	JSON API document (`type: "no-code-modules"`)	Successfully updated a no-code module.
404	JSON API error object	Not found, or the user is unauthorized to perform this action.
422	JSON API error object	Malformed request body (e.g., missing attributes, wrong types, etc.).
500	JSON API error object	Internal system failure.

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 `"no-code-modules"`.
`data.attributes.version-pin`	string	Existing value	The module version to use in no-code provisioning workflows.
`data.attributes.enabled`	boolean	Existing value	Set to `true` to enable no-code provisioning workflows, or `false` to disable them.
`data.relationships.registry-module.data.id`	string	Existing value	The ID of a module in the organization's Private Registry.
`data.relationships.registry-module.data.type`	string	Existing value	Must be `"registry-module"`.
`data.relationships.variable-options.data[].id`	string		The ID of an existing variable-options set. If provided, a new variable-options set replaces the set with this ID. If not provided, this creates a new variable-option set.
`data.relationships.variable-options.data[].type`	string		Must be `"variable-options"`.
`data.relationships.variable-options.data[].attributes.variable-name`	string		The name of a variable within the module.
`data.relationships.variable-options.data[].attributes.variable-type`	string		The data type for the variable. Can be any type supported by Terraform.
`data.relationships.variable-options.data[].attributes.options`	Any[]		A list of allowed values for the variable.

Sample Payload

{
  "data": {
    "type": "no-code-modules",
    "attributes": {
      "enabled": false
    },
    "relationships": {
      "registry-module": {
        "data": {
          "id": "mod-zyai9dwH4VPPaVuC",
          "type": "registry-module"
        }
      },
      "variable-options": {
        "data": [
          {
            "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
            "type": "variable-options",
            "attributes": {
              "variable-name": "Linux AMIs",
              "variable-type": "array",
              "options": [
                "Xenial Xerus",
                "Trusty Tahr"
              ]
            }
          },
          {
            "id": "ncvaropt-dZMfdh9KBcwFjyv2",
            "type": "variable-options",
            "attributes": {
              "variable-name": "region",
              "variable-type": "array",
              "options": [
                "eu-north-1",
                "us-east-2",
                "us-west-1"
              ]
            }
          }
        ]
      }
    }
  }
}

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/no-code-modules/nocode-9HE91XDNY3faePn2

Sample Response

{
  "data": {
    "id": "nocode-9HE91XDNY3faePn2",
    "type": "no-code-modules",
    "attributes": {
      "enabled": true,
      "version-pin": "1.0.1"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
      "registry-module": {
        "data": {
          "id": "mod-2aaFrmRPZs2N9epr",
          "type": "registry-modules"
        },
        "links": {
          "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr"
        }
      },
      "variable-options": {
        "data": [
          {
            "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
            "type": "variable-options"
          },
          {
            "id": "ncvaropt-dZMfdh9KBcwFjyv2",
            "type": "variable-options"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2"
    }
  }
}

Read a no-code module's properties

GET /no-code-modules/:id

Parameter	Description
`:id`	The unique identifier of the no-code module.

Use this API to read the details of an existing no-code module.

The API call that enables no-code provisioning for a module returns that module's unique identifier.

Status	Response	Reason
200	JSON API document (`type: "no-code-modules"`)	Successfully read the no-code module.
400	JSON API error object	Invalid `include` parameter.
404	JSON API error object	Not found, or the user is unauthorized to perform this action.
422	JSON API error object	Malformed request body (e.g., missing attributes, wrong types, etc.).
500	JSON API error object	Internal system failure.

Query Parameters

This endpoint uses our standard URL query parameters. Use HTML URL encoding syntax, such as %5B to represent [ and %5D to represent ], if your tooling does not automatically encode URLs.

Terraform returns related resources when you add the include query parameter to the request.

Parameter	Description
`include`	List related resource to include in the response.

The following resource types are available:

Resource Name	Description
`variable_options`	Module variables with a configured set of allowed values.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2?include=variable_options

Sample Response

{
  "data": {
    "id": "nocode-9HE91XDNY3faePn2",
    "type": "no-code-modules",
    "attributes": {
      "enabled": true,
      "version-pin": "1.0.1"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
      "registry-module": {
        "data": {
          "id": "mod-2aaFrmRPZs2N9epr",
          "type": "registry-modules"
        },
        "links": {
          "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr"
        }
      },
      "variable-options": {
        "data": [
          {
            "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
            "type": "variable-options"
          },
          {
            "id": "ncvaropt-dZMfdh9KBcwFjyv2",
            "type": "variable-options"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2"
    }
  },
  "included": [
    {
      "id": "ncvaropt-fcHDfnZ1EGdRzFNC",
      "type": "variable-options",
      "attributes": {
        "variable-name": "Linux AMIs",
        "variable-type": "array",
        "options": [
          "Xenial Xerus",
          "Trusty Tahr"
        ]
      },
      "relationships": {
        "no-code-allowed-module": {
          "data": {
            "id": "nocode-9HE91XDNY3faePn2",
            "type": "no-code-allowed-modules"
          }
        }
      }
    },
    {
      "id": "ncvaropt-dZMfdh9KBcwFjyv2",
      "type": "variable-options",
      "attributes": {
        "variable-name": "region",
        "variable-type": "array",
        "options": [
          "eu-north-1",
          "us-east-2",
          "us-west-1"
        ]
      },
      "relationships": {
        "no-code-allowed-module": {
          "data": {
            "id": "nocode-9HE91XDNY3faePn2",
            "type": "no-code-allowed-modules"
          }
        }
      }
    }
  ]
}

Create a no-code module workspace

This endpoint creates a workspace from a no-code module.

POST /no-code-modules/:id/workspaces

Parameter	Description
`:id`	The ID of the no-code module to provision.

Each HCP Terraform organization has a list of which modules you can use to create workspaces using no-code provisioning. You can use this API to create a workspace by selecting a no-code module to enable a no-code provisioning workflow.

Note: This endpoint can not be accessed with organization tokens. You must access it with a user token or team token.

Status	Response	Reason
200	JSON API document (`type: "workspaces"`)	Successfully created a workspace from a no-code module for no-code provisioning.
404	JSON API error object	Not found, or the user is unauthorized to perform this action.
422	JSON API error object	Malformed request body (e.g., missing attributes, wrong types, etc.).
500	JSON API error object	Internal system failure.

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	none	Must be `"workspaces"`.
`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`.
`data.attributes.auto_apply`	boolean	`false`	If `true`, Terraform automatically applies changes when a Terraform `plan` is successful.
`data.attributes.description`	string	`""`	A description for the workspace.
`data.attributes.execution-mode`	string	none	Which execution mode to use. Valid values are `remote`, and `agent`. When not provided, defaults to `remote`.
`data.attributes.name`	string	none	The name of the workspace. You can only include letters, numbers, `-`, and `_`. Terraform uses this value to identify the workspace and must be unique in the organization.
`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	(nothing)	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.relationships.project.data.id`	string		The ID of the project to create the workspace in. 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.project.data.type`	string		Must be `"project"`.
`data.relationships.vars.data[].type`	string		Must be `"vars"`.
`data.relationships.vars.data[].attributes.key`	string		The name of the variable.
`data.relationships.vars.data[].attributes.value`	string	`""`	The value of the variable.
`data.relationships.vars.data[].attributes.description`	string		The description of the variable.
`data.relationships.vars.data[].attributes.category`	string		Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`.
`data.relationships.vars.data[].attributes.hcl`	boolean	`false`	Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables.
`data.relationships.vars.data[].attributes.sensitive`	boolean	`false`	Whether the value is sensitive. If `true` then the variable is written once and not visible thereafter.

Sample Payload

{
  "data": {
    "type": "workspaces",
    "attributes": {
      "name":  "no-code-workspace",
      "description": "A workspace to enable the no-code provisioning workflow."
    },
    "relationships": {
      "project": {
        "data": {
          "id": "prj-yuEN6sJVra5t6XVy",
          "type": "project"
        }
      },
      "vars": {
        "data": [
          {
            "type": "vars",
            "attributes": {
              "key": "region",
              "value": "eu-central-1",
              "category": "terraform",
              "hcl": true,
              "sensitive": false,
            }
          },
          {
            "type": "vars",
            "attributes": {
              "key": "ami",
              "value": "ami‑077062",
              "category": "terraform",
              "hcl": true,
              "sensitive": false,
            }
          }
        ]
      }
    }
  }
}

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/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces

Sample Response

{
  "data": {
    "id": "ws-qACTToFUM5BvDKhC",
    "type": "workspaces",
    "attributes": {
      "allow-destroy-plan": true,
      "auto-apply": false,
      "auto-destroy-at": null,
      "auto-destroy-status": null,
      "created-at": "2023-09-08T10:36:04.391Z",
      "environment": "default",
      "locked": false,
      "name": "no-code-workspace",
      "queue-all-runs": false,
      "speculative-enabled": true,
      "structured-run-output-enabled": true,
      "terraform-version": "1.5.6",
      "working-directory": null,
      "global-remote-state": true,
      "updated-at": "2023-09-08T10:36:04.427Z",
      "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": "2023-09-08T10:36:04.391Z",
      "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": true,
        "can-force-delete": true,
        "can-manage-assessments": true,
        "can-manage-ephemeral-workspaces": 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-module",
      "source-name": null,
      "source-url": null,
      "source-module-id": "private/my-organization/lambda/aws/1.0.9",
      "no-code-upgrade-available": false,
      "tag-names": [],
      "setting-overwrites": {
        "execution-mode": false,
        "agent-pool": false
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      },
      "current-run": {
        "data": null
      },
      "latest-run": {
        "data": null
      },
      "outputs": {
        "data": []
      },
      "remote-state-consumers": {
        "links": {
          "related": "/api/v2/workspaces/ws-qACTToFUM5BvDKhC/relationships/remote-state-consumers"
        }
      },
      "current-state-version": {
        "data": null
      },
      "current-configuration-version": {
        "data": {
          "id": "cv-vizi2p3mnrt3utgA",
          "type": "configuration-versions"
        },
        "links": {
          "related": "/api/v2/configuration-versions/cv-vizi2p3mnrt3utgA"
        }
      },
      "agent-pool": {
        "data": null
      },
      "readme": {
        "data": null
      },
      "project": {
        "data": {
          "id": "prj-yuEN6sJVra5t6XVy",
          "type": "projects"
        }
      },
      "current-assessment-result": {
        "data": null
      },
      "no-code-module-version": {
        "data": {
          "id": "nocodever-vFcQjZLs3ZHTe4TU",
          "type": "no-code-module-versions"
        }
      },
      "vars": {
        "data": []
      }
    },
    "links": {
      "self": "/api/v2/organizations/my-organization/workspaces/no-code-workspace",
      "self-html": "/app/my-organization/workspaces/no-code-workspace"
    }
  }
}

Initiate a no-code workspace update

Upgrading a workspace's no-code provisioning settings is a multi-step process.

Use this API to initiate the update. HCP Terraform starts a new plan, which describes the resources to add, update, or remove from the workspace.
Poll the read workspace upgrade plan status API to wait for HCP Terraform to complete the plan.
Use the confirm and apply a workspace upgrade plan API to complete the workspace upgrade.

POST /no-code-modules/:no_code_module_id/workspaces/:id/upgrade

Parameter	Description
`:no_code_module_id`	The ID of the no-code module.
`:id`	The ID of the workspace.

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.relationships.vars.data[].type`	string		Must be `"vars"`.
`data.relationships.vars.data[].attributes.key`	string		The name of the variable.
`data.relationships.vars.data[].attributes.value`	string	`""`	The value of the variable.
`data.relationships.vars.data[].attributes.description`	string		The description of the variable.
`data.relationships.vars.data[].attributes.category`	string		Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`.
`data.relationships.vars.data[].attributes.hcl`	boolean	`false`	Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables.
`data.relationships.vars.data[].attributes.sensitive`	boolean	`false`	Whether the value is sensitive. If `true` then the variable is written once and not visible thereafter.

Sample Payload

{
  "data": {
    "type": "workspaces",
    "relationships": {
        "vars": {
        "data": [
          {
            "type": "vars",
            "attributes": {
              "key": "region",
              "value": "eu-central-1",
              "category": "terraform",
              "hcl": true,
              "sensitive": false,
            }
          },
          {
            "type": "vars",
            "attributes": {
              "key": "ami",
              "value": "ami‑077062",
              "category": "terraform",
              "hcl": true,
              "sensitive": false,
            }
          }
        ]
      }
    }
  }
}

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/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade

Sample Response

{
  "data": {
    "id": "run-Cyij8ctBHM1g5xdX",
    "type": "workspace-upgrade",
    "attributes": {
      "status": "planned",
      "plan-url": "https://app.terraform.io/app/my-organization/no-code-workspace/runs/run-Cyij8ctBHM1g5xdX"
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ws-VvKtcfueHNkR6GqP",
          "type": "workspaces"
        }
      }
    }
  }
}

Read workspace upgrade plan status

This endpoint returns the plan details and status for updating a workspace to new no-code provisioning settings.

GET /no-code-modules/:no_code_module_id/workspaces/:workspace_id/upgrade/:id

Parameter	Description
`:no_code_module_id`	The ID of the no-code module.
`:workspace_id`	The ID of workspace.
`:id`	The ID of update.

Returns the details of a no-code workspace update run, including the run's current state, such as pending, fetching, planning, planned, or cost_estimated. Refer to Run States and Stages for more information on the states a run can return.

Status	Response	Reason
200	JSON API document (`type: "workspace-upgrade"`)	Success
404	JSON API error object	Workspace upgrade not found, or user unauthorized to perform action

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade/run-Cyij8ctBHM1g5xdX

Sample Response

{
  "data": {
    "id": "run-Cyij8ctBHM1g5xdX",
    "type": "workspace-upgrade",
    "attributes": {
      "status": "planned_and_finished",
      "plan-url": "https://app.terraform.io/app/my-organization/no-code-workspace/runs/run-Cyij8ctBHM1g5xdX"
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "ws-VvKtcfueHNkR6GqP",
          "type": "workspaces"
        }
      }
    }
  }
}

Confirm and apply a workspace upgrade plan

Use this endpoint to confirm an update and finalize the update for a workspace to use new no-code provisioning settings.

POST /no-code-modules/:no_code_module_id/workspaces/:workspace_id/upgrade/:id

Parameter	Description
`:no_code_module_id`	The ID of the no-code module.
`:workspace_id`	The ID of workspace.
`:id`	The ID of update.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade/run-Cyij8ctBHM1g5xdX

Sample Response

{ "Workspace update completed" }