Policy insights

Use these endpoints to manage the templates and reports of Policy insights, and to run them against an environment.

All requests require the X-Project-Id header. Read access requires the Project viewer role and changes require the Project editor role. Read Permissions for details. Because the rule is based on the HTTP method, running a report or a query, which uses POST, also requires the Project editor role.

Policy insights requests are applied immediately and are not staged in My workspace.

Environments

Method	Path	Description
GET	/api/insights/endpoints	List the environments available to the project.

An environment is a CAQ endpoint that your administrator configured for the project. Read Remote endpoint management. Each entry has the name, description, and url of the environment. Credentials are never returned.

The name is the value to use as targetEndpoint in reports and runs. A request that names an environment that is not configured for the project is rejected with 400 and the ENDPOINT_NOT_FOUND error code.

Pagination

The lists of reports and templates are paginated with the standard page (starting at 0), size, and sort query parameters. For example, ?page=0&size=20&sort=name,asc. The response contains the items in content, with totalElements, totalPages, number, and size.

Templates

Method	Path	Description
GET	/api/insights/templates	List the active templates.
GET	/api/insights/templates/{name}	Get the active template with this name.
GET	/api/insights/templates/id/{uid}	Get a template version by ID, including older versions.
POST	/api/insights/templates	Create a template.
PATCH	/api/insights/templates/{name}	Update a template.
DELETE	/api/insights/templates/{name}	Delete a template.

Creating a template needs a name (1 to 255 characters), a template, and a domainFqn, which is the source of the attributes used in the template. It is the project ID to use the project's attributes, or the identifier of a domain. A description is optional and can have up to 256 characters.

{
  "name": "Who can view invoices",
  "description": "Lists the subjects that can view invoices",
  "domainFqn": "e00f12c8-8f3a-40ac-81a7-5a762abc7288",
  "template": "..."
}

An update creates a new version of the template with a new uid and retires the previous one. template is required in an update, while name, description, and domainFqn keep their current values if omitted. A delete retires the template, and its name can be reused.

A template's uid identifies one version of it. A report keeps the originalTemplateId of the template version it was created from.

Reports

Method	Path	Description
GET	/api/insights/reports	List the active reports.
GET	/api/insights/reports/{id}	Get a report by ID, with its runs.
GET	/api/insights/reports/name/{name}	Get the active report with this name, with its runs.
POST	/api/insights/reports	Create a report.
PUT	/api/insights/reports/{name}	Update a report.
DELETE	/api/insights/reports/{name}	Delete a report.
POST	/api/insights/reports/{id}/run	Run a report.

A report is created with:

Field	Required	Description
name	Yes	1 to 255 characters. Unique among the active reports.
description	No	Up to 256 characters.
targetEndpoint	Yes	The name of an environment.
insightRequests	Yes	At least one insight request.
originalTemplateId	No	The ID of the template it was created from.
templateText	No	A copy of the template text.

PUT replaces the report's details in place, and keeps its ID. A delete retires the report, and its name can be reused.

Insight requests

An insight request describes one authorization query:

{
  "providedAttributes": [
    { "attribute": "Action.actionId", "values": ["view"] }
  ],
  "mockedAttributes": [],
  "pdpDecisionSet": ["PERMIT"]
}

Field	Description
providedAttributes	The attribute values the query is evaluated with. Each entry has an attribute and a list of values.
mockedAttributes	Optional. Attributes that are simulated rather than retrieved from external sources.
pdpDecisionSet	The decisions to look for, for example ["PERMIT"].

Runs

Method	Path	Description
POST	/api/insights/reports/{id}/run	Run a saved report.
POST	/api/insights/runs	Run queries without a saved report.
GET	/api/insights/runs/{id}	Get a saved run.
DELETE	/api/insights/runs/{id}	Delete a saved run.

• To run a saved report, send an empty request or a body with insightRequests or targetEndpoint to override the report's values for this run.
• To run queries directly, send a name, a targetEndpoint, and the insightRequests.
• Results are only saved if you add ?save=true. A saved run needs a name, or the request fails with RUN_NAME_REQUIRED. Saved runs are returned with their report.
• There is no endpoint that lists runs. Read them from the report.

The response is 200 with the following structure:

{
  "runId": "c9f0a7d2-3b1e-4f58-9a6c-5d2e8b7a1c40",
  "reportId": "1d2e3f4a-5b6c-4d7e-8f90-a1b2c3d4e5f6",
  "name": "Invoice access",
  "targetEndpoint": "caq-dev",
  "targetInstanceIdentity": "caq-instance-1",
  "targetDomainId": "7e0c4a52-91d3-4b6f-8f0e-2c5d7a1b9e33",
  "status": "SUCCESS",
  "results": [
    { "status": "SUCCESS", "data": { } }
  ],
  "saved": true,
  "runBy": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "runAt": "2026-10-13T09:15:30Z"
}

Field	Description
status	SUCCESS if every query succeeded, ERROR if all failed, and PARTIAL otherwise.
results	One entry per insight request, with a status of SUCCESS and the response in data, or ERROR and an errorMessage.
runId	The ID of the saved run. null if the run was not saved.
reportId	The ID of the report. null if the run does not belong to a report.
targetInstanceIdentity, targetDomainId	The authorization engine instance and its domain, as reported by the environment. They are UNKNOWN if they could not be retrieved.

note

The HTTP status of a run is 200 even when some or all queries fail. Check status and each entry in results.

Errors

Status	errorCode	Cause
400	ENDPOINT_NOT_FOUND	The targetEndpoint is not an environment available to the project.
400	RUN_NAME_REQUIRED	A run was saved without a name.
404	TEMPLATE_NOT_FOUND, ACTIVE_TEMPLATE_NOT_FOUND	The template does not exist.
404	REPORT_NOT_FOUND, ACTIVE_REPORT_NOT_FOUND	The report does not exist.
404	RUN_NOT_FOUND	The run does not exist.
409	ACTIVE_TEMPLATE_ALREADY_EXISTS, ACTIVE_REPORT_ALREADY_EXISTS	An active template or report with this name already exists.