Terraform
No-code provisioning API
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" }