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
Sample Request
Sample Response
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
Sample Request
Sample Response
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. |
Available Related Resources
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
Sample Response
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
Sample Request
Sample Response
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
Sample Request
Sample Response
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
Sample Response
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
Sample Response