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
Sample Request
Sample Response
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
Sample Request
Sample Response
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
Sample Response
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 | none | 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 | none | 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 | none | Must be "project" . | |
data.relationships.vars.data[].type | string | none | Must be "vars" . | |
data.relationships.vars.data[].attributes.key | string | none | The name of the variable. | |
data.relationships.vars.data[].attributes.value | string | "" | The value of the variable. | |
data.relationships.vars.data[].attributes.description | string | none | The description of the variable. | |
data.relationships.vars.data[].attributes.category | string | none | 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 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
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 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
Sample Response
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
Sample Response