Skip to main content
API docs by Redocly

AxonFlow Policy Management API (11.0.0)

Download OpenAPI specification:Download

URL: https://getaxonflow.com/support License: Business Source License 1.1

REST API for managing dynamic policies in AxonFlow.

Policies define conditions and actions for request processing, enabling:

  • Content filtering and DLP
  • User-based access controls
  • Risk scoring and blocking
  • Cost management

v11: the policies on this API are read-only

migrations/core/172 revokes INSERT, UPDATE, DELETE and TRUNCATE on the legacy policy tables (static_policies, dynamic_policies) from the application roles. Create, update, delete and bulk import on /api/v1/policies, /api/v1/tenant-policies and the deprecated /api/v1/dynamic-policies therefore answer 409 LEGACY_POLICY_WRITE_FROZEN naming the replacement. It is not an entitlement fact: no licence, edition or upgrade changes it. POST /api/v1/templates/{id}/apply creates a policy in the same table and answers the same 409.

  • Author policy through the typed authoring route, /api/v1/typed-policies, specified in orchestrator-api.yaml (validate, publish, activate). That is the only customer write path in v11, on every edition.
  • Reads are unaffected. List, get, export, effective, versions, test and simulation keep answering: the policies already stored here are still read, and evaluated, by the legacy engine, which stays present until v12 removes it.
  • One deployment shape still writes. The revoke binds the application roles only. A deployment whose connection may still write the tables (the database owner) is not refused, and its writes succeed as they did in v10. Which one a deployment has is a property of its database connection, not of AXONFLOW_DB_USE_APP_ROLE alone.
  • The write routes answer before reading the body. Where the connection cannot write the tables, create, update and bulk import answer 409 LEGACY_POLICY_WRITE_FROZEN before the request body is read, so a malformed body gets the same answer as a valid one.

Authentication

The Agent (port 8080) is the single entry point for all client traffic (ADR-024). Clients authenticate at the Agent with HTTP Basic auth (clientId:clientSecret); the Agent proxies policy requests to the Orchestrator and stamps the X-Tenant-ID header from the authenticated client's tenant. When calling the Orchestrator directly (internal deployments only), supply X-Tenant-ID yourself. X-User-ID is optional and used for audit attribution.

Note: /api/v1/templates* is NOT proxied by the Agent — the template endpoints are reachable only on the Orchestrator directly (or via the customer portal catch-all).

Multi-tenancy

Policies are isolated per tenant. Each API call operates only on policies belonging to the authenticated tenant.

Related APIs

  • The static policy enforcement API is served by the Agent and specified in agent-api.yaml. Its current path spelling is /api/v1/system-policies*; /api/v1/static-policies* is the deprecated spelling and is still served.
  • Unified policy read/write (an aggregated static + dynamic view) lives on the Enterprise customer portal and is documented internally. Enterprise only.

Terminology note

The terminology migration renaming static to system and dynamic to tenant policy endpoints has shipped. The alias routes exist and are served on both APIs.

On this API /api/v1/tenant-policies is the current spelling and /api/v1/dynamic-policies is the deprecated one. The deprecated paths remain served by the same handlers and return the same status codes and bodies; they additionally carry Deprecation and Link response headers naming the replacement.

No removal date is published for the deprecated spelling and no Sunset header is emitted, so clients should not infer one. Migrate when convenient and watch the release notes.

Tenant Policies

Tenant policy CRUD via the ADR-024 /api/v1/tenant-policies surface (Orchestrator, proxied by the Agent). Accepts only policies whose category starts with dynamic- or media-.

Note the category prefixes keep their original spelling. The terminology migration renamed the PATHS only; the category vocabulary is a separate, stored value on every existing policy row and renaming it would be a data migration, not an alias.

List dynamic policies Deprecated

Retrieve a paginated list of dynamic policies. Only policies whose category starts with dynamic- or media- are returned. When type=media is passed without a category, results are filtered to media-* categories.

limit is the preferred pagination parameter; page_size is deprecated but still accepted.

query Parameters
type
string (PolicyType)
Enum: "content" "user" "risk" "cost" "context_aware" "media" "rate-limit" "budget" "time-access" "role-access" "mcp" "connector"

