No-Code Provisioning API

The No-Code Provisioning API allows you to establish and configure a list of Terraform modules that you can use in no-code provisioning workflows within HCP Terraform. For more information on no-code modules, see Designing No-Code Ready Modules.

Allow No-Code Provisioning of a Module within an Organization

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

Parameter	Description
`:organization_name`	The name of the organization where no-code provisioning workflows should be allowed for this module.

Each HCP Terraform organization has a list of which modules you can use to establish workspaces using no-code provisioning. You can use this API to enable no-code provisioning for a specific module. You can also use this API 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/hashicorp/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": "hashicorp",          "type": "organizations"        },        "links": {          "related": "/api/v2/organizations/hashicorp"        }      },      "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 for a Module

PATCH /no-code-modules/:id

Parameter	Description
`:id`	The unique identifier for a No-Code-Allowed module.

Use this API to update the settings for the no-code provisioning of a module. You can use this API to:

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	(previous value)	The module version to use in no-code provisioning workflows.
`data.attributes.enabled`	boolean	(previous value)	Set to `true` to enable no-code provisioning workflows, or `false` to disable them.
`data.relationships.registry-module.data.id`	string	(previous value)	The ID of a module in the organization's Private Registry.
`data.relationships.registry-module.data.type`	string	(previous value)	Must be `"registry-module"`.
`data.relationships.variable-options.data[].id`	string	(new value)	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": "hashicorp",          "type": "organizations"        },        "links": {          "related": "/api/v2/organizations/hashicorp"        }      },      "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 for a No-Code-Allowed module.

Use this API to read the details of an existing No-Code-Allowed 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. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

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

This GET endpoint can optionally return related resources if you request them with the include query parameter. 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": "hashicorp",          "type": "organizations"        },        "links": {          "related": "/api/v2/organizations/hashicorp"        }      },      "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"          }        }      }    }  ]}

BEGIN: TFC:only name:ncm-update

Create a Workspace and Deploy Resources

This endpoint creates a Workspace for No-Code Provisioning.

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

Parameter	Description
`:id`	The id of the No-Code Module that should be used for provisioning.

Each HCP Terraform organization has a list of which modules you can use to establish 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		Must be `"workspaces"`.
`data.attributes.name`	string		The name of the workspace, which can only include letters, numbers, -, and _. This will be used as an identifier and must be unique in the organization.
`data.attributes.description`	string	(nothing)	A description for the workspace.
`data.attributes.auto_apply`	boolean	`false`	Whether to automatically apply changes when a Terraform plan is successful, with some exceptions.
`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/hashicorp/lambda/aws/1.0.9",      "no-code-upgrade-available": false,      "tag-names": [],      "setting-overwrites": {        "execution-mode": false,        "agent-pool": false      }    },    "relationships": {      "organization": {        "data": {          "id": "hashicorp",          "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/hashicorp/workspaces/no-code-workspace",      "self-html": "/app/hashicorp/workspaces/no-code-workspace"    }  }}

Initiate a Workspace Update to new No-Code provisioning settings

Upgrading a workspace's No-code provisioning settings is a multi-step process. First, use this API to initiate the update. HCP Terraform will start a new plan, which will describe the resources that will be added, updated, or removed from the workspace, should you choose to confirm the plan in a later step.

After calling this API, the next step is to await the completion of the plan, by polling the API which shows plan status.

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/hashicorp/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 Run details for performing an upgrade. Status is the Run's status and can be in any of the Run's states, e.g. pending, fetching, planning, planned, cost_estimated.

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/hashicorp/no-code-workspace/runs/run-Cyij8ctBHM1g5xdX"    },    "relationships": {      "workspace": {        "data": {          "id": "ws-VvKtcfueHNkR6GqP",          "type": "workspaces"        }      }    }  }}

Confirm and Apply a Workspace Upgrade Plan

This endpoint is used for confirming an update and finalizing 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" }

END: TFC:only name:ncm-update

No-Code Provisioning API

Allow No-Code Provisioning of a Module within an Organization

Request Body

Sample Payload

Sample Request

Sample Response

Update No-Code Provisioning Settings for a Module

Request Body

Sample Payload

Sample Request

Sample Response

Read a No-Code Module's Properties

Query Parameters

Available Related Resources

Sample Request

Sample Response

Create a Workspace and Deploy Resources

Request Body

Sample Payload

Sample Request

Sample Response

Initiate a Workspace Update to new No-Code provisioning settings

Request Body

Sample Payload

Sample Request

Sample Response

Read Workspace Upgrade Plan Status

Sample Request

Sample Response

Confirm and Apply a Workspace Upgrade Plan

Sample Request

Sample Response