The HTTP admin API

A read/config HTTP API for an admin panel (e.g. laravel-ai-guardrails-admin). It is default-OFF.

Turn it on — safely

// config/ai-guardrails.php
'api' => [
    'enabled'    => true,
    'prefix'     => 'ai-guardrails/api',
    'middleware' => ['auth:sanctum'], // YOU must supply auth — these endpoints expose audit data
],

The envelope

Every response is { "schema_version": "ai-guardrails.api.v1", "schema": "ai-guardrails.api.v1.endpoint_name", "data": { ... } }. schema_version is the contract a client pins; schema is a per-endpoint discriminator. Routes are named ai-guardrails.api.*.

Endpoints

Untrusted query params

The list endpoints treat every query param as untrusted: keyset cursors are parsed as strictly-positive integers, LIKE metacharacters are escaped, dates are strict ISO-8601, repeated array params are ignored rather than 500-ing, and stored text is mb_scrub-bed before JSON encoding.

---

GET /overview — v1.1.0 additions

The /overview response adds the following fields (backward-compatible — v1.0 fields are unchanged):

controls[].posture (string)

Human-readable posture label derived from the control’s effective mode and enabled state:

controls[].spark (int[12])

Twelve-bucket hourly histogram for the trailing 12 hours. Bucket 11 = current UTC hour, bucket 0 = 11 hours ago. All values are non-negative integers.

totals.observed_24h (int)

Count of injection attempts in the last 24 hours where blocked = false AND rule_id IS NOT NULL — i.e. monitor-mode observations (rule matched but not blocked). Complements the existing blocked_24h counter.

totals.pending_approvals (int)

Count of currently pending HITL approvals (requires laravel-flow). Returns 0 when HITL is unavailable.

---

GET /audit/trend — v1.1.0 additions

Each point in data.points[] now carries an observed bucket alongside the existing date, total, blocked, and allowed fields.

points[].observed (int)

Count of attempts on that day where blocked = false AND rule_id IS NOT NULL — monitor-mode matches that were detected but not blocked. observed is a subset of allowed (observed ⊆ allowed); it is additive information and does not change the meaning of any existing field.

Invariant

The v1.0 invariant is preserved: for every point total === blocked + allowed.

• allowed retains its v1.0 meaning: every attempt that was not blocked, regardless of whether a rule matched. This means monitor-mode rows (rule matched, not blocked) are included in allowed, exactly as they were before v1.1.0.
• observed is a new, purely additive field: the subset of allowed rows where a rule matched (blocked = false AND rule_id IS NOT NULL). Consumers that only need a disjoint “no rule matched at all” series can compute it as allowed - observed.

The degenerate row blocked = true, rule_id = null counts as blocked only (never as allowed). The invariant total === blocked + allowed holds for all rows.

---

GET /output/stats — v1.1.0 additions

counts.pii.by_detector (object — string keys to int values)

Breaks down counts.pii_redaction by the detector that fired. Keys are detector names (e.g. "email", "phone", "ssn"); values are the summed redaction counts for that detector. When no per-detector data exists (e.g. the store has no PII rows, or they were recorded without a detector tag), the field is an empty object {}.

This field is additive — counts.pii_redaction (the total) is unchanged.

{
  "counts": {
    "html_stripped": 2,
    "markdown_sanitized": 0,
    "structured_validation_failure": 0,
    "pii_redaction": 5,
    "pii": {
      "by_detector": { "email": 3, "phone": 2 }
    }
  },
  "total": 7
}

---

GET /approvals — v1.1.0 additions

Each pending[] item now carries four enrichment fields in addition to the base flow fields (approval_id, run_id, step_name, status, expires_at, created_at):

Raw arguments — by design

The arguments field exposes the scoped tool arguments verbatim. This is intentional: an approver must see exactly what will execute when they approve. The sidecar (ai_guardrails_hitl_requests) is append-only and covered by ai-guardrails:purge for GDPR erasure — see audit hygiene & retention.

Sidecar availability

The sidecar is default-OFF (hitl_requests.store = null). Enable array or database to populate tool/arguments. When no sidecar row exists for a run_id, the item degrades gracefully: tool: "", arguments: {}. The sidecar write is best-effort — a logging failure never un-parks or errors an already-parked approval.

---

Overridable settings

PUT /settings only accepts keys on the settings.overridable allow-list, each strictly type-validated as untrusted input — a malformed value rejects the whole request (422); a non-overridable key is silently dropped (forward-compatible). GET /settings returns the effective value (file default overlaid with any DB override) for every allow-listed key.

Read-only (infra) keys

The following keys are not overridable at runtime — they are config/env-only and are silently dropped from a PUT body:

• audit.store, audit.table, audit.connection
• firewall_log.store, firewall_log.table, firewall_log.connection
• output_stats.store, output_stats.table, output_stats.connection
• settings.store, settings.table, settings.connection
• settings_audit.store, settings_audit.table, settings_audit.connection
• hitl_requests.store, hitl_requests.table, hitl_requests.connection

These keys affect database routing and must be set via environment variables — changing them at runtime could corrupt data or split the audit trail across stores.

Settings audit

PUT /settings records every effective change (before ≠ after) to the settings_audit store with the server-derived actor (never client-supplied) and dispatches SettingsChanged. GET /settings/changes lists them.