HashiDays One conference. Three cities. Find a city near you
Terraform
Terraform Home

You are viewing documentation for version v202212-2. View latest version.

Policy Checks API

Note: Sentinel and OPA policies are available in the Terraform Cloud Team & Governance tier, and OPA policies are in beta. OPA policies are not available in Terraform Enterprise.

List Policy Checks

This endpoint lists the policy checks in a run.

Note: The sentinel hash in the result attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk.

GET /runs/:run_id/policy-checks

ParameterDescription
run_idThe ID of the run to list policy checks for.

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results.

ParameterDescription
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 policy checks per page.

Sample Request

curl \  --header "Authorization: Bearer $TOKEN" \  https://app.terraform.io/api/v2/runs/run-CZcmD7eagjhyXavN/policy-checks

Sample Response

{  "data": [    {      "id": "polchk-9VYRc9bpfJEsnwum",      "type": "policy-checks",      "attributes": {        "result": {          "result": false,          "passed": 0,          "total-failed": 1,          "hard-failed": 0,          "soft-failed": 1,          "advisory-failed": 0,          "duration-ms": 0,          "sentinel": {...}        },        "scope": "organization",        "status": "soft_failed",        "status-timestamps": {          "queued-at": "2017-11-29T20:02:17+00:00",          "soft-failed-at": "2017-11-29T20:02:20+00:00"        },        "actions": {          "is-overridable": true        },        "permissions": {          "can-override": false        }      },      "relationships": {        "run": {          "data": {            "id": "run-veDoQbv6xh6TbnJD",            "type": "runs"          }        }      },      "links": {        "output": "/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum/output"      }    }  ]}

Show Policy Check

This endpoint gets information about a specific policy check ID. Policy check IDs can appear in audit logs.

Note: The sentinel hash in the result attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk.

GET /policy-checks/:id

ParameterDescription
idThe ID of the policy check to show.

Sample Request

curl \  --header "Authorization: Bearer $TOKEN" \  https://app.terraform.io/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum

Sample Response

{  "data": {    "id": "polchk-9VYRc9bpfJEsnwum",    "type": "policy-checks",    "attributes": {      "result": {        "result": false,        "passed": 0,        "total-failed": 1,        "hard-failed": 0,        "soft-failed": 1,        "advisory-failed": 0,        "duration-ms": 0,        "sentinel": {...}      },      "scope": "organization",      "status": "soft_failed",      "status-timestamps": {        "queued-at": "2017-11-29T20:02:17+00:00",        "soft-failed-at": "2017-11-29T20:02:20+00:00"      },      "actions": {        "is-overridable": true      },      "permissions": {        "can-override": false      }    },    "relationships": {      "run": {        "data": {          "id": "run-veDoQbv6xh6TbnJD",          "type": "runs"        }      }    },    "links": {      "output": "/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum/output"    }  }}

Override Policy

This endpoint overrides a soft-mandatory or warning policy.

Note: The sentinel hash in the result attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk.

POST /policy-checks/:id/actions/override

ParameterDescription
idThe ID of the policy check to override.

Sample Request

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  https://app.terraform.io/api/v2/policy-checks/polchk-EasPB4Srx5NAiWAU/actions/override

Sample Response

{  "data": {    "id": "polchk-EasPB4Srx5NAiWAU",    "type": "policy-checks",    "attributes": {      "result": {        "result": false,        "passed": 0,        "total-failed": 1,        "hard-failed": 0,        "soft-failed": 1,        "advisory-failed": 0,        "duration-ms": 0,        "sentinel": {...}      },      "scope": "organization",      "status": "overridden",      "status-timestamps": {        "queued-at": "2017-11-29T20:13:37+00:00",        "soft-failed-at": "2017-11-29T20:13:40+00:00",        "overridden-at": "2017-11-29T20:14:11+00:00"      },      "actions": {        "is-overridable": true      },      "permissions": {        "can-override": false      }    },    "links": {      "output": "/api/v2/policy-checks/polchk-EasPB4Srx5NAiWAU/output"    }  }}

Available Related Resources

The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:

Resource NameDescription
runThe run this policy check belongs to.
run.workspaceThe associated workspace of the run.