API Reference

This page covers the public Action Guard HTTP API. Where a deployment exposes interactive docs, you can also browse them at:

OpenAPI JSON: GET /openapi.json
Swagger UI: GET /docs
ReDoc: GET /redoc

Authentication

Action Guard accepts either of:

JWT (Bearer): Authorization: Bearer <jwt>
API key: X-API-Key: <api_key> (format: sk-vai-...)

Endpoint Group	Accepts
Action evaluation (`/api/v1/guard_actions`)	JWT or API key
Logs (`/api/v1/logs`)	JWT only
Policy management (`/api/v1/policies/*`)	JWT or API key

Action Evaluation

`POST /api/v1/guard_actions`

Evaluate agent action safety based on the agent interaction history in a session and the configured policies. Each call performs one evaluation of the current action and saves a log entry for the request.

Request:

{
  "session_history": {
    "session_info": {
      "gateway_id": "gw_abc123",
      "metadata": {
        "step_count": 5,
        "actions_count": 2,
        "tool_count": 1
      }
    },
    "trace": [
      {
        "role": "user",
        "content": "Create a lead for John Doe",
        "step_id": 0
      },
      {
        "role": "agent",
        "action": "create_lead(name='John Doe', email='john@example.com')",
        "step_id": 1,
        "metadata": {
          "tool_name": "create_lead",
          "tool_params": { "name": "John Doe", "email": "john@example.com" },
          "server_name": "salesforce",
          "server_id": "srv_123"
        }
      }
    ]
  },
  "session_id": "session_123",
  "policy_id": "agp_4d59ef9c...",
  "fast_mode": false,
  "blocking_config": {
    "blocking_mode": "severity_level",
    "blocking_level": "High"
  }
}

Field	Type	Required	Description
`session_history`	object	Yes	Full session trace including `session_info` and `trace`
`session_id`	string	Yes	Session identifier (e.g. `session_123`)
`policy_id`	string	Yes	Policy set identifier (e.g. `agp_4d59ef9c...`)
`fast_mode`	boolean	No (default `false`)	Reduce token usage at the cost of some accuracy
`blocking_config`	object	No	Override the policy file's blocking configuration
`blocking_config.blocking_mode`	string	—	`strict` / `severity_level` / `rule_threshold`
`blocking_config.blocking_level`	string	—	`High` / `Medium` / `Low` — used with `severity_level` mode
`blocking_config.blocking_threshold`	float	—	`0.0–1.0` — used with `rule_threshold` mode

Response:

{
  "allowed": true,
  "violations": [],
  "warnings": ["Category → Policy → Rule rul_xxx: potential PII in email field"],
  "violations_detail": [],
  "warnings_detail": [
    {
      "rule_id": "rul_xxx",
      "description": "potential PII in email field",
      "severity": "Low",
      "category": "Data Privacy",
      "policy_set": "My Policy Set",
      "policy_id": "pol_yyy",
      "action": "allow",
      "notify_emails": []
    }
  ],
  "violations_count": 0,
  "warnings_count": 1,
  "threat_category": "none",
  "explanation": "The action is within the agent's permitted scope.",
  "blocking_mode": "severity_level",
  "blocking_metadata": {
    "blocking_level": "High",
    "highest_violation_severity": "Low"
  },
  "session_id": "session_123",
  "timestamp": "2026-05-19T10:30:00Z",
  "service_status": "operational",
  "user_id": "usr_abc123",
  "observation": "User asked to create a lead for John Doe.",
  "action": "create_lead(name='John Doe', email='john@example.com')",
  "fast_mode": false,
  "total_enabled_rules": 12,
  "active_policies": ["Data Privacy", "Financial Controls"]
}

Field	Description
`allowed`	Whether the action is permitted
`violations`	Display-formatted strings for blocking violations
`warnings`	Display-formatted strings for sub-threshold violations
`violations_detail`	Rich violation objects (see shape below)
`warnings_detail`	Rich warning objects (same shape as `violations_detail`)
`violations_count`	Number of blocking violations
`warnings_count`	Number of warning-level violations
`threat_category`	Detected threat category (`none` when allowed)
`explanation`	Human-readable explanation of the decision
`blocking_mode`	Blocking mode that was applied
`blocking_metadata`	Extra metadata about the blocking decision
`total_enabled_rules`	Number of enabled rules evaluated
`active_policies`	Names of active policies in the policy set

violations_detail / warnings_detail item shape:

Field	Description
`rule_id`	Rule identifier (e.g. `rul_xxx`)
`description`	Rule description
`severity`	`High` / `Medium` / `Low`
`category`	Policy category name
`policy_set`	Policy set name
`policy_id`	Policy identifier
`action`	Per-rule action: `deny` / `ask` / `allow`
`notify_emails`	List of emails to notify when this rule fires

Logs

`GET /api/v1/logs`

Retrieve Action Guard evaluation logs and aggregated statistics. Requires JWT.

Non-admin users always see only their own logs. Admins may omit user_id to see all users.

Query parameters:

Parameter	Type	Default	Description
`start_date`	string	—	ISO 8601 datetime — filter logs from this point
`end_date`	string	—	ISO 8601 datetime — filter logs up to this point
`limit`	int	`100`	Maximum logs to return (`0` for no limit)
`stats_only`	boolean	`false`	Return only statistics, not individual log entries
`session_id`	string	—	Filter by session ID
`gateway_ids`	string	—	Filter by gateway IDs (comma-separated)
`user_id`	string	—	Filter by user ID (admins only for other users)

Response (with stats_only=false):

{
  "logs": [
    {
      "session_id": "session_123",
      "gateway_id": "gw_abc123",
      "tool_name": "create_lead",
      "tool_params": { "name": "John Doe" },
      "server_name": "salesforce",
      "allowed": true,
      "violations_count": 0,
      "threat_category": "none",
      "timestamp": "2026-05-19T10:30:00Z"
    }
  ],
  "stats": {
    "total_evaluations": 1240,
    "total_violations": 37,
    "total_allowed": 1203,
    "violations_last_day": 5,
    "violations_last_hour": 1,
    "unique_sessions": 88,
    "active_sessions_last_hour": 4,
    "violation_categories": { "Data Privacy": 20, "Financial Controls": 17 },
    "threat_categories": { "injection": 12, "exfiltration": 25 },
    "approval_rate": 0.97,
    "evaluations_last_hour": 43,
    "evaluations_last_day": 310
  },
  "total": 1240,
  "timestamp": "2026-05-19T10:35:00Z"
}

Response (with stats_only=true):

{
  "stats": { ... },
  "timestamp": "2026-05-19T10:35:00Z"
}

Policy Management

All policy management endpoints accept JWT or an API key.

Templates

Templates are preset, read-only policy configurations available to all users.

`GET /api/v1/policies/templates`

List all preset policy templates.

Response:

{
  "templates": [
    {
      "id": "tmpl_eu_ai_act",
      "name": "EU AI Act",
      "description": "Enforcement rules derived from the EU AI Act.",
      "category": "Regulatory"
    }
  ],
  "total": 5
}

`GET /api/v1/policies/templates/{template_id}`

Get a specific preset template by ID.

Policy Sets

A policy set bundles one or more individual policies and is referenced by policy_id when calling /api/v1/guard_actions.

`GET /api/v1/policies/sets`

List all active policy sets owned by the current user.

Response:

{
  "policy_sets": [
    {
      "id": "agp_4d59ef9c...",
      "name": "Customer Support Guardrails",
      "policy_count": 3,
      "created_at": "2026-04-01T08:00:00Z"
    }
  ],
  "total": 1
}

`POST /api/v1/policies/sets`

Create a new policy set.

Request:

{
  "name": "Customer Support Guardrails",
  "policy_ids": ["pol_abc", "pol_def"]
}

Field	Type	Required	Description
`name`	string	Yes	Policy set name
`policy_ids`	array	No	IDs of existing policies to include

Response:

{
  "success": true,
  "policy_id": "agp_4d59ef9c...",
  "name": "Customer Support Guardrails",
  "message": "Policy set created successfully",
  "policy_count": 2
}

`GET /api/v1/policies/sets/{policy_set_id}`

Get a specific policy set with full policy details.

`PUT /api/v1/policies/sets/{policy_set_id}`

Update a policy set's name and/or enabled policy configuration.

Request:

{
  "name": "Updated Name",
  "policies": {
    "pol_abc": { "enabled": true },
    "pol_def": { "enabled": false }
  }
}

`DELETE /api/v1/policies/sets/{policy_set_id}`

Soft-delete a policy set and all its associated policies.

`POST /api/v1/policies/sets/{policy_set_id}/policies`

Add existing policies to a policy set.

Request:

{
  "policy_ids": ["pol_ghi", "pol_jkl"]
}

Response:

{
  "success": true,
  "message": "Added 2 policies to policy set",
  "added_policy_ids": ["pol_ghi", "pol_jkl"]
}

Individual Policies

`GET /api/v1/policies/policy`

List all active policies owned by the current user.

Response:

{
  "policies": [
    {
      "id": "pol_abc",
      "name": "Financial Controls",
      "description": "Restrict unauthorized financial operations.",
      "category": "User Rules",
      "rules": {
        "rul_001": { "description": "Block wire transfers above $10,000", "severity": "High" }
      }
    }
  ],
  "total": 1
}

`GET /api/v1/policies/policy/{policy_id}`

Get a specific policy by ID.

`POST /api/v1/policies/policy`

Create a new custom policy.

Request:

{
  "name": "Financial Controls",
  "description": "Restrict unauthorized financial operations.",
  "category": "User Rules",
  "rules": {
    "rul_001": {
      "description": "Block wire transfers above $10,000",
      "severity": "High"
    }
  }
}

Field	Type	Default	Description
`name`	string	required	Policy name
`description`	string	`""`	Optional description
`category`	string	`"User Rules"`	Policy category
`rules`	object	`{}`	Map of rule key → `{description, severity}`
`rules[*].severity`	string	`"Medium"`	`High` / `Medium` / `Low`

