Policy evaluations API reference

Policy evaluations are run within the HCP Terraform agents in HCP Terraform's infrastructure. Policy evaluations do not have access to cost estimation data. This set of APIs provides endpoints to list and get policy evaluations and policy outcomes.

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.

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",
            "policy-tool-version": "0.44.0",
            "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

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

The following example requests demonstrate how to call the policy-set-outcomes endpoint using cuRL.

All Policy Outcomes

The following example call returns all policy set 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

The following example call filters the response so that it only contains failed outcomes and errors.

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

The following example response shows that the policyVCS policy failed.

{
   "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
            },
            "policy-tool-version": "0.54.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. Refer to List the Policy Outcomes for reference information about finding 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

The following example request gets the outcomes for the psout-cu8E9a97LBepZZXd policy set.

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

The following example response shows that the policyVCS policy failed.

{
   "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
         },
         "policy-tool-version": "0.54.0"
      },
      "relationships":{
         "policy-evaluation":{
            "data":{
               "id":"poleval-8Jj9Hfoz892D9WMX",
               "type":"policy-evaluations"
            }
         }
      }
   }
}