API Reference

Base URL

http://localhost:8002/api/v1

All endpoints except /health require JWT authentication via the Authorization: Bearer <token> header. Write operations on policies require the admin role.

Health

GET

/api/v1/health

Health check. No authentication required.

{
  "status": "healthy",
  "service": "anar-guard",
  "uptime_seconds": 3600
}

Governance

Evaluate Content

POST

/api/v1/governance/evaluate

Evaluate content against all active policies, content filters, and PII detection.

Request Body:

Field	Type	Required	Description
`content`	string	Yes	The text content to evaluate (max 100,000 chars)
`user_id`	string	No	User identifier for audit logging
`model`	string	No	Model identifier for audit logging
`context`	string	No	Context hint (e.g., "customer_chat")

curl -X POST http://localhost:8002/api/v1/governance/evaluate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Please diagnose my symptoms", "context": "chatbot"}'

Response:

Field	Type	Description
`allowed`	boolean	`false` when action is `block`, `true` otherwise
`action`	string	Escalated action: `pass`, `log`, `warn`, or `block`
`violations`	array	List of policy violations with policy ID, name, action, reason, and matched terms
`pii_detected`	array	List of PII entities found with type, value, start, and end offsets
`content_score`	float	Toxicity/restricted topic score (0.0 to 1.0, flagged at 0.3)
`redacted_content`	string	Content with PII replaced by `[REDACTED_TYPE]` markers (null if no PII)

Policies

List Policies

GET

/api/v1/policies

List governance policies with optional filtering.

Query Parameters:

Parameter	Type	Default	Description
`active_only`	boolean	`false`	Only return active policies
`skip`	integer	`0`	Pagination offset
`limit`	integer	`50`	Results per page (1-100)

Create Policy

POST

/api/v1/policies

Create a new policy. Requires admin role.

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Policy name (max 500 chars)
`description`	string	No	Policy description (max 5,000 chars)
`rule_type`	enum	Yes	`keyword`, `regex`, or `model-based`
`rule_config`	string	Yes	JSON-encoded rule configuration (max 50,000 chars)
`action`	enum	Yes	`block`, `warn`, or `log`
`is_active`	boolean	No	Whether the policy is active (default: `true`)

Keyword rule config:

{"keywords": ["diagnosis", "prescribe", "تشخيص"]}

Regex rule config:

{"patterns": ["(?:\\+|00)(?:971|966)\\d{8,10}"]}

Get Policy

GET

/api/v1/policies/{policy_id}

Get a specific policy by ID.

Update Policy

PUT

/api/v1/policies/{policy_id}

Update a policy. Requires admin role. Only include fields to change.

Delete Policy

DELETE

/api/v1/policies/{policy_id}

Delete a policy. Requires admin role.

Returns {"deleted": true} on success.

PII Detection

Detect PII

POST

/api/v1/pii/detect

Detect personally identifiable information in text.

Request Body:

Field	Type	Required	Description
`text`	string	Yes	Text to scan for PII (max 100,000 chars)

Response:

Field	Type	Description
`entities`	array	PII entities with `type`, `value`, `start`, `end`
`has_pii`	boolean	Whether any PII was detected

Redact PII

POST

/api/v1/pii/redact

Detect and replace PII with typed redaction markers.

Request Body:

Field	Type	Required	Description
`text`	string	Yes	Text to redact (max 100,000 chars)

Response:

Field	Type	Description
`original`	string	Original input text
`redacted`	string	Text with PII replaced by `[REDACTED_TYPE]`
`entities_redacted`	integer	Number of entities that were redacted

Safety

Check Safety

POST

/api/v1/safety/check

Classify content safety using Llama Guard 4 via Groq.

Request Body:

Field	Type	Required	Description
`text`	string	Yes	Text to classify (max 100,000 chars)
`scan_type`	string	No	`input` (default) or `output`

Response:

Field	Type	Description
`safe`	boolean	Whether the content is safe
`categories`	string[]	Violated category names (e.g., "Violent Crimes", "Hate")
`confidence`	float	1.0 for safe, 0.9 for unsafe, 0.0 when checks are skipped
`raw_response`	string	Raw model output for debugging

