Workspace Variables API
This set of APIs covers create, update, list and delete operations on workspace variables.
Viewing variables requires permission to read variables for their workspace. Creating, updating, and deleting variables requires permission to read and write variables for their workspace. (More about permissions.)
Create a Variable
POST /workspaces/:workspace_id/vars
Parameter | Description |
---|---|
:workspace_id | The ID of the workspace to create the variable in. |
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 "vars" . | |
data.attributes.key | string | The name of the variable. | |
data.attributes.value | string | "" | The value of the variable. |
data.attributes.description | string | The description of the variable. | |
data.attributes.category | string | Whether this is a Terraform or environment variable. Valid values are "terraform" or "env" . | |
data.attributes.hcl | bool | false | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. |
data.attributes.sensitive | bool | false | Whether the value is sensitive. If true then the variable is written once and not visible thereafter. |
Deprecation warning: The custom filter
properties are replaced by JSON API relationships
and will be removed from future versions of the API!
Key path | Type | Default | Description |
---|---|---|---|
filter.workspace.name | string | The name of the workspace that owns the variable. | |
filter.organization.name | string | The name of the organization that owns the workspace. |
Sample Payload
Sample Request
Sample Response
List Variables
GET /workspaces/:workspace_id/vars
Parameter | Description |
---|---|
:workspace_id | The ID of the workspace to list variables for. |
Sample Request
Sample Response
Update Variables
PATCH /workspaces/:workspace_id/vars/:variable_id
Parameter | Description |
---|---|
:workspace_id | The ID of the workspace that owns the variable. |
:variable_id | The ID of the variable to be updated. |
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 "vars" . | |
data.id | string | The ID of the variable to update. | |
data.attributes | object | New attributes for the variable. This object can include key , value , description , category , hcl , and sensitive properties, which are described above under create a variable. All of these properties are optional; if omitted, a property will be left unchanged. |
Sample Payload
Sample Request
Sample Response
Delete Variables
DELETE /workspaces/:workspace_id/vars/:variable_id
Parameter | Description |
---|---|
:workspace_id | The ID of the workspace that owns the variable. |
:variable_id | The ID of the variable to be deleted. |
Sample Request