Policy Checks - API Docs - Terraform Enterprise | Terraform

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

Parameter	Description
`run_id`	The 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.

Parameter	Description
`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.

GET /policy-checks/:id

Parameter	Description
`id`	The 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.

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

Parameter	Description
`id`	The 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"
    }
  }
}

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

Resource Name	Description
`run`	The run this policy check belongs to.
`run.workspace`	The associated workspace of the run.

List Policy Evaluations in the Task Stage

Each run passes through several stages of action (pending, plan, policy check, apply, and completion), and shows the progress through those stages as run states. This endpoint allows you to list policy evaluations that are part of the task stage.

This endpoint is only available for OPA policies.

GET /task-stages/:task_stage_id/policy-evaluations

Parameter	Description
`:task_stage_id`	The task stage ID to get.

Status	Response	Reason
200	JSON API document	Success
404	JSON API error object	Task stage not found

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling does not automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 20 agent pools per page.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi/policy-evaluations

Sample Response

{
   "data":[
      {
         "id":"poleval-8Jj9Hfoz892D9WMX",
         "type":"policy-evaluations",
         "attributes":{
            "status":"passed",
            "policy-kind":"opa",
            "result-count": {
              "advisory-failed":0,
              "errored":0,
              "mandatory-failed":0,
              "passed":1
            }
            "status-timestamps":{
               "passed-at":"2022-09-16T01:40:30+00:00",
               "queued-at":"2022-09-16T01:40:04+00:00",
               "running-at":"2022-09-16T01:40:08+00:00"
            },
            "created-at":"2022-09-16T01:39:07.782Z",
            "updated-at":"2022-09-16T01:40:30.010Z"
         },
         "relationships":{
            "policy-attachable":{
               "data":{
                  "id":"ts-yxskot8Gz5yHa38W",
                  "type":"task-stages"
               }
            },
            "policy-set-outcomes":{
               "links":{
                  "related":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes"
               }
            }
         },
         "links":{
            "self":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX"
         }
      }
   ]
}

List Policy Outcomes

This endpoint is only available for OPA policies.

GET /policy-evaluations/:policy_evaluation_id/policy-set-outcomes

Parameter	Description
`:policy_evaluation_id`	The ID of the policy evaluation the outcome belongs to get

This endpoint allows you to list policy set outcomes that are part of the policy evaluation.

Status	Response	Reason
200	JSON API document	Success
404	JSON API error object	Policy evaluation not found

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling does not automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 20 policy sets per page.
`filter[n][status]`	Optional. If omitted, the endpoint returns all policies regardless of status. Must be either "passed", "failed", or "errored".
`filter[n][enforcementLevel]`	Optional. Only used if paired with a non-errored status filter. Must be either "advisory" or "mandatory."

Note: You can use filter[n] to combine combinations of statuses and enforcement levels. Policy outcomes with an errored status do not have an enforcement level.

Sample Request

All Policy Outcomes

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes

Failed and Errored Policy Outcomes

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?filter[0][status]=errored&filter[1][status]=failed&filter[1][enforcementLevel]=mandatory

Sample Response

{
   "data":[
      {
         "id":"psout-cu8E9a97LBepZZXd",
         "type":"policy-set-outcomes",
         "attributes":{
            "outcomes":[
               {
                  "enforcement_level":"advisory",
                  "query":"data.terraform.main.main",
                  "status":"failed",
                  "policy_name":"policyVCS",
                  "description":""
               }
            ],
            "error":"",
            "overridable":true,
            "policy-set-name":"opa-policies-vcs",
            "policy-set-description":null,
            "result-count":{
               "advisory-failed":1,
               "errored":0,
               "mandatory-failed":0,
               "passed":0
            }
         },
         "relationships":{
            "policy-evaluation":{
               "data":{
                  "id":"poleval-8Jj9Hfoz892D9WMX",
                  "type":"policy-evaluations"
               }
            }
         }
      }
   ],
   "links":{
      "self":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
      "first":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
      "prev":null,
      "next":null,
      "last":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20"
   },
   "meta":{
      "pagination":{
         "current-page":1,
         "page-size":20,
         "prev-page":null,
         "next-page":null,
         "total-pages":1,
         "total-count":1
      }
   }
}

Show a Policy Outcome

GET /policy-set-outcomes/:policy_set_outcome_id

Parameter	Description
`:policy_set_outcome_id`	The ID of the policy outcome to show. Use the "List the Policy Outcomes of the Policy Evaluation" endpoint to find IDs.

Status	Response	Reason
200	JSON API document	The request was successful
404	JSON API error object	Policy set outcome not found or user unauthorized to perform action

Sample Request

curl --request GET \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/policy-set-outcomes/psout-cu8E9a97LBepZZXd

Sample Response

{
   "data":{
      "id":"psout-cu8E9a97LBepZZXd",
      "type":"policy-set-outcomes",
      "attributes":{
         "outcomes":[
            {
               "enforcement_level":"advisory",
               "query":"data.terraform.main.main",
               "status":"failed",
               "policy_name":"policyVCS",
               "description":""
            }
         ],
         "error":"",
         "overridable":true,
         "policy-set-name":"opa-policies-vcs",
         "policy-set-description":null,
         "result-count":{
            "advisory-failed":1,
            "errored":0,
            "mandatory-failed":0,
            "passed":0
         }
      },
      "relationships":{
         "policy-evaluation":{
            "data":{
               "id":"poleval-8Jj9Hfoz892D9WMX",
               "type":"policy-evaluations"
            }
         }
      }
   }
}

Policy Checks API

List Policy Checks

Query Parameters

Sample Request

Sample Response

Show Policy Check

Sample Request

Sample Response

Override Policy

Sample Request

Sample Response

Available Related Resources

List Policy Evaluations in the Task Stage

Query Parameters

Sample Request

Sample Response

List Policy Outcomes

Query Parameters

Sample Request

All Policy Outcomes

Failed and Errored Policy Outcomes

Sample Response

Show a Policy Outcome

Sample Request

Sample Response