Health assessment results API reference

An Assessment Result is the summary record of an instance of health assessment. HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Refer to Health for more details.

Show Assessment Result

Any user with read access to a workspace can retrieve assessment results for the workspace.

GET api/v2/assessment-results/:assessment_result_id

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm

Sample Response

{
  "id": "asmtres-UG5rE9L1373hMYMA",
  "type": "assessment-results",
  "data": {
    "attributes": {
      "drifted": true,
      "succeeded": true,
      "error-msg": null,
      "created-at": "2022-07-02T22:29:58+00:00",
    },
    "links": {
      "self": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/"
      "json-output": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/json-output"
      "json-schema": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/json-schema"
      "log-output": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/log-output"
    }
  }
}

Retrieve the JSON output from the assessment execution

The following endpoints retrieve files documenting the plan, schema, and logged runtime associated with the specified assessment result. They provide complete context for an assessment result. The responses do not adhere to JSON API spec.

You cannot access these endpoints with organization tokens. You must access them with a user token or team token that has admin level access to the workspace. Refer to Permissions for details.

JSON Plan

The following endpoint returns the JSON plan output associated with the assessment result.

GET api/v2/assessment-results/:assessment_result_id/json-output

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm/json-output

JSON Schema file

The following endpoint returns the JSON provider schema associated with the assessment result.

GET api/v2/assessment-results/:assessment_result_id/json-schema

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm/json-schema

JSON Log Output

The following endpoint returns Terraform JSON log output.

GET api/v2/assessment-results/assessment_result_id/log-output

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm/log-output

Soft delete assessment backing data

POST /assessments/:id/actions/soft-delete-backing-data

This endpoint directs Terraform Enterprise to soft delete the backing files associated with an assessment operation. Soft deleting marks the assessment for garbage collection. Terraform permanently deletes assessments marked for soft deletion after a set number of days unless you restore the assessment. Once an assessment is soft deleted, any attempts to read the assessment's backing data fail.

This endpoint can only soft delete assessments that meet the following criteria:

• The associated run is in a terminal state and is not in an assessing state.
• The associated run is not the current run in the workspace.

Otherwise, the endpoint returns a 409 Conflict.

Request body

No request body.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://<TFE_HOSTNAME>/api/v2/assessments/asmtres-cHh5777xm/actions/soft-delete-backing-data

Restore assessment backing data

POST /assessments/:id/actions/restore-backing-data

This endpoint directs Terraform Enterprise to restore the backing files associated with a soft-deleted assessment. This endpoint can only restore assessments that are not in a backing_data_permanently_deleted state. Otherwise, the endpoint returns an error.

Request body

No request body.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://<TFE_HOSTNAME>/api/v2/assessments/asmtres-cHh5777xm/actions/restore-backing-data

Permanently delete assessment backing data

POST /assessments/:id/actions/permanently-delete-backing-data

This endpoint directs Terraform Enterprise to immediately and permanently delete the backing files associated with a soft-deleted assessment. This endpoint can only permanently delete assessments that are in a backing_data_soft_deleted state. Otherwise, the endpoint returns a 409 Conflict.

Request body

No request body.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://<TFE_HOSTNAME>/api/v2/assessments/asmtres-cHh5777xm/actions/permanently-delete-backing-data