Filter by policy type

category
string

Filter by category. Must start with dynamic- or media- (e.g., dynamic-risk, media-safety); other values are rejected with a validation error.

enabled
boolean

Filter by enabled status

search
string <= 100 characters

Search in policy name and description

page
integer >= 1
Default: 1

Page number (1-indexed)

limit
integer [ 1 .. 100 ]
Default: 20

Items per page (preferred over the deprecated page_size)

page_size
integer [ 1 .. 100 ]
Deprecated

Items per page (deprecated - use limit instead)

sort_by
string
Default: "created_at"
Enum: "name" "created_at" "updated_at" "priority"

Sort field

sort_dir
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "pagination": {
    }
}

Create a dynamic policy Deprecated

Create a new dynamic policy. category is required and must start with dynamic- or media- (e.g., dynamic-risk, media-safety).

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
name
required
string [ 3 .. 100 ] characters
description
string <= 500 characters
type
required
string (PolicyType)
Enum: "content" "user" "risk" "cost" "context_aware" "media" "rate-limit" "budget" "time-access" "role-access" "mcp" "connector"

Policy type determines evaluation context:

  • content: Evaluates request/response content
  • user: Evaluates user attributes
  • risk: Evaluates risk scores
  • cost: Evaluates cost estimates
  • context_aware: Context-aware controls (tenant isolation, debug restriction, sensitive-data control)
  • media: Media governance policies (multimodal image governance)
  • rate-limit, budget, time-access: MCP rate/budget controls
  • role-access, mcp, connector: MCP access controls
category
string

Policy category (dynamic-risk, dynamic-compliance, media-safety, etc.). Required on the /api/v1/dynamic-policies surface, where it must start with dynamic- or media-.

tier
string
Enum: "organization" "tenant"

Policy tier. Only organization or tenant is allowed via the API.

required
Array of objects (PolicyCondition) non-empty
required
Array of objects (PolicyAction) non-empty
priority
integer [ 0 .. 1000 ]
Default: 0
enabled
boolean
Default: true
tags
Array of strings

Tags for categorization

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "content",
  • "category": "string",
  • "tier": "organization",
  • "conditions": [
    ],
  • "actions": [
    ],
  • "priority": 0,
  • "enabled": true,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Import dynamic policies Deprecated

Bulk import dynamic policies from JSON. Supports up to 100 policies per request. Every policy must have a category starting with dynamic- or media-.

On a deployment whose database connection cannot write the legacy policy tables (migrations/core/172), the request is refused 409 LEGACY_POLICY_WRITE_FROZEN before its body is read, whatever it contains, and the refusal names the typed authoring route. An owner-role deployment still imports.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
required
Array of objects (CreatePolicyRequest) [ 1 .. 100 ] items
overwrite_mode
string
Default: "skip"
Enum: "skip" "overwrite" "error"

How to handle existing policies

Responses

Request samples

Content type
application/json
{
  • "policies": [
    ],
  • "overwrite_mode": "skip"
}

Response samples

Content type
application/json
{
  • "created": 0,
  • "updated": 0,
  • "skipped": 0,
  • "errors": [
    ]
}

Export dynamic policies Deprecated

Export the tenant's dynamic policies as JSON. Only policies with a dynamic-* or media-* category are included.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "exported_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "string"
}

Get effective dynamic policies Deprecated

Returns the enabled dynamic policies for the tenant (both dynamic-* and media-* categories), sorted by priority ascending. Returns up to 100 policies.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "pagination": {
    }
}

Get a dynamic policy Deprecated

Retrieve a single dynamic policy by ID. Returns 404 if the policy exists but is not a dynamic policy (category not dynamic-*/media-*).

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Update a dynamic policy Deprecated

Update an existing dynamic policy. Only provided fields are updated. If category is changed, the new value must still start with dynamic- or media-.

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
name
string [ 3 .. 100 ] characters
description
string <= 500 characters
type
string (PolicyType)
Enum: "content" "user" "risk" "cost" "context_aware" "media" "rate-limit" "budget" "time-access" "role-access" "mcp" "connector"

