System Policy API

Manage pattern-based system and tenant policies through the Agent API. This API covers both:

• the built-in system policy baseline that AxonFlow ships and maintains
• tenant or organization policies you add for custom pattern-based governance

API Endpoint: /api/v1/static-policies

Overview

System and tenant pattern-based policies (accessed via /api/v1/static-policies) are evaluated synchronously on every request. They:

• Detect SQL injection attempts
• Identify PII (credit cards, SSNs, emails, phone numbers)
• Block or warn on custom patterns
• Support tenant-specific overrides (Enterprise)

Base URL: http://localhost:8080 (Agent)

---

Authentication

All static policy endpoints require Authorization: Basic base64(clientId:clientSecret). The server derives tenant and org context from the authenticated credentials.

• Tenant context is extracted from the authenticated clientId — no separate header needed
• Organization-tier policies use organization_id in the request body (not a header)
• X-User-ID is used on mutating operations for audit attribution

Endpoints

GET /api/v1/static-policies

List all system and tenant pattern-based policies with optional filtering.

Request:

curl "http://localhost:8080/api/v1/static-policies?enabled=true&category=security-sqli&tier=system&limit=20" \

Query Parameters:

Parameter	Type	Default	Description
enabled	boolean	(none — returns all)	Filter by enabled status
category	string	(none — returns all)	Filter by category such as security-sqli, security-admin, pii-global, pii-us, pii-eu, pii-india, pii-singapore, code-secrets, code-unsafe, code-compliance, sensitive-data
tier	string	(none — returns all)	Filter by tier: system, organization, or tenant
search	string	(none — returns all)	Search by name or description
page	integer	1	Page number
limit	integer	20 (max: 100)	Preferred items-per-page parameter
page_size	integer	Deprecated	Backward-compatible alias for limit

Response (200 OK):

{
  "policies": [
    {
      "id": "01JSTATICPOLICY1234567890",
      "policy_id": "sys_sqli_union_select",
      "name": "UNION SELECT Detection",
      "description": "Detects UNION-based SQL injection attempts",
      "category": "security-sqli",
      "tier": "system",
      "pattern": "(?i)union\\s+(all\\s+)?select",
      "action": "block",
      "severity": "critical",
      "priority": 100,
      "enabled": true,
      "tenant_id": "",
      "version": 1,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": "01JTENANTPOLICY1234567890",
      "policy_id": "pol_abc123",
      "name": "Customer Account Pattern",
      "description": "Detects internal customer account identifiers",
      "category": "pii-global",
      "tier": "tenant",
      "pattern": "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14})\\b",
      "action": "log",
      "severity": "medium",
      "enabled": true,
      "priority": 50,
      "tenant_id": "my-tenant",
      "version": 3,
      "created_at": "2025-01-02T10:00:00Z",
      "updated_at": "2025-01-02T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 24,
    "total_pages": 1
  }
}

---

POST /api/v1/static-policies

Create a new static policy.

Request:

curl -X POST http://localhost:8080/api/v1/static-policies \
  -H "Content-Type: application/json" \
  -H "X-User-ID: [email protected]" \
  -d '{
    "name": "Block Competitor Mentions",
    "description": "Block queries mentioning competitor products",
    "category": "security-admin",
    "tier": "tenant",
    "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
    "action": "block",
    "severity": "medium",
    "priority": 90,
    "enabled": true,
    "tags": ["competitive-intelligence", "sales"]
  }'

Request Body:

Field	Type	Required	Default	Description
name	string	Yes	—	Policy display name
description	string	No	—	Policy description
category	string	Yes	—	Category such as security-sqli, security-admin, pii-global, pii-us, pii-eu, pii-india, pii-singapore, code-secrets, code-unsafe, code-compliance, sensitive-data
tier	string	No	tenant	Tier: tenant or organization via API
organization_id	string	No	—	Organization identifier for org-tier policies
pattern	string	Yes	—	Regex pattern to match
action	string	Yes	—	Action: block, redact, warn, or log
severity	string	No	"medium"	Severity: critical, high, medium, low
priority	integer	No	0	Evaluation priority (higher runs earlier)
enabled	boolean	No	false	Whether policy is active
tags	array	No	—	Tags for filtering and internal organization

Response (201 Created):

{
  "id": "01JTENANTPOLICY1234567890",
  "policy_id": "pol_abc123",
  "name": "Block Competitor Mentions",
  "description": "Block queries mentioning competitor products",
  "category": "security-admin",
  "tier": "tenant",
  "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
  "action": "block",
  "severity": "medium",
  "priority": 90,
  "enabled": true,
  "tags": ["competitive-intelligence", "sales"],
  "tenant_id": "my-tenant",
  "version": 1,
  "created_at": "2025-01-02T10:00:00Z",
  "updated_at": "2025-01-02T10:00:00Z"
}