Response:

{
  "success": true,
  "policy_id": "pol_abc",
  "message": "Policy created successfully"
}

`PUT /api/v1/policies/policy/{policy_id}`

Update a policy. Only provided fields are changed.

Request:

{
  "name": "Updated Name",
  "description": "Updated description.",
  "category": "User Rules",
  "rules": {
    "rul_001": { "description": "Updated rule text", "severity": "Medium" }
  }
}

`DELETE /api/v1/policies/policy/{policy_id}`

Soft-delete a policy.

Rule Extraction

Extract policy rules from unstructured text or documents using AI. Extractions run as background jobs to avoid gateway timeouts.

`POST /api/v1/policies/extract-rules-async`

Start async rule extraction from plain text. Returns a job_id immediately.

Request: multipart/form-data

Field	Type	Required	Description
`text`	string	Yes	Policy document text to extract rules from
`policy_name`	string	No (default `"Untitled Policy"`)	Name for the generated policy
`category`	string	No (default `"User Rules"`)	Category for the generated policy

Response:

{
  "job_id": "job_a1b2c3",
  "status": "pending"
}

`POST /api/v1/policies/extract-rules-from-pdf-async`

Start async rule extraction from uploaded files. Returns a job_id immediately. Accepted file types: .pdf, .txt, .md.

Request: multipart/form-data

Field	Type	Required	Description
`files`	file[]	Yes	One or more PDF, TXT, or MD files
`policy_name`	string	No (default `"Untitled Policy"`)	Name for the generated policy
`category`	string	No (default `"User Rules"`)	Category for the generated policy

Response:

{
  "job_id": "job_a1b2c3",
  "status": "pending"
}

`GET /api/v1/policies/extraction-jobs/{job_id}`

Poll for the status and result of an extraction job.

Response (pending):

{
  "job_id": "job_a1b2c3",
  "status": "pending",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:01Z"
}

Response (completed):

{
  "job_id": "job_a1b2c3",
  "status": "completed",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:15Z",
  "result": {
    "policy_name": "My Extracted Policy",
    "category": "User Rules",
    "rules": {
      "rul_001": { "description": "Block sharing of customer PII externally", "severity": "High" }
    },
    "rule_count": 1,
    "total_files": 2,
    "successful_files": 2,
    "failed_files": []
  }
}

Response (failed):

{
  "job_id": "job_a1b2c3",
  "status": "failed",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:10Z",
  "error": "No valid content could be extracted from any files"
}

Health

`GET /healthz`

No authentication required.

{
  "status": "healthy",
  "service": "Action Guard Service",
  "version": "1.0.0",
  "timestamp": "2026-05-19T10:30:00Z",
  "openai_available": true,
  "features": ["policy_evaluation", "fast_mode", "async_extraction"]
}

Authentication​

Action Evaluation​

POST /api/v1/guard_actions​

Logs​

GET /api/v1/logs​

Policy Management​

Templates​

GET /api/v1/policies/templates​

GET /api/v1/policies/templates/{template_id}​

Policy Sets​

GET /api/v1/policies/sets​

POST /api/v1/policies/sets​

GET /api/v1/policies/sets/{policy_set_id}​

PUT /api/v1/policies/sets/{policy_set_id}​

DELETE /api/v1/policies/sets/{policy_set_id}​

POST /api/v1/policies/sets/{policy_set_id}/policies​

Individual Policies​

GET /api/v1/policies/policy​

GET /api/v1/policies/policy/{policy_id}​

POST /api/v1/policies/policy​

PUT /api/v1/policies/policy/{policy_id}​

DELETE /api/v1/policies/policy/{policy_id}​

Rule Extraction​

POST /api/v1/policies/extract-rules-async​

POST /api/v1/policies/extract-rules-from-pdf-async​

GET /api/v1/policies/extraction-jobs/{job_id}​

Health​

GET /healthz​

Authentication

Action Evaluation

`POST /api/v1/guard_actions`

Logs

`GET /api/v1/logs`

Policy Management

Templates

`GET /api/v1/policies/templates`

`GET /api/v1/policies/templates/{template_id}`

Policy Sets

`GET /api/v1/policies/sets`

`POST /api/v1/policies/sets`

`GET /api/v1/policies/sets/{policy_set_id}`

`PUT /api/v1/policies/sets/{policy_set_id}`

`DELETE /api/v1/policies/sets/{policy_set_id}`

`POST /api/v1/policies/sets/{policy_set_id}/policies`

Individual Policies

`GET /api/v1/policies/policy`

`GET /api/v1/policies/policy/{policy_id}`

`POST /api/v1/policies/policy`

`PUT /api/v1/policies/policy/{policy_id}`

`DELETE /api/v1/policies/policy/{policy_id}`

Rule Extraction

`POST /api/v1/policies/extract-rules-async`

`POST /api/v1/policies/extract-rules-from-pdf-async`

`GET /api/v1/policies/extraction-jobs/{job_id}`

Health

`GET /healthz`