Static Policy API

Manage system policies for pattern-based enforcement through the Agent API. System policies define rules that are evaluated against every request for SQL injection prevention, PII detection, and custom patterns.

API Endpoint: /api/v1/static-policies

Overview

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

• 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 endpoints require:

• X-Org-ID header (required) — Identifies the tenant for policy scoping

System policies are read-only for all tenants. Custom policies and overrides are scoped to the tenant specified in X-Org-ID.

Endpoints

GET /api/v1/static-policies

List all static policies with optional filtering.

Request:

curl "http://localhost:8080/api/v1/static-policies?enabled=true&category=security" \
  -H "X-Org-ID: my-tenant"

Query Parameters:

Parameter	Type	Default	Description
enabled	boolean	(none — returns all)	Filter by enabled status
category	string	(none — returns all)	Filter by category (security, compliance, sensitive-data, custom)
page	integer	1	Page number
page_size	integer	50 (max: 100)	Items per page

Response (200 OK):

{
  "policies": [
    {
      "id": "sys_sqli_union",
      "name": "SQL Injection - UNION",
      "description": "Detects UNION-based SQL injection attempts",
      "category": "security",
      "pattern": "(?i)union\\s+(all\\s+)?select",
      "action": "block",
      "severity": "critical",
      "enabled": true,
      "system": true,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": "sys_pii_credit_card",
      "name": "PII - Credit Card Detection",
      "description": "Detects credit card numbers using Luhn validation",
      "category": "compliance",
      "pattern": "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14})\\b",
      "action": "warn",
      "severity": "high",
      "enabled": true,
      "system": true,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_count": 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-Org-ID: my-tenant" \
  -d '{
    "name": "Block Competitor Mentions",
    "description": "Block queries mentioning competitor products",
    "category": "custom",
    "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
    "action": "block",
    "severity": "medium",
    "enabled": true,
    "message": "Queries about competitor products are not allowed"
  }'

Request Body:

Field	Type	Required	Default	Description
name	string	Yes	—	Policy display name
description	string	No	—	Policy description
category	string	Yes	—	Category: security, compliance, sensitive-data, custom
pattern	string	Yes	—	Regex pattern to match
action	string	Yes	—	Action: block, warn, log
severity	string	No	"medium"	Severity: critical, high, medium, low
enabled	boolean	No	true	Whether policy is active
message	string	No	—	Custom message when policy triggers

Response (201 Created):

{
  "success": true,
  "policy": {
    "id": "pol_abc123",
    "name": "Block Competitor Mentions",
    "description": "Block queries mentioning competitor products",
    "category": "custom",
    "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
    "action": "block",
    "severity": "medium",
    "enabled": true,
    "message": "Queries about competitor products are not allowed",
    "system": false,
    "version": 1,
    "created_at": "2025-01-02T10:00:00Z",
    "updated_at": "2025-01-02T10:00:00Z"
  }
}

---

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

Get a specific policy by ID.

Request:

curl http://localhost:8080/api/v1/static-policies/pol_abc123 \
  -H "X-Org-ID: my-tenant"

Response (200 OK):

{
  "id": "pol_abc123",
  "name": "Block Competitor Mentions",
  "description": "Block queries mentioning competitor products",
  "category": "custom",
  "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
  "action": "block",
  "severity": "medium",
  "enabled": true,
  "message": "Queries about competitor products are not allowed",
  "system": false,
  "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-Org-ID: my-tenant" \
  -d '{
    "pattern": "(?i)(competitor-a|competitor-b|competitor-c|rival-product)",
    "enabled": true
  }'

Response (200 OK):

{
  "success": true,
  "policy": {
    "id": "pol_abc123",
    "name": "Block Competitor Mentions",
    "pattern": "(?i)(competitor-a|competitor-b|competitor-c|rival-product)",
    "enabled": true,
    "version": 4,
    "updated_at": "2025-01-02T14:00:00Z"
  }
}

note

System policies (where system: true) cannot be modified or deleted. 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 \
  -H "X-Org-ID: my-tenant"

Response (200 OK):

{
  "success": true,
  "message": "Policy soft-deleted",
  "policy_id": "pol_abc123"
}

---

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" \
  -H "X-Org-ID: my-tenant" \
  -d '{
    "enabled": false
  }'

Response (200 OK):

{
  "success": true,
  "policy": {
    "id": "pol_abc123",
    "enabled": false,
    "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",
    "test_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",
  "results": [
    {
      "input": "SELECT * FROM users WHERE id = 1",
      "matched": true,
      "match_positions": [{"start": 0, "end": 31}]
    },
    {
      "input": "What is the weather today?",
      "matched": false
    },
    {
      "input": "Please select items from the menu where price is low",
      "matched": true,
      "match_positions": [{"start": 7, "end": 52}]
    }
  ],
  "match_count": 2,
  "total_inputs": 3
}

---

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 \
  -H "X-Org-ID: my-tenant"

Response (200 OK):

{
  "tenant_id": "my-tenant",
  "effective_policies": [
    {
      "id": "sys_sqli_union",
      "name": "SQL Injection - UNION",
      "enabled": true,
      "action": "block",
      "source": "system",
      "override": null
    },
    {
      "id": "sys_pii_credit_card",
      "name": "PII - Credit Card Detection",
      "enabled": true,
      "action": "warn",
      "source": "system",
      "override": {
        "action": "block",
        "reason": "Tenant requires blocking credit card exposure"
      }
    },
    {
      "id": "pol_abc123",
      "name": "Block Competitor Mentions",
      "enabled": true,
      "action": "block",
      "source": "tenant"
    }
  ],
  "system_policies_count": 20,
  "tenant_policies_count": 3,
  "overrides_count": 1
}

---

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 \
  -H "X-Org-ID: my-tenant"

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" \
  -H "X-Org-ID: my-tenant" \
  -d '{
    "action": "block",
    "reason": "Financial services compliance requires blocking"
  }'

Response (201 Created):

{
  "success": true,
  "override": {
    "policy_id": "sys_pii_credit_card",
    "tenant_id": "my-tenant",
    "action": "block",
    "reason": "Financial services compliance requires blocking",
    "created_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 \
  -H "X-Org-ID: my-tenant"

Response (200 OK):

{
  "success": true,
  "message": "Override removed, policy reverted to system default"
}

GET /api/v1/static-policies/overrides

List all policy overrides for a tenant.

Request:

curl http://localhost:8080/api/v1/static-policies/overrides \
  -H "X-Org-ID: my-tenant"

Response (200 OK):

{
  "tenant_id": "my-tenant",
  "overrides": [
    {
      "policy_id": "sys_pii_credit_card",
      "policy_name": "PII - Credit Card Detection",
      "system_action": "warn",
      "override_action": "block",
      "reason": "Financial services compliance requires blocking",
      "created_at": "2025-01-02T10:00:00Z"
    }
  ],
  "count": 1
}

---

Policy Actions

Action	Description
block	Reject the request and return an error
warn	Allow the request but include a warning in the response
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 static 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 - Static and dynamic 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