System-tier policies cannot be created through this endpoint. Use it for tenant-tier policies in Community Edition and tenant or organization policies in Enterprise.

---

GET /api/v1/static-policies/{id}

Get a specific policy by ID.

Request:

curl http://localhost:8080/api/v1/static-policies/pol_abc123 \

Response (200 OK):

{
  "id": "01JTENANTPOLICY1234567890",
  "policy_id": "pol_abc123",
  "name": "Block Competitor Mentions",
  "description": "Block queries mentioning competitor products",
  "category": "security-admin",
  "tier": "tenant",
  "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
  "action": "block",
  "severity": "medium",
  "enabled": true,
  "priority": 90,
  "tenant_id": "my-tenant",
  "version": 3,
  "created_at": "2025-01-02T10:00:00Z",
  "updated_at": "2025-01-02T12:00:00Z"
}

---

PUT /api/v1/static-policies/{id}

Update an existing policy.

Request:

curl -X PUT http://localhost:8080/api/v1/static-policies/pol_abc123 \
  -H "Content-Type: application/json" \
  -H "X-User-ID: [email protected]" \
  -d '{
    "pattern": "(?i)(competitor-a|competitor-b|competitor-c|rival-product)",
    "enabled": true,
    "priority": 95
  }'

Response (200 OK):

{
  "id": "01JTENANTPOLICY1234567890",
  "policy_id": "pol_abc123",
  "name": "Block Competitor Mentions",
  "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
  "enabled": true,
  "version": 3,
  "updated_at": "2025-01-02T12:00:00Z"
}

note

System-tier policies cannot be modified or deleted through this endpoint. Create an override instead.

---

DELETE /api/v1/static-policies/{id}

Soft-delete a policy. The policy is disabled but retained for audit purposes.

Request:

curl -X DELETE http://localhost:8080/api/v1/static-policies/pol_abc123 \

Response (204 No Content):

No response body.

---

PATCH /api/v1/static-policies/{id}

Toggle the enabled status of a policy.

Request:

curl -X PATCH http://localhost:8080/api/v1/static-policies/pol_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Response (200 OK):

{
  "id": "01JTENANTPOLICY1234567890",
  "policy_id": "pol_abc123",
  "name": "Block Competitor Mentions",
  "description": "Block queries mentioning competitor products",
  "category": "security-admin",
  "tier": "tenant",
  "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
  "action": "block",
  "severity": "medium",
  "enabled": false,
  "priority": 90,
  "tenant_id": "my-tenant",
  "version": 4,
  "created_at": "2025-01-02T10:00:00Z",
  "updated_at": "2025-01-02T15:00:00Z"
}

---

Policy Testing

POST /api/v1/static-policies/test

Test a pattern against sample inputs without creating a policy.

Request:

curl -X POST http://localhost:8080/api/v1/static-policies/test \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "(?i)select.*from.*where",
    "inputs": [
      "SELECT * FROM users WHERE id = 1",
      "What is the weather today?",
      "Please select items from the menu where price is low"
    ]
  }'

Response (200 OK):

{
  "pattern": "(?i)select.*from.*where",
  "valid": true,
  "matches": [
    {
      "input": "SELECT * FROM users WHERE id = 1",
      "matched": true,
      "groups": ["SELECT * FROM users WHERE id = 1"]
    },
    {
      "input": "What is the weather today?",
      "matched": false,
      "groups": null
    },
    {
      "input": "Please select items from the menu where price is low",
      "matched": true,
      "groups": ["select items from the menu where price is low"]
    }
  ]
}

---

GET /api/v1/static-policies/effective

Get effective policies for a tenant, including system policies and tenant overrides.

Request:

curl http://localhost:8080/api/v1/static-policies/effective \

Response (200 OK):