Policy type determines evaluation context:

  • content: Evaluates request/response content
  • user: Evaluates user attributes
  • risk: Evaluates risk scores
  • cost: Evaluates cost estimates
  • context_aware: Context-aware controls (tenant isolation, debug restriction, sensitive-data control)
  • media: Media governance policies (multimodal image governance)
  • rate-limit, budget, time-access: MCP rate/budget controls
  • role-access, mcp, connector: MCP access controls
category
string

Policy category. Only changeable on non-system policies.

Array of objects (PolicyCondition)
Array of objects (PolicyAction)
priority
integer [ 0 .. 1000 ]
enabled
boolean
tags
Array of strings

Tags for categorization

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "content",
  • "category": "string",
  • "conditions": [
    ],
  • "actions": [
    ],
  • "priority": 1000,
  • "enabled": true,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Delete a dynamic policy Deprecated

Soft-delete a dynamic policy. The policy is marked as deleted but retained for audit purposes.

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get dynamic policy version history Deprecated

Retrieve the complete version history of a dynamic policy for audit purposes

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "versions": [
    ]
}

Dynamic Policies

DEPRECATED spelling of Tenant Policies, served at /api/v1/dynamic-policies. Every operation is the same handler as its /api/v1/tenant-policies counterpart and returns the same status code and body.

In v11 BOTH spellings are the deprecated export surface (PRD §1.11): reads are served, and every response carries Link: </api/v1/typed-policies>; rel="successor-version" and X-AxonFlow-Removed-In: v11.1, plus an RFC 9745 Deprecation: @<epoch> from the v11.0.0 tag. v11.1 removes both spellings; there is no Sunset header until that release has a date.

List dynamic policies Deprecated

Retrieve a paginated list of dynamic policies. Only policies whose category starts with dynamic- or media- are returned. When type=media is passed without a category, results are filtered to media-* categories.

limit is the preferred pagination parameter; page_size is deprecated but still accepted.

query Parameters
type
string (PolicyType)
Enum: "content" "user" "risk" "cost" "context_aware" "media" "rate-limit" "budget" "time-access" "role-access" "mcp" "connector"

Filter by policy type

category
string

Filter by category. Must start with dynamic- or media- (e.g., dynamic-risk, media-safety); other values are rejected with a validation error.

enabled
boolean

Filter by enabled status

search
string <= 100 characters

Search in policy name and description

page
integer >= 1
Default: 1

Page number (1-indexed)

limit
integer [ 1 .. 100 ]
Default: 20

Items per page (preferred over the deprecated page_size)

page_size
integer [ 1 .. 100 ]
Deprecated

Items per page (deprecated - use limit instead)

sort_by
string
Default: "created_at"
Enum: "name" "created_at" "updated_at" "priority"

Sort field

sort_dir
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "pagination": {
    }
}

Create a dynamic policy Deprecated

Create a new dynamic policy. category is required and must start with dynamic- or media- (e.g., dynamic-risk, media-safety).

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
name
required
string [ 3 .. 100 ] characters
description
string <= 500 characters
type
required
string (PolicyType)
Enum: "content" "user" "risk" "cost" "context_aware" "media" "rate-limit" "budget" "time-access" "role-access" "mcp" "connector"

Policy type determines evaluation context:

  • content: Evaluates request/response content
  • user: Evaluates user attributes
  • risk: Evaluates risk scores
  • cost: Evaluates cost estimates
  • context_aware: Context-aware controls (tenant isolation, debug restriction, sensitive-data control)
  • media: Media governance policies (multimodal image governance)
  • rate-limit, budget, time-access: MCP rate/budget controls
  • role-access, mcp, connector: MCP access controls
category
string

Policy category (dynamic-risk, dynamic-compliance, media-safety, etc.). Required on the /api/v1/dynamic-policies surface, where it must start with dynamic- or media-.

tier
string
Enum: "organization" "tenant"

Policy tier. Only organization or tenant is allowed via the API.

required
Array of objects (PolicyCondition) non-empty
required
Array of objects (PolicyAction) non-empty
priority
integer [ 0 .. 1000 ]
Default: 0
enabled
boolean
Default: true
tags
Array of strings

