Skip to main content
Use https://api.kontext.security/api/v1 as the base URL. Kontext requires an owner or admin caller with the route’s scope. See API overview to get a token. To let an agent manage policies, create a service account or connect the agent under Settings → Agent access with the Policy author preset. It grants management:policy:read, management:policy:write and management:logs:read.

​
Routes

​
Change one policy

The dashboard and kontext-admin agent skill use POST /policy/actions for the actions on Policies. First read the deployment and its response headers:
Copy the complete ETag header value, including its double quotes, into DEPLOYMENT_ETAG. Send it in If-Match for the action:
Set scopes to a list of { "endpointId": "<endpoint ID>", "agentId": "openai-codex" } objects. Omit endpointId to cover every endpoint or agentId to cover both agents. You can scope custom Cedar policies only if their IDs start with custom:. Kontext saves actions in paused workspaces without resuming them. The response includes the updated deployment, a plain-language message, changedPolicyIds, validation, and a new ETag for your next action. A missing If-Match returns 428. A stale value returns 412. For 412, read the deployment again and review the intervening change. Rebuild the intended action against the current deployment, then retry with its ETag. Adding an existing policy or enforcing one already in Enforced returns 409.

​
Read what policies do

Use GET /policy/blocked?days=7 to read each enforced policy’s blocked count and up to 20 of its newest blocked calls. Set days to 7, 14 or 30. Kontext sets truncated to true for windows with more than 2,000 Deny decisions. Counts then cover only the newest 2,000. Send enforcingVersionId, observingVersionId and days to POST /policy/replay. Replay checks the newest 2,000 recorded calls in the window and returns how many each policy would newly block or allow. The needsCapture count covers calls that need full tool input for assessment. Each workspace runs one replay at a time. The API returns 409 when too many are waiting.

​
Save a policy set

Use these routes to manage the complete Cedar source.

The API rejects a stale If-Match with 412 to preserve the other edit.

Send the complete source to PUT /policy as {"policyText": "..."}, up to 1,048,576 UTF-8 bytes. Use If-Match with the ETag from your last GET /policy, or If-None-Match: * for the first set. A missing precondition returns 428. A stale precondition returns 412. The response body includes validation results and diagnostics. Send the same body to POST /policy/validations to validate without saving. Use the optional origin field to name the action in History, for example {"kind": "enforced", "subject": "Block GitHub force pushes"}. Set kind to added, enforced, stopped, edited or deleted. Set subject to at most 200 characters. Without origin, History uses a title that describes the changes. Saving creates a version unless an API save without origin reuses identical source. Endpoints use it only after you select it in the deployment.

​
Replace the deployment

Use PUT /policy/deployment to set the mode for the whole workspace. With "rolloutMode": "enforce", Kontext blocks calls with every policy in policyVersionId. Use POST /policy/actions to change one policy.
Send the deployment ETag in If-Match and this body:
Set rolloutMode to observe, enforce or disabled. Kontext pauses the workspace in disabled mode. Only this mode accepts a null policyVersionId. The dashboard replays observingVersionId alongside the enforced version. Endpoints do not receive that version. Omit it to keep the current observing version or set it to null to clear it. Endpoints apply changes on their next check-in. Read rollout and failure behavior before you choose enforce.