Skip to main content

Policy Templates API

The policy template catalog on the Orchestrator, as it answers in v11.0.0.

Applying a template is refused in v11

A template is a reusable shape for a legacy tenant policy, and applying one writes a row to the legacy policy table, which v11 makes read-only. So POST /api/v1/templates/{id}/apply answers 409 LEGACY_POLICY_WRITE_FROZEN and names the route to use instead. The catalog reads still answer, so you can read a template's conditions and actions and re-author the rule as a typed policy; they are removed in a later release with the rest of the legacy policy family. See Typed Policy Authoring.

Generated reference

Request and response schemas live in the Policy API reference. Each endpoint below links to its operation there.

Routes​

MethodPathIn v11Reference
GET/api/v1/templatesRead: list templateslistTemplates
GET/api/v1/templates/categoriesRead: list categorieslistTemplateCategories
GET/api/v1/templates/statsRead: your tenant's past template usagegetTemplateStats
GET/api/v1/templates/{id}Read: one templategetTemplate
POST/api/v1/templates/{id}/applyWrite: 409applyTemplate

Base URL:

http://localhost:8081

The template routes are served by the Orchestrator directly (port 8081) and are not proxied through the Agent. The Customer Portal proxies all five for its own pages, apply behind the policy:write permission.

Authentication​

The Orchestrator reads identity from headers set by the caller or by an upstream gateway:

  • X-Tenant-ID: required for GET /api/v1/templates/stats and for apply; missing tenant context returns 401 with code UNAUTHORIZED. List, get and categories do not require it.
  • X-User-ID: recorded for audit attribution.

Errors use the shape {"error": {"code": "<STRING_CODE>", "message": "...", "details": [...]}}. If the Orchestrator has no database connection, every template endpoint returns 503.

Apply answers 409​

{
  "error": {
    "code": "LEGACY_POLICY_WRITE_FROZEN",
    "message": "The legacy policy tables are read-only in v11: migrations/core/172 revoked write access from the application role, and this endpoint writes them. Author policies through the typed authoring route at /api/v1/typed-policies instead. Reads on this endpoint are unaffected."
  }
}

The request is still validated first, so a malformed body, a missing required variable or an unknown template answers 400 or 404 as before; a well-formed apply answers 409. On a deployment that connects to its database as the owner (AXONFLOW_DB_USE_APP_ROLE=false) the revoke does not bind and apply still creates a row, which nothing the v11 engine decides reads.

Reading the catalog​

List templates​

Query paramPurpose
categoryFilter by category
searchSearch template names and descriptions
tagsComma-separated tags
activeFilter active templates
builtinFilter built-in templates
pagePage number
page_sizePage size, max 100

The response wraps the list:

{
  "templates": [],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 0,
    "total_pages": 0
  }
}

One template​

GET /api/v1/templates/{id} returns a template wrapper around the full template object: id, name, display_name, description, category, subcategory, the rule shape under template (name, type, conditions, actions, priority), its variables (name, type, default, description, required, validation), is_builtin, is_active, version, tags and timestamps. {{variable}} placeholders in the rule shape mark where a value was substituted at apply time in v10.x. Unknown template IDs return 404 with code NOT_FOUND.

GET /api/v1/templates/categories returns {"categories": [...]}, and GET /api/v1/templates/stats returns your tenant's stats: per-template usage_count and last_used_at from v10.x applies.

Last updated on