Variables API
Important: The Variables API is deprecated and will be removed in a future release. All existing integrations with this API should transition to the Workspace Variables API.
This set of APIs covers create, update, list and delete operations on variables.
Create a Variable
POST /vars
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. |
data.relationships.workspace.data.type | string | Must be "workspaces" . | |
data.relationships.workspace.data.id | string | The ID of the workspace that owns the variable. Obtain workspace IDs from the workspace settings or the Show Workspace endpoint. |
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 /vars
Query Parameters
These are standard URL query parameters. Remember to percent-encode [
as %5B
and ]
as %5D
if your tooling doesn't automatically encode URLs.
Parameter | Description |
---|---|
filter[workspace][name] | Optional The name of one workspace to list variables for. If included, you must also include the organization name filter. |
filter[organization][name] | Optional The name of the organization that owns the desired workspace. If included, you must also included the workspace name filter. |
These two parameters are optional but linked; if you include one, you must include both. Without a filter, this method lists variables for all workspaces where you have permission to read variables. (More about permissions.)
Sample Request
Sample Response
Update Variables
PATCH /vars/:variable_id
Parameter | Description |
---|---|
:variable_id | The ID of the variable to be updated. |
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.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 /vars/:variable_id
Parameter | Description |
---|---|
:variable_id | The ID of the variable to be deleted. |
Sample Request