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 the terraform.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.