Tags for categorization

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "content",
  • "category": "string",
  • "tier": "organization",
  • "conditions": [
    ],
  • "actions": [
    ],
  • "priority": 0,
  • "enabled": true,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Import dynamic policies Deprecated

Bulk import dynamic policies from JSON. Supports up to 100 policies per request. Every policy must have a category starting with dynamic- or media-.

On a deployment whose database connection cannot write the legacy policy tables (migrations/core/172), the request is refused 409 LEGACY_POLICY_WRITE_FROZEN before its body is read, whatever it contains, and the refusal names the typed authoring route. An owner-role deployment still imports.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
required
Array of objects (CreatePolicyRequest) [ 1 .. 100 ] items
overwrite_mode
string
Default: "skip"
Enum: "skip" "overwrite" "error"

How to handle existing policies

Responses

Request samples

Content type
application/json
{
  • "policies": [
    ],
  • "overwrite_mode": "skip"
}

Response samples

Content type
application/json
{
  • "created": 0,
  • "updated": 0,
  • "skipped": 0,
  • "errors": [
    ]
}

Export dynamic policies Deprecated

Export the tenant's dynamic policies as JSON. Only policies with a dynamic-* or media-* category are included.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "exported_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "string"
}

Get effective dynamic policies Deprecated

Returns the enabled dynamic policies for the tenant (both dynamic-* and media-* categories), sorted by priority ascending. Returns up to 100 policies.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "pagination": {
    }
}

Get a dynamic policy Deprecated

Retrieve a single dynamic policy by ID. Returns 404 if the policy exists but is not a dynamic policy (category not dynamic-*/media-*).

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Update a dynamic policy Deprecated

Update an existing dynamic policy. Only provided fields are updated. If category is changed, the new value must still start with dynamic- or media-.

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
name
string [ 3 .. 100 ] characters
description
string <= 500 characters
type
string (PolicyType)
Enum: "content" "user" "risk" "cost" "context_aware" "media" "rate-limit" "budget" "time-access" "role-access" "mcp" "connector"

Policy type determines evaluation context:

  • content: Evaluates request/response content
  • user: Evaluates user attributes
  • risk: Evaluates risk scores
  • cost: Evaluates cost estimates
  • context_aware: Context-aware controls (tenant isolation, debug restriction, sensitive-data control)
  • media: Media governance policies (multimodal image governance)
  • rate-limit, budget, time-access: MCP rate/budget controls
  • role-access, mcp, connector: MCP access controls
category
string

Policy category. Only changeable on non-system policies.

Array of objects (PolicyCondition)
Array of objects (PolicyAction)
priority
integer [ 0 .. 1000 ]
enabled
boolean
tags
Array of strings

Tags for categorization

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "content",
  • "category": "string",
  • "conditions": [
    ],
  • "actions": [
    ],
  • "priority": 1000,
  • "enabled": true,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Delete a dynamic policy Deprecated

Soft-delete a dynamic policy. The policy is marked as deleted but retained for audit purposes.

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get dynamic policy version history Deprecated

Retrieve the complete version history of a dynamic policy for audit purposes

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "versions": [
    ]
}

Policies

Dynamic policy CRUD operations (Orchestrator)

List policies Deprecated

Retrieve a paginated list of policies with optional filtering

query Parameters
type
string (PolicyType)
Enum: "content" "user" "risk" "cost" "context_aware" "media" "rate-limit" "budget" "time-access" "role-access" "mcp" "connector"

Filter by policy type

enabled
boolean

Filter by enabled status

search
string <= 100 characters

Search in policy name and description

page
integer >= 1
Default: 1

Page number (1-indexed)

page_size
integer [ 1 .. 100 ]
Default: 20

Items per page

sort_by
string
Default: "created_at"
Enum: "name" "created_at" "updated_at" "priority"

Sort field

sort_dir
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "pagination": {
    }
}

Create a policy Deprecated

Create a new policy with conditions and actions

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
name
required
string [ 3 .. 100 ] characters
description
string <= 500 characters
type
required
string (PolicyType)
Enum: "content" "user" "risk" "cost" "context_aware" "media" "rate-limit" "budget" "time-access" "role-access" "mcp" "connector"

Policy type determines evaluation context:

  • content: Evaluates request/response content
  • user: Evaluates user attributes
  • risk: Evaluates risk scores
  • cost: Evaluates cost estimates
  • context_aware: Context-aware controls (tenant isolation, debug restriction, sensitive-data control)
  • media: Media governance policies (multimodal image governance)
  • rate-limit, budget, time-access: MCP rate/budget controls
  • role-access, mcp, connector: MCP access controls
category
string

Policy category (dynamic-risk, dynamic-compliance, media-safety, etc.). Required on the /api/v1/dynamic-policies surface, where it must start with dynamic- or media-.

tier
string
Enum: "organization" "tenant"

Policy tier. Only organization or tenant is allowed via the API.

required
Array of objects (PolicyCondition) non-empty
required
Array of objects (PolicyAction) non-empty
priority
integer [ 0 .. 1000 ]
Default: 0
enabled
boolean
Default: true
tags
Array of strings

Tags for categorization

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Block PII Access",
  • "description": "Prevent unauthorized access to personally identifiable information",
  • "type": "content",
  • "conditions": [
    ],
  • "actions": [
    ],
  • "priority": 100,
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Get a policy Deprecated

Retrieve a single policy by ID

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Update a policy Deprecated

Update an existing policy. Only provided fields are updated.

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
name
string [ 3 .. 100 ] characters
description
string <= 500 characters
type
string (PolicyType)
Enum: "content" "user" "risk" "cost" "context_aware" "media" "rate-limit" "budget" "time-access" "role-access" "mcp" "connector"

Policy type determines evaluation context:

  • content: Evaluates request/response content
  • user: Evaluates user attributes
  • risk: Evaluates risk scores
  • cost: Evaluates cost estimates
  • context_aware: Context-aware controls (tenant isolation, debug restriction, sensitive-data control)
  • media: Media governance policies (multimodal image governance)
  • rate-limit, budget, time-access: MCP rate/budget controls
  • role-access, mcp, connector: MCP access controls
category
string

Policy category. Only changeable on non-system policies.

Array of objects (PolicyCondition)
Array of objects (PolicyAction)
priority
integer [ 0 .. 1000 ]
enabled
boolean
tags
Array of strings

Tags for categorization

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "content",
  • "category": "string",
  • "conditions": [
    ],
  • "actions": [
    ],
  • "priority": 1000,
  • "enabled": true,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "policy": {
    }
}

Delete a policy Deprecated

Soft-delete a policy. The policy is marked as deleted but retained for audit purposes.

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get policy version history Deprecated

Retrieve the complete version history of a policy for audit purposes

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "versions": [
    ]
}

List active dynamic policies (legacy) Deprecated

Legacy endpoint. Returns the array of active dynamic policies visible to the CALLING tenant — its own plus the shared global/default baseline (no pagination). Policies owned by other tenants are never returned in the same response, and requests without a resolvable tenant are rejected with 401 (fail closed).

The tenant scope is read from the X-Tenant-ID header. When the request arrives through the AxonFlow Agent, that header is set from the validated credential and overwrites any client-supplied value, so the caller cannot choose the scope. The orchestrator itself does not authenticate this route, so a caller with direct network access to the orchestrator can name a tenant — deploy the orchestrator on a private network behind the Agent.

Prefer GET /api/v1/dynamic-policies.

Responses

Response samples

Content type
application/json
[
  • { }
]

Testing

Policy testing and validation

Test a dynamic policy Deprecated

Evaluate a dynamic policy against sample input without executing actions. query is required.

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Request Body schema: application/json
required
query
required
string

Sample query to test against

object

User context for testing

request_type
string

Type of request being simulated

object

Additional context for testing

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "user": {},
  • "request_type": "string",
  • "context": { }
}

Response samples

Content type
application/json
{
  • "matched": true,
  • "blocked": true,
  • "actions": [
    ],
  • "explanation": "string",
  • "eval_time_ms": 0.1
}

Test a dynamic policy Deprecated

Evaluate a dynamic policy against sample input without executing actions. query is required.

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Request Body schema: application/json
required
query
required
string

Sample query to test against

object

User context for testing

request_type
string

Type of request being simulated

object

