Skip to content
Policy DSL

General API

This API manages stored policies and flows, their draft/version lifecycle, ownership, groups, audit, and tenant-scoped access control.

Base URL

Section titled “Base URL”
https://api.policy2.net

Resource Model

Section titled “Resource Model”

Policies and flows both use a base ID plus one or more concrete records.

  • the base ID identifies the logical resource across its lifetime
  • a concrete policy ID or flow ID identifies a specific draft or version record

That split is important because listing, ownership, grouping, deletion, and execution do not always operate on the same identifier.

Policies

Section titled “Policies”

Create a draft policy

Section titled “Create a draft policy”
POST /policy

Creates a new draft policy.

Update a policy draft or publish a version

Section titled “Update a policy draft or publish a version”
PUT /policy/{policyId}

Behavior depends on the submitted status:

  • draft updates the current draft
  • non-draft publish requests create a new version from the draft

Get a specific policy record

Section titled “Get a specific policy record”
GET /policy/{policyId}

Returns a specific draft or version record by policy ID.

List policy versions for a base

Section titled “List policy versions for a base”
GET /policy/{policyId}/versions

Returns the draft and published/versioned records for the base policy.

Create a new draft from an existing version

Section titled “Create a new draft from an existing version”
GET /policy/{policyId}/draft

Creates a draft from an existing published/versioned policy record and returns the new draft.

List visible policies

Section titled “List visible policies”
GET /policies

Returns policies visible to the current user in the current tenant context.

Flows

Section titled “Flows”

Create a draft flow

Section titled “Create a draft flow”
POST /flow

Creates a new draft flow.

Update a flow draft or publish a version

Section titled “Update a flow draft or publish a version”
PUT /flow/{flowId}

Behavior depends on the submitted status:

  • draft updates the current draft
  • non-draft publish requests create a new version from the draft

Get a specific flow record

Section titled “Get a specific flow record”
GET /flow/{flowId}

Returns a specific draft or version record by flow ID.

List flow versions for a base

Section titled “List flow versions for a base”
GET /flow/{flowId}/versions

Returns the draft and published/versioned records for the base flow.

Create a new draft from an existing version

Section titled “Create a new draft from an existing version”
GET /flow/{flowId}/draft

Creates a draft from an existing published/versioned flow record and returns the new draft.

List visible flows

Section titled “List visible flows”
GET /flows

Returns flows visible to the current user in the current tenant context.

Execution

Section titled “Execution”

All execution endpoints require a valid API key via the x-api-key header. The key must have at least view scope.

x-api-key: <your-api-key>

Ad hoc policy execution

Section titled “Ad hoc policy execution”
POST /run

Runs an unsaved policy body directly. This is not tied to a stored policy record.

Run a policy by base ID

Section titled “Run a policy by base ID”
POST /run/policy/{baseId}

Executes the current runnable policy for the base.

Resolution order:

  • latest published/versioned policy, if one exists
  • otherwise the draft

Run a policy by exact policy ID

Section titled “Run a policy by exact policy ID”
POST /run/policy_version/{policyId}

Executes the exact stored policy record identified by policyId.

Run a flow by base ID

Section titled “Run a flow by base ID”
POST /run/flow/{baseId}

Executes the current runnable flow for the base.

Resolution order:

  • latest published/versioned flow, if one exists
  • otherwise the draft

Run a flow by exact flow ID

Section titled “Run a flow by exact flow ID”
POST /run/flow_version/{flowId}

Executes the exact stored flow record identified by flowId.

Flow test execution

Section titled “Flow test execution”
POST /flow/test

Runs an ad hoc flow definition without storing it.

Ownership and Visibility

Section titled “Ownership and Visibility”

The API applies both role checks and ownership checks.

Never-published drafts

Section titled “Never-published drafts”

If a policy or flow has never been published:

  • it is owned by the creating user
  • only that user sees it in normal listings
  • it can still be loaded directly by ID if the caller has the link

Published/versioned resources

Section titled “Published/versioned resources”

Once a policy or flow is published/versioned:

  • ownership becomes organization-level
  • users in that organization can see it according to their role permissions

Groups

Section titled “Groups”

Create group

Section titled “Create group”
POST /group

Creates a group.

Get group

Section titled “Get group”
GET /group/{groupId}

Returns group metadata.

Update group

Section titled “Update group”
PUT /group/{groupId}

Updates group metadata.

Delete group

Section titled “Delete group”
DELETE /group/{groupId}

Deletes the group and its membership records.

List groups

Section titled “List groups”
GET /groups

Returns groups visible to the current user.

Add a member to a group

Section titled “Add a member to a group”
POST /group/{groupId}/member

Adds a policy base or flow base to a group.

Remove a member from a group

Section titled “Remove a member from a group”
DELETE /group/{groupId}/member/{memberId}

Removes a policy base or flow base from its group.

List group policies

Section titled “List group policies”
GET /group/{groupId}/policies

Lists visible policies in the group.

List group flows

Section titled “List group flows”
GET /group/{groupId}/flows

Lists visible flows in the group.

Delete Semantics

Section titled “Delete Semantics”

Policies and flows currently use soft delete.

Delete policy base

Section titled “Delete policy base”
DELETE /policy/{policyId}

Deletes the base policy, not just the individual version/draft record passed in.

Delete flow base

Section titled “Delete flow base”
DELETE /flow/{flowId}

Deletes the base flow, not just the individual version/draft record passed in.

Important delete behavior

Section titled “Important delete behavior”
  • versions are tied to a base and are not deleted individually
  • once a base is deleted, it is hidden from lists and groups
  • deleted bases cannot be loaded or executed
  • execution by exact version ID is also denied if the base has been deleted

Audit

Section titled “Audit”

List audit events

Section titled “List audit events”
GET /audit

Returns tenant-scoped audit events for authorized users.

Current audit coverage includes stored resource lifecycle and execution events such as:

  • created
  • edited
  • published
  • assigned
  • executed
  • deleted

The tenant audit view is intended for admins and auditors.

Role Notes

Section titled “Role Notes”

Current platform role expectations are:

  • viewer: inspect and run visible resources
  • editor: create drafts, tests, and groups
  • publisher: publish versions
  • admin: manage roles, keys, and deletes
  • auditor: review tenant audit activity without becoming an authoring role