State Versions¶
The StateVersion resource¶
A State version is the version of a state file associated with a workspace.
Key path
Description
type* (string)
Available values:state-versions
id (string)
attributes.created-at (string)
The resource creation timestamp.
attributes.force (boolean)
attributes.lineage (string)
Lineage of the state version. Should match the lineage extracted from the
terraform.tfstate
.attributes.md5 (string)
The MD5 hash of the terraform.tfstate.
attributes.modules (object)
The list of modules.
attributes.outputs (array)
The list of output values.
attributes.providers (object)
The list of providers.
attributes.resources (array)
The list of resources.
attributes.serial (integer)
The serial of the state version which must match the
serial
value from theterraform.tfstate
.attributes.size (integer)
Size of the
terraform.tfstate
in bytes.attributes.state (string)
Base64 encoded
terraform.tfstate
relationships.next-state-version (object)
Next state version for the workspace to which state version is associated.
relationships.next-state-version.data.type* (string)
Available values:state-versions
relationships.next-state-version.data.id* (string)
relationships.previous-state-version (object)
Previous state version for the workspace to which state version is associated.
relationships.previous-state-version.data.type* (string)
Available values:state-versions
relationships.previous-state-version.data.id* (string)
relationships.run (object)
The the optional run associated with the state version.
relationships.run.data.type* (string)
Available values:runs
relationships.run.data.id* (string)
relationships.workspace (object)
The workspace, this state version belongs to.
relationships.workspace.data.type* (string)
Available values:workspaces
relationships.workspace.data.id* (string)
links.download (string)
The URL to download the
terraform.tfstate
.links.self (string)
List Workspace’s State Versions¶
-
GET
/api/iacp/v3/state-versions
¶ - Query Parameters
page[number] (string) – Page number
page[size] (string) – Page size
include (array) – The comma-separated list of relationship paths. (Available values:
run
)filter[workspace] (string) – (Required)
sort (array) – The comma-separated list of attributes. (Available values:
created-at
)query (string) – Query string
Example Request:
GET /api/iacp/v3/state-versions?filter%5Bworkspace%5D=string HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Success
404 Not Found – Workspace not found, or or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Get a State Version¶
-
GET
/api/iacp/v3/state-versions/{state_version}
¶ Show details of a specific state version.
- Parameters
state_version (string) – The ID of the state version.
- Query Parameters
include (array) – The comma-separated list of relationship paths. (Available values:
run
)
Example Request:
GET /api/iacp/v3/state-versions/{state_version} HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Success.
404 Not Found – State version not found, or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Download State Version¶
-
GET
/api/iacp/v3/state-versions/{state_version}/download
¶ Download the
terraform.tfstate
- Parameters
state_version (string) – The ID of the state version.
Example Request:
GET /api/iacp/v3/state-versions/{state_version}/download HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK –
302 Found – The location of the temporary download link.
404 Not Found – State version not found or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.
Get Workspace’s Current State Version¶
-
GET
/api/iacp/v3/workspaces/{workspace}/current-state-version
¶ Fetch the current state version for the given workspace.
This state version will be the input state when running terraform operations.
- Parameters
workspace (string) – The ID of the workspace.
- Query Parameters
include (array) – The comma-separated list of relationship paths. (Available values:
run
)
Example Request:
GET /api/iacp/v3/workspaces/{workspace}/current-state-version HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Successfully returned current state version for the given workspace.
404 Not Found – Workspace not found, workspace does not have a current state version, or user unauthorized to perform action.
4XX – Client error.
5XX – Server error.