Monitoring

Get Metrics

GET

/api/v1/monitoring/metrics

Get aggregated metrics for a time period.

Query Parameters:

Parameter	Type	Default	Description
`days`	integer	`7`	Lookback period (1-90 days)

Response:

Field	Type	Description
`total_requests`	integer	Total monitored requests
`avg_latency_ms`	float	Average response latency
`error_rate`	float	Percentage of errors
`total_cost_usd`	float	Estimated total cost
`total_tokens`	integer	Total tokens consumed
`model_breakdown`	array	Per-model usage statistics
`daily_usage`	array	Day-by-day usage data

List Alerts (Legacy)

GET

/api/v1/monitoring/alerts

List alerts from the legacy alert system.

Resolve Alert (Legacy)

PUT

/api/v1/monitoring/alerts/{alert_id}/resolve

Resolve an alert. Requires admin role.

Alert Rules

Create Alert Rule

POST

/api/v1/alerts/rules

Create a new alert rule with metric, threshold, and optional webhook dispatch.

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Rule name
`metric`	string	Yes	Metric to monitor: `policy_violations`, `pii_detections`, `safety_blocks`, `critical_events`
`operator`	string	Yes	Comparison: `gt`, `gte`, `lt`, `lte`, `eq`
`threshold`	float	Yes	Threshold value
`window_minutes`	integer	Yes	Lookback window (1-10080 minutes)
`cooldown_minutes`	integer	No	Cooldown between firings (default: 60, range 1-10080)
`enabled`	boolean	No	Whether the rule is active (default: `true`)
`webhook_ids`	string[]	No	Webhook IDs to notify when triggered

curl -X POST http://localhost:8002/api/v1/alerts/rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High PII Detection Rate",
    "metric": "pii_detections",
    "operator": "gt",
    "threshold": 10,
    "window_minutes": 60,
    "cooldown_minutes": 120,
    "webhook_ids": ["wh-abc123"]
  }'

List Alert Rules

GET

/api/v1/alerts/rules

List configured alert rules.

Query Parameters: enabled_only, skip, limit

Update Alert Rule

PUT

/api/v1/alerts/rules/{rule_id}

Update an alert rule.

Delete Alert Rule

DELETE

/api/v1/alerts/rules/{rule_id}

Delete an alert rule.

List Triggered Alerts

GET

/api/v1/alerts

List triggered alerts with optional status filter.

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `triggered`, `acknowledged`, `resolved`
`limit`	integer	Results per page (1-500, default 50)

Acknowledge Alert

POST

/api/v1/alerts/{alert_id}/acknowledge

Acknowledge a triggered alert.

Webhooks

Create Webhook

POST

/api/v1/webhooks

Request Body:

Field	Type	Required	Description
`url`	string	Yes	Webhook endpoint URL
`events`	string[]	Yes	Event types to subscribe to (e.g., `["alert_triggered"]`)
`secret`	string	No	HMAC-SHA256 signing secret (auto-generated if omitted)

List Webhooks

GET

/api/v1/webhooks

List registered webhooks.

Delete Webhook

DELETE

/api/v1/webhooks/{webhook_id}

Delete a webhook registration.

Test Webhook

POST

/api/v1/webhooks/{webhook_id}/test

Send a test payload to verify webhook connectivity.

{
  "success": true,
  "status_code": 200,
  "error": null
}

Compliance Reports

List Frameworks

GET

/api/v1/compliance/reports/frameworks

List available compliance frameworks.

Generate Report

POST

/api/v1/compliance/reports/generate

Generate a new compliance report.

Request Body:

Field	Type	Required	Description
`framework_id`	string	Yes	Framework identifier (e.g., `uae_ai_ethics`)
`days`	integer	No	Assessment period in days (default: 30, range 1-365)

List Reports

GET

/api/v1/compliance/reports

List previously generated reports.

Query Parameters: framework_id, limit

Get Report

GET

/api/v1/compliance/reports/{report_id}

Get full report details including all sections.

Export Report

GET

/api/v1/compliance/reports/{report_id}/export

Export report in structured JSON format.

Diff Reports

GET

/api/v1/compliance/reports/{report_a_id}/diff/{report_b_id}

Compare two reports from the same framework.

Audit Trail

GET

/api/v1/audit/trail

Query the audit trail with filtering.

Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	`50`	Results per page (1-500)
`event_type`	string	None	Filter: `evaluation`, `safety_check`, `proxy_request`, `proxy_input_blocked`, `pii_detection`
`severity`	string	None	Filter: `info`, `warning`, `critical`
`user_id`	string	None	Filter by user identifier

curl "http://localhost:8002/api/v1/audit/trail?severity=critical&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Telemetry Ingestion

POST

/api/v1/telemetry/ingest

Ingest telemetry events from other Anar products. No JWT required.

Request Body:

Field	Type	Required	Description
`events`	array	Yes	Array of telemetry events (max 1000)
`events[].event_type`	string	No	Event type (default: `llm_call`)
`events[].product`	string	Yes	Source product name
`events[].model`	string	No	Model used
`events[].user_id`	string	No	User identifier
`events[].latency_ms`	float	No	Response latency
`events[].prompt_tokens`	integer	No	Prompt token count
`events[].completion_tokens`	integer	No	Completion token count
`events[].total_tokens`	integer	No	Total token count
`events[].content_snippet`	string	No	Content preview (max 1000 chars)
`events[].severity`	string	No	Event severity (default: `info`)
`events[].metadata`	object	No	Arbitrary metadata

curl -X POST http://localhost:8002/api/v1/telemetry/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "event_type": "llm_call",
      "product": "anar-chat",
      "model": "llama-3.3-70b-versatile",
      "latency_ms": 245.3,
      "total_tokens": 512,
      "severity": "info"
    }]
  }'

{"ingested": 1}

Guarded Proxy

POST

/api/v1/proxy/chat/completions

OpenAI-compatible chat completions with full input/output safety scanning.

Request Body: Standard OpenAI chat completion format with model, messages, temperature, max_tokens, and stream fields.

Response: Standard chat completion response with an additional safety object:

Field	Type	Description
`safety.input_safe`	boolean	Whether the input passed safety checks
`safety.input_categories`	string[]	Safety categories violated by input
`safety.output_safe`	boolean	Whether the output passed safety checks
`safety.output_categories`	string[]	Safety categories violated by output
`safety.pii_detected`	integer	Number of PII entities found in input
`safety.blocked`	boolean	Whether the request or response was blocked

Gateway Required

The proxy endpoint requires a running Gateway instance at the URL specified by GATEWAY_BASE_URL. If Gateway is unreachable, the proxy returns a 502 error.

Base URL#

Health#

Governance#

Evaluate Content#

Policies#

List Policies#

Create Policy#

Get Policy#

Update Policy#

Delete Policy#

PII Detection#

Detect PII#

Redact PII#

Safety#

Check Safety#

Monitoring#

Get Metrics#

List Alerts (Legacy)#

Resolve Alert (Legacy)#

Alert Rules#

Create Alert Rule#

List Alert Rules#

Update Alert Rule#

Delete Alert Rule#

List Triggered Alerts#

Acknowledge Alert#

Webhooks#

Create Webhook#

List Webhooks#

Delete Webhook#

Test Webhook#

Compliance Reports#

List Frameworks#

Generate Report#

List Reports#

Get Report#

Export Report#

Diff Reports#

Audit Trail#

Telemetry Ingestion#

Guarded Proxy#

Base URL

Health

Governance

Evaluate Content

Policies

List Policies

Create Policy

Get Policy

Update Policy

Delete Policy

PII Detection

Detect PII

Redact PII

Safety

Check Safety

Monitoring

Get Metrics

List Alerts (Legacy)

Resolve Alert (Legacy)

Alert Rules

Create Alert Rule

List Alert Rules

Update Alert Rule

Delete Alert Rule

List Triggered Alerts

Acknowledge Alert

Webhooks

Create Webhook

List Webhooks

Delete Webhook

Test Webhook

Compliance Reports

List Frameworks

Generate Report

List Reports

Get Report

Export Report

Diff Reports

Audit Trail

Telemetry Ingestion

Guarded Proxy