Type '/' to Search

»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

ParameterDescription
:workspace_idThe 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 pathTypeDefaultDescription
data.typestringMust be "vars".
data.attributes.keystringThe name of the variable.
data.attributes.valuestring""The value of the variable.
data.attributes.descriptionstringThe description of the variable.
data.attributes.categorystringWhether this is a Terraform or environment variable. Valid values are "terraform" or "env".
data.attributes.hclboolfalseWhether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables.
data.attributes.sensitiveboolfalseWhether 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 pathTypeDefaultDescription
filter.workspace.namestringThe name of the workspace that owns the variable.
filter.organization.namestringThe name of the organization that owns the workspace.

»Sample Payload

{
  "data": {
    "type":"vars",
    "attributes": {
      "key":"some_key",
      "value":"some_value",
      "description":"some description",
      "category":"terraform",
      "hcl":false,
      "sensitive":false
    }
  }
}

{  "data": {    "type":"vars",    "attributes": {      "key":"some_key",      "value":"some_value",      "description":"some description",      "category":"terraform",      "hcl":false,      "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/workspaces/ws-4j8p6jX1w33MiDC7/vars

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars

»Sample Response

{
  "data": {
    "id":"var-EavQ1LztoRTQHSNT",
    "type":"vars",
    "attributes": {
      "key":"some_key",
      "value":"some_value",
      "description":"some description",
      "sensitive":false,
      "category":"terraform",
      "hcl":false
    },
    "relationships": {
      "configurable": {
        "data": {
          "id":"ws-4j8p6jX1w33MiDC7",
          "type":"workspaces"
        },
        "links": {
          "related":"/api/v2/organizations/my-organization/workspaces/my-workspace"
        }
      }
    },
    "links": {
      "self":"/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-EavQ1LztoRTQHSNT"
    }
  }
}

{  "data": {    "id":"var-EavQ1LztoRTQHSNT",    "type":"vars",    "attributes": {      "key":"some_key",      "value":"some_value",      "description":"some description",      "sensitive":false,      "category":"terraform",      "hcl":false    },    "relationships": {      "configurable": {        "data": {          "id":"ws-4j8p6jX1w33MiDC7",          "type":"workspaces"        },        "links": {          "related":"/api/v2/organizations/my-organization/workspaces/my-workspace"        }      }    },    "links": {      "self":"/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-EavQ1LztoRTQHSNT"    }  }}

»List Variables

GET /workspaces/:workspace_id/vars

ParameterDescription
:workspace_idThe ID of the workspace to list variables for.

»Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
"https://app.terraform.io/api/v2/workspaces/ws-cZE9LERN3rGPRAmH/vars"

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \"https://app.terraform.io/api/v2/workspaces/ws-cZE9LERN3rGPRAmH/vars"

»Sample Response

{
  "data": [
    {
      "id":"var-AD4pibb9nxo1468E",
      "type":"vars","attributes": {
        "key":"name",
        "value":"hello",
        "description":"some description",
        "sensitive":false,
        "category":"terraform",
        "hcl":false
      },
      "relationships": {
        "configurable": {
          "data": {
            "id":"ws-cZE9LERN3rGPRAmH",
            "type":"workspaces"
          },
          "links": {
            "related":"/api/v2/organizations/my-organization/workspaces/my-workspace"
          }
        }
      },
      "links": {
        "self":"/api/v2/workspaces/ws-cZE9LERN3rGPRAmH/vars/var-AD4pibb9nxo1468E"
      }
    }
  ]
}

{  "data": [    {      "id":"var-AD4pibb9nxo1468E",      "type":"vars","attributes": {        "key":"name",        "value":"hello",        "description":"some description",        "sensitive":false,        "category":"terraform",        "hcl":false      },      "relationships": {        "configurable": {          "data": {            "id":"ws-cZE9LERN3rGPRAmH",            "type":"workspaces"          },          "links": {            "related":"/api/v2/organizations/my-organization/workspaces/my-workspace"          }        }      },      "links": {        "self":"/api/v2/workspaces/ws-cZE9LERN3rGPRAmH/vars/var-AD4pibb9nxo1468E"      }    }  ]}

»Update Variables

PATCH /workspaces/:workspace_id/vars/:variable_id

ParameterDescription
:workspace_idThe ID of the workspace that owns the variable.
:variable_idThe 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 pathTypeDefaultDescription
data.typestringMust be "vars".
data.idstringThe ID of the variable to update.
data.attributesobjectNew 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

{
  "data": {
    "id":"var-yRmifb4PJj7cLkMG",
    "attributes": {
      "key":"name",
      "value":"mars",
      "description":"some description",
      "category":"terraform",
      "hcl": false,
      "sensitive": false
    },
    "type":"vars"
  }
}

{  "data": {    "id":"var-yRmifb4PJj7cLkMG",    "attributes": {      "key":"name",      "value":"mars",      "description":"some description",      "category":"terraform",      "hcl": false,      "sensitive": false    },    "type":"vars"  }}

»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/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request PATCH \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG

»Sample Response

{
  "data": {
    "id":"var-yRmifb4PJj7cLkMG",
    "type":"vars",
    "attributes": {
      "key":"name",
      "value":"mars",
      "description":"some description",
      "sensitive":false,
      "category":"terraform",
      "hcl":false
    },
    "relationships": {
      "configurable": {
        "data": {
          "id":"ws-4j8p6jX1w33MiDC7",
          "type":"workspaces"
        },
        "links": {
          "related":"/api/v2/organizations/workspace-v2-06/workspaces/workspace-v2-06"
        }
      }
    },
    "links": {
      "self":"/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG"
    }
  }
}

{  "data": {    "id":"var-yRmifb4PJj7cLkMG",    "type":"vars",    "attributes": {      "key":"name",      "value":"mars",      "description":"some description",      "sensitive":false,      "category":"terraform",      "hcl":false    },    "relationships": {      "configurable": {        "data": {          "id":"ws-4j8p6jX1w33MiDC7",          "type":"workspaces"        },        "links": {          "related":"/api/v2/organizations/workspace-v2-06/workspaces/workspace-v2-06"        }      }    },    "links": {      "self":"/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG"    }  }}

»Delete Variables

DELETE /workspaces/:workspace_id/vars/:variable_id

ParameterDescription
:workspace_idThe ID of the workspace that owns the variable.
:variable_idThe ID of the variable to be deleted.

»Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request DELETE \  https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG