--- updatedAt: 2026-05-28T08:16:45.000Z agentTools: projectIndex: https://docs.scalr.io/llms.txt --- # Create a Configuration Version Create the new configuration version for specific workspace # OpenAPI definition ````json { "components": { "schemas": { "ConfigurationVersion": { "description": "A Configuration Version describes the version of a Terraform configuration files.\n\nEach run is associated with a configuration version. It provides details of the source of the configuration files,\nthe upload status, and the relationships to VCS and the workspace.", "properties": { "attributes": { "properties": { "auto-queue-runs": { "description": "Indicates if a run should automatically be queued when the configuration has been uploaded.", "type": "boolean" }, "created-at": { "description": "Date/Time the configuration version was created.", "format": "date-time", "readOnly": true, "type": "string" }, "error-message": { "description": "This field contains the error description, when this configuration version's\nstatus is `errored`.", "nullable": true, "readOnly": true, "type": "string" }, "inputs": { "default": [], "description": "The input variables definitions.\n\nExample:\n```js\n[\n {\n \"description\": \"The name of the CloudSQL database.\",\n \"name\": \"cloudsql_database\",\n \"type\": \"string\"\n },\n {\"...\": \"\"...\"}\n]\n```", "items": { "anyOf": [ { "$ref": "#/components/schemas/RegistryInputOptional" }, { "$ref": "#/components/schemas/RegistryInputRequired" } ] }, "readOnly": true, "type": "array" }, "is-dry": { "description": "Indicates the configuration version can only be used to perform dry runs that comprise the plan,\ncost estimation (if enabled) and policy checks.\n\nWith this set to `true` the configuration cannot be used for an apply and never requires confirmation.", "type": "boolean" }, "size": { "description": "A blob size in bytes.", "nullable": true, "readOnly": true, "type": "integer" }, "source": { "description": "The origin for the configuration version.", "readOnly": true, "type": "string" }, "status": { "description": "The Configuration version's current status.\n\n* `pending` - waiting for the configuration files to upload.\n* `uploaded` - upload successful. At this point if the `auto-queue-runs: true` the new run should be `queued`.\n* `errored` - uploaded files post processing failed. Attribute `error-message` contains the details.", "enum": [ "errored", "pending", "uploaded" ], "readOnly": true, "type": "string" }, "status-timestamps": { "additionalProperties": { "format": "date-time", "type": "string" }, "description": "Date/Time of transition to each status that has occurred.", "readOnly": true, "type": "object" } }, "type": "object" }, "id": { "readOnly": true, "type": "string" }, "links": { "properties": { "self": { "readOnly": true, "type": "string" }, "upload": { "description": "URL for terraform configuration templates upload, that could be used to `PUT` a tar.gz archive of a local workspace directory. Available only in the create `configuration-versions` response.", "nullable": true, "readOnly": true, "type": "string" } }, "readOnly": true, "type": "object" }, "relationships": { "properties": { "vcs-revision": { "description": "When configuration version was uploaded from a VCS, this relation points to the Git commit information", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "vcs-revisions", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "readOnly": true, "required": [ "data" ], "type": "object" }, "workspace": { "description": "The workspace the configuration version belongs to.", "properties": { "data": { "nullable": true, "properties": { "id": { "type": "string" }, "type": { "enum": [ "workspaces", "" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" } }, "required": [ "data" ], "type": "object" } }, "type": "object" }, "type": { "enum": [ "configuration-versions" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "ConfigurationVersionDocument": { "description": "JSON:API Document.\n\nsee: https://jsonapi.org/format/#document-structure", "properties": { "data": { "$ref": "#/components/schemas/ConfigurationVersion" }, "included": { "items": { "type": "object" }, "readOnly": true, "type": "array" }, "meta": { "readOnly": true, "type": "object" } }, "type": "object" }, "RegistryInputOptional": { "properties": { "default": { "anyOf": [ { "type": "boolean" }, { "type": "integer" }, { "type": "number" }, { "type": "string" }, { "items": {}, "type": "array" }, { "type": "object" } ], "nullable": true }, "description": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "sensitive": { "default": false, "type": "boolean" }, "type": { "nullable": true, "type": "string" } }, "required": [ "default", "name" ], "type": "object" }, "RegistryInputRequired": { "properties": { "description": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "sensitive": { "default": false, "type": "boolean" }, "type": { "nullable": true, "type": "string" } }, "required": [ "name" ], "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": { "/configuration-versions": { "post": { "description": "Create the new configuration version for specific workspace", "operationId": "create_configuration_version", "parameters": [], "requestBody": { "content": { "application/vnd.api+json": { "examples": { "0-tarball": { "summary": "Create a configuration version for uploading files via URL", "value": "{\n \"data\": {\n \"type\": \"configuration-versions\",\n \"attributes\": {\n \"auto-queue-runs\": false,\n \"is-dry\": true\n },\n \"relationships\": {\n \"workspace\": {\n \"data\": {\n \"id\": \"ws-spturhj1dckd8so\",\n \"type\": \"workspaces\"\n }\n }\n }\n }\n}" }, "1-vcs": { "summary": "Create a configuration version for workspace linked to VCS", "value": "{\n \"data\": {\n \"type\": \"configuration-versions\",\n \"attributes\": {\n \"auto-queue-runs\": true,\n },\n \"relationships\": {\n \"workspace\": {\n \"data\": {\n \"id\": \"ws-spturhj1dckd8so\",\n \"type\": \"workspaces\"\n }\n }\n }\n }\n}" } }, "schema": { "$ref": "#/components/schemas/ConfigurationVersionDocument" } } } }, "responses": { "201": { "content": { "application/vnd.api+json": { "examples": { "0-tarball": { "summary": "Configuration version for uploading files via URL is created", "description": "Once configuration version is created, use URL returned in the `data.links.upload` to `PUT`\na tarball with terraform configuration files:\n\n```\n$ cd /path/to/tf-templates\n\n$ tar -czf cv.tgz .\n\n$ curl \\\n --header \"Content-Type: application/octet-stream\" \\\n --request PUT \\\n --data-binary @cv.tgz \\\n https://my.scalr.io/api/iacp/v3/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiJwUTlTSG5OM3VBUjdLXzhXVm1EWktBIn0.TDSfnHHTUrxUlflx_fAl8zKmXyT4mzviGiShvGncIgawrL_eEs3S0n1sDfUVXi2a_28XTyl4zuDI9QSazXK51AFM2Z_SZBhC.VaoUUTUKWbga_7vvCQasrQ.FzqF-Sxsc1ac3uVOiyX1L9X4wU8Xuh0qFdqwKoM5MfexRuz8DJU1xUVPO9_5vqYjr102R4g-hE9yt0hAxw5P-ziyodILLWRYJZzr_IGpSosKzHr0qsda6izQbihBUAyW.RY9XyG7pDCkPTpdeGUJhm7Hkzt6Z0oEwmxeDu-2HNQA\n```", "value": "{\n \"data\": {\n \"attributes\": {\n \"auto-queue-runs\": false,\n \"created-at\": \"2020-11-05T03:07:07Z\",\n \"error-message\": null,\n \"inputs\": null,\n \"source\": \"api\",\n \"is-dry\": true,\n \"status\": \"pending\",\n \"status-timestamps\": {\n \"pending-at\": \"2020-11-05T03:07:07Z\"\n },\n },\n \"id\": \"cv-t5uvn2j0fcnf7po\",\n \"links\": {\n \"self\": \"https://my.scalr.io/api/iacp/v3/configuration-versions/cv-t5uvn2j0fcnf7po\",\n \"upload\": \"https://my.scalr.io/api/iacp/v3/blobs/eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwicDJjIjo4MTkyLCJwMnMiOiJwUTlTSG5OM3VBUjdLXzhXVm1EWktBIn0.TDSfnHHTUrxUlflx_fAl8zKmXyT4mzviGiShvGncIgawrL_eEs3S0n1sDfUVXi2a_28XTyl4zuDI9QSazXK51AFM2Z_SZBhC.VaoUUTUKWbga_7vvCQasrQ.FzqF-Sxsc1ac3uVOiyX1L9X4wU8Xuh0qFdqwKoM5MfexRuz8DJU1xUVPO9_5vqYjr102R4g-hE9yt0hAxw5P-ziyodILLWRYJZzr_IGpSosKzHr0qsda6izQbihBUAyW.RY9XyG7pDCkPTpdeGUJhm7Hkzt6Z0oEwmxeDu-2HNQA\"\n },\n \"relationships\": {\n \"workspace\": {\n \"data\": {\n \"id\": \"ws-spturhj1dckd8so\",\n \"type\": \"workspaces\"\n }\n }\n },\n \"type\": \"configuration-versions\"\n },\n \"included\": null,\n \"meta\": null\n}" }, "1-vcs": { "summary": "Configuration version for a VCS workspace is created", "description": "Once a configuration version is created, Scalr will start upload from a VCS repository in a background.", "value": "{\n \"data\": {\n \"attributes\": {\n \"auto-queue-runs\": true,\n \"created-at\": \"2020-11-05T03:07:07Z\",\n \"error-message\": null,\n \"inputs\": null,\n \"source\": \"github\",\n \"is-dry\": false,\n \"status\": \"pending\",\n \"status-timestamps\": {\n \"pending-at\": \"2020-11-05T03:07:07Z\"\n },\n },\n \"id\": \"cv-t5uvn2j0fcnf7po\",\n \"links\": {\n \"self\": \"https://my.scalr.io/api/iacp/v3/configuration-versions/cv-t5uvn2j0fcnf7po\",\n },\n \"relationships\": {\n \"workspace\": {\n \"data\": {\n \"id\": \"ws-spturhj1dckd8so\",\n \"type\": \"workspaces\"\n }\n }\n },\n \"type\": \"configuration-versions\"\n },\n \"included\": null,\n \"meta\": null\n}" } }, "schema": { "$ref": "#/components/schemas/ConfigurationVersionDocument" } } }, "description": "The request was successful." }, "404": { "description": "Workspace not found or user unauthorized to perform action." }, "409": { "description": "Conflict; check the error object for more information." }, "422": { "description": "Malformed request body (missing attributes, wrong types, etc.)." }, "4XX": { "description": "Client error." }, "5XX": { "description": "Server error." } }, "summary": "Create a Configuration Version", "tags": [ "configuration-versions" ], "x-resource": "ConfigurationVersion", "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 Configuration Versions](https://docs.scalr.io/scalr/reference/get_configuration_versions.md) * [Get a Configuration Version](https://docs.scalr.io/scalr/reference/get_configuration_version.md) * [Download Configuration Version](https://docs.scalr.io/scalr/reference/download_configuration_version.md)