Additional context for testing

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "user": {},
  • "request_type": "string",
  • "context": { }
}

Response samples

Content type
application/json
{
  • "matched": true,
  • "blocked": true,
  • "actions": [
    ],
  • "explanation": "string",
  • "eval_time_ms": 0.1
}

Test a policy Deprecated

Evaluate a policy against sample input without executing actions. Useful for validating policy behavior before enabling.

path Parameters
id
required
string
Example: pol_abc123def456

Policy unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Request Body schema: application/json
required
query
required
string

Sample query to test against

object

User context for testing

request_type
string

Type of request being simulated

object

Additional context for testing

Responses

Request samples

Content type
application/json
{
  • "query": "Show me the customer's SSN and credit card",
  • "user": {},
  • "request_type": "query",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "matched": true,
  • "blocked": true,
  • "actions": [
    ],
  • "explanation": "Policy 'Block PII Access' matched: all 2 conditions evaluated to true",
  • "eval_time_ms": 0.45
}

Test input against all active policies (legacy) Deprecated

Legacy endpoint. Evaluates the supplied input against all active dynamic policies and returns the raw policy evaluation result. Prefer POST /api/v1/policies/simulate (dry-run semantics, tier-aware) or POST /api/v1/dynamic-policies/{id}/test (single-policy testing).

Request Body schema: application/json
required
query
string

Sample query to test against

object (SimulationUserContext)

User context for policy simulation and testing

request_type
string

Type of request being simulated

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "user": {
    },
  • "request_type": "string"
}

Response samples

Content type
application/json
{
  • "allowed": true,
  • "applied_policies": [
    ],
  • "risk_score": 0.1,
  • "severity": "string",
  • "required_actions": [
    ],
  • "processing_time_ms": 0
}

Simulation

Policy simulation, impact reports, and conflict detection. Evaluation tier and above.

Simulate policies (dry run) Deprecated

Run all active policies against the provided input as a dry run — no audit writes and no policy actions are applied.

Evaluation tier and above — requires an Evaluation or Enterprise license. Daily simulation quotas apply per tier (unlimited on Enterprise); exceeding the quota returns 429.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Request Body schema: application/json
required
query
required
string

Input to evaluate against all active policies

request_type
string

Type of request being simulated (defaults to "simulation")

object (SimulationUserContext)

User context for policy simulation and testing

object (SimulationClientContext)

Client context for policy simulation

object

Additional context for evaluation

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "request_type": "string",
  • "user": {
    },
  • "client": {
    },
  • "context": { }
}

Response samples

Content type
application/json
{
  • "allowed": true,
  • "applied_policies": [
    ],
  • "risk_score": 0.1,
  • "required_actions": [
    ],
  • "processing_time_ms": 0,
  • "total_policies": 0,
  • "dry_run": true,
  • "simulated_at": "2019-08-24T14:15:22Z",
  • "tier": "string",
  • "daily_usage": {
    }
}

Generate a policy impact report Deprecated

Test a single policy against multiple inputs and return aggregate match/block statistics plus per-input results.

Evaluation tier and above — requires an Evaluation or Enterprise license. The number of inputs per request is capped per tier.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Request Body schema: application/json
required
policy_id
required
string

Policy to test against the inputs

required
Array of objects (ImpactReportInput) non-empty

Test inputs (per-tier maximum applies)

Responses

Request samples

Content type
application/json
{
  • "policy_id": "string",
  • "inputs": [
    ]
}

Response samples

Content type
application/json
{
  • "policy_id": "string",
  • "policy_name": "string",
  • "total_inputs": 0,
  • "matched": 0,
  • "blocked": 0,
  • "match_rate": 0.1,
  • "block_rate": 0.1,
  • "results": [
    ],
  • "processing_time_ms": 0,
  • "generated_at": "2019-08-24T14:15:22Z",
  • "tier": "string"
}

Detect policy conflicts Deprecated

Analyze the tenant's active policies for contradictions, shadows, and redundancies. Optionally scope the analysis to a single policy by passing policy_id in the request body (the body may be omitted entirely to check all policies).

Evaluation tier and above — requires an Evaluation or Enterprise license. Counts against the daily simulation quota.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Request Body schema: application/json
optional
policy_id
string

