---
updatedAt: 2026-05-05T11:11:03.000Z
agentTools:
  projectIndex: https://docs.scalr.io/llms.txt
---

# Create a variable set

Creates a new variable set.


# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "VariableSet": {
        "description": "A named container of variables.\nVariable sets can be granted access to environments and applied to workspaces.\n\nThe extra fields below are not available in response by default. Ask for them explicitly in the query parameter `fields[var-sets]`:\n* applied-at\n* applied-by-email",
        "properties": {
          "attributes": {
            "properties": {
              "applied-at": {
                "description": "UTC timestamp when this variable set was applied to the workspace. Only present when filtering by a single workspace.",
                "format": "date-time",
                "nullable": true,
                "readOnly": true,
                "type": "string"
              },
              "applied-by-email": {
                "description": "Email of the user who applied this variable set to the workspace. Only present when filtering by a single workspace.",
                "nullable": true,
                "readOnly": true,
                "type": "string"
              },
              "description": {
                "description": "Optional description of the variable set.",
                "maxLength": 512,
                "nullable": true,
                "type": "string"
              },
              "is-shared": {
                "default": false,
                "description": "If true, the variable set is available in all current and future environments of the account without explicitly linking it to each environment.",
                "type": "boolean"
              },
              "name": {
                "description": "The name of the variable set. Unique within an account.",
                "maxLength": 255,
                "type": "string"
              },
              "updated-at": {
                "description": "The UTC timestamp of the last update to this variable set.",
                "format": "date-time",
                "readOnly": true,
                "type": "string"
              },
              "updated-by-email": {
                "description": "The email of the user who last updated this variable set.",
                "nullable": true,
                "readOnly": true,
                "type": "string"
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          },
          "id": {
            "readOnly": true,
            "type": "string"
          },
          "links": {
            "properties": {
              "self": {
                "readOnly": true,
                "type": "string"
              }
            },
            "readOnly": true,
            "type": "object"
          },
          "relationships": {
            "properties": {
              "account": {
                "description": "The account this variable set belongs to.",
                "properties": {
                  "data": {
                    "nullable": true,
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "type": {
                        "enum": [
                          "accounts",
                          ""
                        ],
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "id"
                    ],
                    "type": "object"
                  }
                },
                "readOnly": true,
                "required": [
                  "data"
                ],
                "type": "object"
              },
              "environments": {
                "description": "The list of environments this integration is directly linked to.",
                "properties": {
                  "data": {
                    "items": {
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "type": {
                          "enum": [
                            "environments",
                            ""
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "type",
                        "id"
                      ],
                      "type": "object"
                    },
                    "nullable": true,
                    "type": "array"
                  }
                },
                "required": [
                  "data"
                ],
                "type": "object"
              },
              "owners": {
                "description": "The teams this variable set belongs to.",
                "properties": {
                  "data": {
                    "items": {
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "type": {
                          "enum": [
                            "teams",
                            ""
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "type",
                        "id"
                      ],
                      "type": "object"
                    },
                    "nullable": true,
                    "type": "array"
                  }
                },
                "required": [
                  "data"
                ],
                "type": "object"
              }
            },
            "type": "object"
          },
          "type": {
            "enum": [
              "var-sets"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "attributes"
        ],
        "type": "object"
      },
      "VariableSetDocument": {
        "description": "JSON:API Document.\n\nsee: https://jsonapi.org/format/#document-structure",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/VariableSet"
          },
          "included": {
            "items": {
              "type": "object"
            },
            "readOnly": true,
            "type": "array"
          },
          "meta": {
            "readOnly": true,
            "type": "object"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "API-Key": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Scalr IACP API",
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    },
    "title": "Scalr IACP API",
    "version": "unversioned"
  },
  "openapi": "3.0.0",
  "paths": {
    "/var-sets": {
      "post": {
        "description": "Creates a new variable set.\n",
        "operationId": "create_var_set",
        "parameters": [
          {
            "description": "The comma-separated list of relationship paths.",
            "explode": false,
            "in": "query",
            "name": "include",
            "required": false,
            "schema": {
              "items": {
                "enum": [
                  "account",
                  "environments",
                  "owners"
                ],
                "type": "string"
              },
              "type": "array"
            }
          },
          {
            "description": "The value of the fields[resource-type] parameter is a comma-separated list that refers to the name of the fields to be returned for the resource. An empty value indicates that no fields should be returned.",
            "explode": true,
            "in": "query",
            "name": "fields",
            "required": false,
            "schema": {
              "properties": {
                "accounts": {
                  "description": "The comma-separated list of fields to return in response for Account resource.",
                  "type": "string"
                },
                "environments": {
                  "description": "The comma-separated list of fields to return in response for Environment resource.",
                  "type": "string"
                },
                "teams": {
                  "description": "The comma-separated list of fields to return in response for Team resource.",
                  "type": "string"
                },
                "var-sets": {
                  "description": "The comma-separated list of fields to return in response for VariableSet resource.",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "style": "deepObject"
          }
        ],
        "requestBody": {
          "content": {
            "application/vnd.api+json": {
              "schema": {
                "$ref": "#/components/schemas/VariableSetDocument"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/vnd.api+json": {
                "schema": {
                  "$ref": "#/components/schemas/VariableSetDocument"
                }
              }
            },
            "description": "Created."
          },
          "403": {
            "description": "User unauthorized to perform action."
          },
          "404": {
            "description": "Relationship resource not found, or user unauthorized to perform action."
          },
          "422": {
            "description": "Malformed request body or validation error."
          },
          "4XX": {
            "description": "Client error."
          },
          "5XX": {
            "description": "Server error."
          }
        },
        "summary": "Create a variable set",
        "tags": [
          "var-sets"
        ],
        "x-resource": "VariableSet",
        "x-service": "tf-api"
      }
    }
  },
  "security": [
    {
      "API-Key": []
    }
  ],
  "servers": [
    {
      "url": "https://{Domain}/api/iacp/v3",
      "variables": {
        "Domain": {
          "default": "example.scalr.io",
          "description": "Domain where Scalr is hosted"
        }
      }
    }
  ]
}
```

# Sibling pages

* [List variable sets](https://docs.scalr.io/scalr/reference/list_var_sets.md)
* [Delete a variable set](https://docs.scalr.io/scalr/reference/delete_var_set.md)
* [Get a variable set](https://docs.scalr.io/scalr/reference/get_var_set.md)
* [Update a variable set](https://docs.scalr.io/scalr/reference/update_var_set.md)