Skip to main content

Governance

Every endpoint on this page needs a Keycloak access token with the admin platform role, except the detector manifest, which any signed-in user can read. See Policy for how the rules work.

List custom policies​

GET/governance/custom-policies

Response fields​

policiesarrayoptional
Each policy's id, name, description, effect, action, conditions, enabled, created_at, created_by, updated_at and updated_by.
revisionstringoptional
A hash of the enabled rules. It changes when what OPA should decide with changes.
catalogobjectoptional
Every action you can write a rule for, the fields it carries and the effects it allows.
approval_fieldsarrayoptional
The fields an approval rule can test.
GET/governance/custom-policies/status

Whether OPA has loaded the current rules. Returns api_revision, opa_revision and in_sync.

Create a custom policy​

POST/governance/custom-policies

Saves a rule. OPA loads it on its next poll. Recorded in the audit log as custom_policy.create.

Body​

namestringrequired
Up to 120 characters.
effectstringrequired
deny, require_approval or allow. require_approval and allow work only with call_tool.
actionstringrequired
call_tool, chat, embed, transcribe, speak, deploy_model or verify_model_integrity.
conditionsobjectoptional
Field names mapped to lists of allowed values. Every condition must match. Empty means every request for the action. An allow rule must have a project_id condition.
descriptionstringoptional
Who asked for it and what it protects. Up to 2,000 characters.
enabledbooleanoptional
Default true. A disabled rule is saved but not sent to OPA.
PUT/governance/custom-policies/{policy_id}

Replaces a rule. Same body. Recorded as custom_policy.update.

DELETE/governance/custom-policies/{policy_id}

Deletes a rule. Recorded as custom_policy.delete.

Responses​

201
Created.
404
No such policy.
422
The rule would never match or is not allowed, for example a condition on a field the action does not send. detail says why.

Test a request​

POST/governance/custom-policies/test

Asks OPA what it would decide for a request you describe. Nothing is written to the audit log.

Body​

actionstringrequired
The action.
resourceobjectoptional
The request's fields, such as tool_name and project_id.

Response fields​

allowbooleanoptional
OPA's decision.
requires_approvalboolean or nulloptional
For call_tool, whether the call would wait for a person. null for other actions.
matched_policy_idsarrayoptional
The custom policies that matched.
opa_revisionstring or nulloptional
The custom rule set OPA decided with.

Export and import​

GET/governance/custom-policies/export

Every custom policy, in the file format the import accepts. Ids are kept, so re-importing an edited export updates rules instead of duplicating them.

POST/governance/custom-policies/import

Replaces the whole set with the file's policies. A policy missing from the file is deleted. Every policy is checked first, so a file with one bad entry changes nothing. Recorded as custom_policy.import.

Query parameters​

dry_runbooleanoptional
true to see what would change without changing it.

Body​

formatstringrequired
vois-orchestrate.custom-policies/v1.
policiesarrayrequired
Up to 500 policies, each with the fields of a create request and an optional id.

Response fields​

createdarrayoptional
Names of policies that are new.
updatedarrayoptional
Names of policies that changed.
deletedarrayoptional
Names of policies that are not in the file.
dry_runbooleanoptional
Whether anything was changed.

Read the rules in force​

GET/governance/policies

The policy data OPA is deciding with, read from OPA. data has the baseline's write_tools and write_tool_allowed_projects. custom_policies_revision is the custom rule set OPA has loaded, or null if none.

GET/governance/guardrails

The PII guardrail configuration the Model Gateway is enforcing. Same response as the gateway's GET /guardrails/config.

GET/guardrails/detector

What the PII detector checks and does not check, for this release. Any signed-in user. Pass detector with the value from a scan report, such as vois-bundled-ruleset@1.0.0. If it does not match this release's detector, the response is 409.

Responses​

200
The rules.
502
OPA or the Model Gateway could not be reached or refused the read. detail says which.

List blocked actions​

GET/governance/blocked

Everything the platform refused, newest first, read from the audit log, with a reason for each.

Query parameters​

limitintegeroptional
From 1 to 200. Default 50.
offsetintegeroptional
Default 0.

Response fields​

items[].sequenceintegeroptional
The audit event's sequence number.
items[].created_atstringoptional
When it happened.
items[].actorstringoptional
Who tried.
items[].actionstringoptional
What was refused.
items[].targetstringoptional
What it was aimed at, such as a model or a tool.
items[].sourcestringoptional
What refused it: policy, guardrail or approval.
items[].reasonstringoptional
Why, in a sentence.
has_morebooleanoptional
Whether there are older items.

List pending approvals​

GET/governance/pending-approvals

Tool calls in every project that are waiting for a person, found in the audit log and confirmed against the runs.

Query parameters​

daysintegeroptional
How far back to look, from 1 to 90. Default 7.

Response fields​

approvals[]objectoptional
Each request's workflow_id, approval_id, tool_name, step, project_id, requested_by, requested_at, expires_at and status. status is pending, or unconfirmed if the run could not be asked.
truncatedbooleanoptional
true if there were too many requests to read them all. truncated_reason explains.
countsobjectoptional
How many were found, pending and unconfirmed.

To decide one, use POST /workflow-runs/{workflow_id}/approvals/{approval_id}.

Guardrail profiles​

See Guardrail profiles for the profile document and how a profile is chosen.

Method and pathWhoWhat it does
GET /guardrails/profiles?project_id=any signed-in userThe install-wide profiles, and the project's own.
POST /guardrails/profilesproject admin; platform admin for an install-wide profileBody: project_id (none for install-wide), name, description, is_default, config.
PATCH /guardrails/profiles/{profile_id}the sameChange a profile.
DELETE /guardrails/profiles/{profile_id}the sameDelete a profile. 409 while it is assigned or an organization's default.
GET /projects/{project_id}/agents/{agent_name}/guardrailsviewerThe agent's assignments and the profile that is in effect.
PUT /projects/{project_id}/agents/{agent_name}/guardrailsproject admin{"profile_id", "version_id"}: assign a profile to the agent, or to one version.
GET /guardrails/detectorsany signed-in userThe PII and prompt-injection detectors this install runs, their versions, packs and rules.

Model access​

See Model access.

Method and pathWhoWhat it does
GET /model-accessany signed-in userEvery model access policy.
GET /model-access/{model}any signed-in userOne policy, by catalog id or model name.
PUT /model-access/{model}platform admin{"restricted": true, "allowed_projects": ["support", "billing"]}. Takes effect at the Model Gateway within about 15 seconds.
GET /projects/{project_id}/model-accessviewerEvery model, and whether this project may use it.
Was this page helpful?