Applies API reference

An apply represents the results of applying a Terraform Run's execution plan.

Attributes

Apply States

You'll find the apply state in data.attributes.status, as one of the following values.

State	Description
`pending`	The initial status of a apply once it has been created.
`managed_queued`/`queued`	The apply has been queued, awaiting backend service capacity to run terraform.
`running`	The apply is running.
`errored`	The apply has errored. This is a final state.
`canceled`	The apply has been canceled. This is a final state.
`finished`	The apply has completed successfully. This is a final state.
`unreachable`	The apply will not run. This is a final state.

Show an apply

GET /applies/:id

Parameter	Description
`id`	The ID of the apply to show.

There is no endpoint to list applies. You can find the ID for an apply in the relationships.apply property of a run object.

Status	Response	Reason
200	JSON API document (`type: "applies"`)	The request was successful
404	JSON API error object	Apply not found, or user unauthorized to perform action

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v

Sample Response

{
  "data": {
    "id": "apply-47MBvjwzBG8YKc2v",
    "type": "applies",
    "attributes": {
      "execution-details": {
        "mode": "remote",
      },
      "status": "finished",
      "status-timestamps": {
        "queued-at": "2018-10-17T18:58:27+00:00",
        "started-at": "2018-10-17T18:58:29+00:00",
        "finished-at": "2018-10-17T18:58:37+00:00"
      },
      "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg",
      "resource-additions": 1,
      "resource-changes": 0,
      "resource-destructions": 0,
      "resource-imports": 0
    },
    "relationships": {
      "state-versions": {
        "data": [
          {
            "id": "sv-TpnsuD3iewwsfeRD",
            "type": "state-versions"
          },
          {
            "id": "sv-Fu1n6a3TgJ1Typq9",
            "type": "state-versions"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v"
    }
  }
}

Using HCP Terraform agents

HCP Terraform agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. When a workspace is set to use the agent execution mode, the apply response will include additional details about the agent pool and agent used.

{
  "data": {
    "id": "apply-47MBvjwzBG8YKc2v",
    "type": "applies",
    "attributes": {
      "execution-details": {
        "agent-id": "agent-S1Y7tcKxXPJDQAvq",
        "agent-name": "agent_01",
        "agent-pool-id": "apool-Zigq2VGreKq7nwph",
        "agent-pool-name": "first-pool",
        "mode": "agent",
      },
      "status": "finished",
      "status-timestamps": {
        "queued-at": "2018-10-17T18:58:27+00:00",
        "started-at": "2018-10-17T18:58:29+00:00",
        "finished-at": "2018-10-17T18:58:37+00:00"
      },
      "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg",
      "resource-additions": 1,
      "resource-changes": 0,
      "resource-destructions": 0,
      "resource-imports": 0
    },
    "relationships": {
      "state-versions": {
        "data": [
          {
            "id": "sv-TpnsuD3iewwsfeRD",
            "type": "state-versions"
          },
          {
            "id": "sv-Fu1n6a3TgJ1Typq9",
            "type": "state-versions"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v"
    }
  }
}

Recover a failed state upload after applying

GET /applies/:id/errored-state

Parameter	Description
`id`	The ID of the apply to recover state for.

It is possible that during the course of a Run, Terraform may fail to upload a state file. This can happen for a variety of reasons, but should be an exceptionally rare occurrence. HCP Terraform agent versions greater than 1.12.0 include a fallback mechanism which attempts to upload the state directly to HCP Terraform's backend storage system in these cases. This endpoint then makes the raw data from these failed uploads available to users who are authorized to read the state contents.

Status	Response	Reason
307	HTTP temporary redirect to state storage URL	Errored state available and user is authorized to read it
404	JSON API error object	Apply not found, errored state not uploaded, or user unauthorized to perform action

When a 307 redirect is returned, the storage URL to the raw state file will be present in the Location header of the response. The URL in the Location header will expire after one minute. It is recommended for the API client to follow the redirect immediately. Each successful request to the errored-state endpoint will generate a new, unique storage URL with the same one minute expiration window.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v/errored-state

Sample Response

HTTP/1.1 307 Temporary Redirect
Content-Length: 22
Content-Type: text/plain
Location: https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg
 
307 Temporary Redirect