{
  "static": [
    {
      "id": "01JSTATICPOLICY1234567890",
      "policy_id": "sys_sqli_union_select",
      "name": "UNION SELECT Detection",
      "description": "Detects UNION-based SQL injection attempts",
      "category": "security-sqli",
      "tier": "system",
      "pattern": "(?i)union\\s+(all\\s+)?select",
      "action": "block",
      "severity": "critical",
      "priority": 100,
      "enabled": true,
      "tenant_id": "",
      "version": 1,
      "has_override": false,
      "override_action": "",
      "override_enabled": true,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": "01JSTATICPOLICY0987654321",
      "policy_id": "sys_pii_credit_card",
      "name": "PII - Credit Card Detection",
      "description": "Detects credit card numbers",
      "category": "pii-global",
      "tier": "system",
      "pattern": "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14})\\b",
      "action": "warn",
      "severity": "high",
      "priority": 90,
      "enabled": true,
      "tenant_id": "",
      "version": 1,
      "has_override": true,
      "override_action": "block",
      "override_enabled": true,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "dynamic": [],
  "tenant_id": "my-tenant",
  "organization_id": "",
  "computed_at": "2025-01-02T12:00:00Z"
}

---

Version History

GET /api/v1/static-policies/{id}/versions

Get version history for a policy.

Request:

curl http://localhost:8080/api/v1/static-policies/pol_abc123/versions \

Response (200 OK):

{
  "policy_id": "pol_abc123",
  "versions": [
    {
      "version": 4,
      "pattern": "(?i)(competitor-a|competitor-b|competitor-c|rival-product)",
      "action": "block",
      "enabled": true,
      "changed_by": "[email protected]",
      "changed_at": "2025-01-02T14:00:00Z",
      "change_summary": "Added competitor-c to pattern"
    },
    {
      "version": 3,
      "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
      "action": "block",
      "enabled": true,
      "changed_by": "[email protected]",
      "changed_at": "2025-01-02T12:00:00Z",
      "change_summary": "Updated pattern"
    }
  ],
  "current_version": 4
}

---

Policy Overrides (Enterprise)

Tenant-specific overrides allow customizing system policy behavior without modifying the base policy.

POST /api/v1/static-policies/{id}/override

Create an override for a system policy.

Request:

curl -X POST http://localhost:8080/api/v1/static-policies/sys_pii_credit_card/override \
  -H "Content-Type: application/json" \
  -d '{
    "action_override": "block",
    "enabled_override": true,
    "override_reason": "Financial services compliance requires blocking",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Response (201 Created):

{
  "policy_id": "sys_pii_credit_card",
  "tenant_id": "my-tenant",
  "action_override": "block",
  "enabled_override": true,
  "override_reason": "Financial services compliance requires blocking",
  "expires_at": "2026-12-31T23:59:59Z",
  "created_at": "2025-01-02T10:00:00Z",
  "updated_at": "2025-01-02T10:00:00Z"
}

DELETE /api/v1/static-policies/{id}/override

Remove a policy override, reverting to system default.

Request:

curl -X DELETE http://localhost:8080/api/v1/static-policies/sys_pii_credit_card/override \

Response (204 No Content):

No response body.

GET /api/v1/static-policies/overrides

List all policy overrides for a tenant.

Request:

curl http://localhost:8080/api/v1/static-policies/overrides \

Response (200 OK):

{
  "overrides": [
    {
      "policy_id": "sys_pii_credit_card",
      "tenant_id": "my-tenant",
      "action_override": "block",
      "enabled_override": true,
      "override_reason": "Financial services compliance requires blocking",
      "expires_at": "2026-12-31T23:59:59Z",
      "created_at": "2025-01-02T10:00:00Z",
      "updated_at": "2025-01-02T10:00:00Z"
    }
  ],
  "count": 1
}

---

Policy Actions

Action	Description
block	Reject the request and return an error
redact	Allow the request but redact matched content from the input or output
warn	Allow the request but include a warning in the response
require_approval	Pause the request and require human approval before proceeding
log	Allow the request and log the match silently

---

Error Responses

HTTP Status	Error Code	Description
400	INVALID_PATTERN	Regex pattern is invalid
400	INVALID_ACTION	Action must be block, warn, or log
403	SYSTEM_POLICY_READONLY	Cannot modify system policies
404	POLICY_NOT_FOUND	Policy does not exist
409	POLICY_NAME_EXISTS	Policy name already in use

---

SDK Examples

Use the AxonFlow SDKs to manage system policies programmatically.

List Policies (Go)

policies, _ := client.ListStaticPolicies(axonflow.ListStaticPoliciesRequest{
    Enabled: true, Category: "security",
})
for _, p := range policies.Policies {
    fmt.Printf("%s: %s (%s)\n", p.ID, p.Name, p.Action)
}

Create Custom Policy (Python)

policy = await client.create_static_policy(
    name="Block Competitor Mentions",
    pattern=r"(?i)(competitor-a|competitor-b)",
    action="block",
    category="custom"
)

Test Pattern (TypeScript)

const result = await client.testStaticPolicy(policyId, {
  content: "Check competitor-a pricing"
});
console.log(`Matched: ${result.matched}`);

Community Examples

• Policy Examples - System and tenant policy patterns
• PII Detection - PII detection patterns
• SQL Injection - SQLi prevention examples

---

Next Steps

• Agent Endpoints - Policy enforcement API
• Security - PII Detection - PII detection patterns
• Security - SQL Injection - SQLi prevention