Policy API

Policy API

Create drafts, preview assignments, publish revisions, and inspect per-target adoption.

Policies have immutable published revisions and separate executor adoption. Read precedence and rollback before automation. Administrator authority is required for every resolved target.

Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.

List policies

GET/organizations/{organization_id}/policies
Scope
policies:read
Auth
Bearer API key

Lists policy metadata and current published revision; it does not collapse target adoption into publication status. Standard limit and cursor apply. Unknown filters return 422.

Query parameters
familystringoptional

Limit policy family.

one ofedge, endpoint, dlp, device_control, compliance, access
200Result

Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.

Create a draft

POST/organizations/{organization_id}/policies
Scope
policies:write
Auth
Bearer API key

Creates an unpublished draft with no enforcement effect.

Request body
namestringrequired

Display name; does not change resource identity.

rule1–120 characters
familystringrequired

Immutable family.

one ofedge, endpoint, dlp, device_control, compliance, access
modestringoptional

Initial enforcement mode.

one ofmonitor, blockdefaultmonitor
201Created

Returns policy ID, draft revision, configuration, and ETag.

Read a policy

GET/organizations/{organization_id}/policies/{policy_id}
Scope
policies:read
Auth
Bearer API key

Returns family-specific configuration, draft revision, current published revision, assignments, and valid writable settings for installed capabilities.

200Result

Returns data and request_id.

Update a draft

PATCH/organizations/{organization_id}/policies/{policy_id}
Scope
policies:write
Auth
Bearer API key

Updates an unpublished draft. Requires If-Match; published revisions are never changed. Family configuration defines the writable schema. Unknown family fields or unsupported required combinations return 422.

Request body
modestringoptional

Requested mode; omission preserves the draft mode. Access remains deny by default without explicit grants.

one ofmonitor, block
configurationobjectoptional

Complete replacement draft configuration for the existing family. Omission preserves the current configuration; omitted fields inside a supplied replacement receive family defaults. Required controls must be supported by targets.

assignmentsobject[]optional

Replacement assignments; omission preserves current assignments and an empty list removes draft assignments. Equal-priority overlapping group assignments conflict.

200Result

Returns the new draft ETag. No target changes until publication.

Preview a draft

POST/organizations/{organization_id}/policies/{policy_id}/preview
Scope
policies:write
Auth
Bearer API key

Evaluates assignment precedence, required capabilities, and visible targets without publishing.

Request body
draft_revisionintegerrequired

Current draft revision to evaluate.

ruleAt least 1
200Result

Returns target IDs, winning assignments, effective revisions, unsupported controls, and conflicts. The preview does not lock future membership.

Publish a revision

POST/organizations/{organization_id}/policies/{policy_id}/publish
Scope
policies:write
Auth
Bearer API key

Publishes an immutable policy revision. Requires If-Match; assignment conflicts return 409 assignment_conflict; invalid capability requirements return 422.

Request body
draft_revisionintegerrequired

The reviewed current draft.

ruleAt least 1
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
202Accepted

Returns published revision and publication operation. Success records desired configuration; adoption remains separate.

Read adoption

GET/organizations/{organization_id}/policies/{policy_id}/adoption
Scope
policies:read
Auth
Bearer API key

Returns per-target requested and applied revisions with pending, applied, failed, or offline state. The response lists unsupported controls and latest observation time.

200Result

Returns data and request_id.

Create an exception

POST/organizations/{organization_id}/policy-exceptions
Scope
policies:write
Auth
Bearer API key

Creates a scoped policy exception. Access or risk exceptions require the corresponding special approval grant in addition to this scope.

Request body
policy_idstringrequired

Policy containing the affected rule.

rule_idstringrequired

Single affected rule.

asset_idsstring[]required

Existing assets visible to the caller; duplicates reject the request.

rule1–200 unique IDs
effectstringrequired

Exact change to the named rule.

one ofmonitor_only, suppress_alert, skip_check, allow_access
expires_attimestamprequired

Future UTC expiry; no implicit permanent exception.

reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
201Created

Returns an exception ID and pending adoption state. Unsupported family/effect combinations return 422.

Revoke an exception

DELETE/organizations/{organization_id}/policy-exceptions/{exception_id}
Scope
policies:write
Auth
Bearer API key

Revokes future exception use. Requires If-Match; enforcement reconciliation is asynchronous and must be verified.

202Accepted

Returns the exception summary and reconciliation operation. Completed transfers and skipped checks remain historical facts.