Optional: check a specific policy against all others

Responses

Request samples

Content type
application/json
{
  • "policy_id": "string"
}

Response samples

Content type
application/json
{
  • "conflicts": [
    ],
  • "total_policies": 0,
  • "conflict_count": 0,
  • "checked_at": "2019-08-24T14:15:22Z",
  • "tier": "string"
}

Bulk Operations

Import and export policies

Import policies Deprecated

Bulk import policies from JSON. Supports up to 100 policies per request.

Overwrite modes:

  • skip: Skip policies that already exist (by name)
  • overwrite: Update existing policies
  • error: Fail if any policy already exists

On a deployment whose database connection cannot write the legacy policy tables (migrations/core/172), the request is refused 409 LEGACY_POLICY_WRITE_FROZEN before its body is read, whatever it contains, and the refusal names the typed authoring route. An owner-role deployment still imports.

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
required
Array of objects (CreatePolicyRequest) [ 1 .. 100 ] items
overwrite_mode
string
Default: "skip"
Enum: "skip" "overwrite" "error"

How to handle existing policies

Responses

Request samples

Content type
application/json
{
  • "policies": [
    ],
  • "overwrite_mode": "skip"
}

Response samples

Content type
application/json
{
  • "created": 0,
  • "updated": 0,
  • "skipped": 0,
  • "errors": [
    ]
}

Export policies Deprecated

Export all policies for the tenant as JSON

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "exported_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "string"
}

Templates

Policy templates for quick policy creation

List policy templates Deprecated

Retrieve available policy templates for quick policy creation. Templates provide pre-configured policies for common use cases like HIPAA compliance, GDPR data protection, and rate limiting.

query Parameters
category
string
Enum: "general" "security" "compliance" "content_safety" "rate_limiting" "access_control" "data_protection" "custom"

Filter by template category

search
string

Search in name and description

tags
string

Comma-separated tags to filter by

active
boolean

Filter by active status

builtin
boolean

Filter by builtin status

page
integer >= 1
Default: 1

Page number (1-indexed)

page_size
integer [ 1 .. 100 ]
Default: 20

Number of items per page

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "templates": [
    ],
  • "pagination": {
    }
}

Get a template Deprecated

Retrieve a single policy template by ID

path Parameters
id
required
string
Example: hipaa_phi_protection

Template unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "template": {
    }
}

Apply a template Deprecated

Create a new policy from a template by providing variable values. Templates may have required and optional variables that customize the generated policy.

v11: the generated policy is written to dynamic_policies, which migrations/core/172 makes read-only to the application roles, so on a deployment whose database connection cannot write it this route answers 409 LEGACY_POLICY_WRITE_FROZEN before the request body is read, whatever it contains, as the policy write routes do. An owner-role deployment still applies.

path Parameters
id
required
string
Example: hipaa_phi_protection

Template unique identifier

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

X-User-ID
string

User identifier for audit logging

Request Body schema: application/json
required
policy_name
required
string [ 3 .. 100 ] characters

Name for the new policy

description
string <= 500 characters

Optional policy description

required
object

Variable values for the template

enabled
boolean
Default: false

Whether to enable the policy immediately

priority
integer [ 0 .. 1000 ]

Policy priority (overrides template default)

Responses

Request samples

Content type
application/json
{
  • "policy_name": "Production Rate Limit",
  • "description": "Rate limiting for production API",
  • "variables": {
    },
  • "enabled": true,
  • "priority": 75
}

Response samples

Content type
application/json
{
  • "success": true,
  • "policy": {
    },
  • "usage_id": "string",
  • "message": "string"
}

List template categories Deprecated

Retrieve all available template categories

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

Get template usage statistics Deprecated

Retrieve usage statistics for templates in your tenant

header Parameters
X-Tenant-ID
required
string
Example: tenant_abc123

Tenant identifier for multi-tenancy isolation. When calling through the Agent (recommended), this header is stamped automatically from the authenticated client — you do not set it yourself. Required only on direct Orchestrator calls (internal deployments).

Responses

Response samples

Content type
application/json
{
  • "stats": [
    ]
}