Guardian Health LogoGuardian Health
Safe AI Workbench Developer Docs

Policies API

Create and manage PHI detection policies for your organization

Overview

The Policies API allows administrators to create, update, and manage PHI detection policies that control how the AI assistant handles Protected Health Information. Policies can be scoped to organizations, groups, or individual users with different priority levels and enforcement actions.

Get All Policies

GET /api/admin/policies

Returns all policies for the authenticated user's organization.

Request Headers

Authorization: Bearer YOUR_JWT_TOKEN

Response

[
  {
    "id": "policy-uuid",
    "org_id": "org-uuid",
    "policy_name": "Default PHI Detection",
    "policy_type": "phi_detection",
    "scope": "organization",
    "scope_id": null,
    "priority": 10,
    "rules": {
      "action": "block",
      "entities": ["PERSON", "PHONE_NUMBER", "EMAIL_ADDRESS", "US_SSN"]
    },
    "allowed_models": ["gpt-4", "gpt-4-turbo"],
    "default_model": "gpt-4",
    "model_fallback": "gpt-3.5-turbo",
    "retention_days": 30,
    "require_approval": false,
    "alert_on_trigger": true,
    "enabled": true,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
]

Get Policy by ID

GET /api/admin/policies/:id

Returns a specific policy by ID. User must belong to the same organization or be a site admin.

Path Parameters

id— Policy UUID

Response

{
  "id": "policy-uuid",
  "org_id": "org-uuid",
  "policy_name": "Default PHI Detection",
  "policy_type": "phi_detection",
  "scope": "organization",
  "priority": 10,
  "rules": {
    "action": "block",
    "entities": ["PERSON", "PHONE_NUMBER", "EMAIL_ADDRESS"]
  },
  "enabled": true
}

Create Policy

POST /api/admin/policies

Creates a new policy for your organization. Requires admin or manager role.

Request Body

{
  "policy_name": "Block All PHI",
  "policy_type": "phi_detection",
  "scope": "organization",
  "scope_id": null,
  "priority": 10,
  "rules": {
    "action": "block",
    "entities": ["PERSON", "PHONE_NUMBER", "EMAIL_ADDRESS", "US_SSN"],
    "threshold": 0.8
  },
  "allowed_models": ["gpt-4", "gpt-4-turbo"],
  "default_model": "gpt-4",
  "retention_days": 30,
  "require_approval": false,
  "alert_on_trigger": true,
  "enabled": true
}

Policy Fields

policy_type— Type of policy
Options: phi_detection, content_filter, rate_limit
scope— Policy scope
Options: organization, group, user
rules.action— Enforcement action
Options: block, warn, redact, allow
priority— Policy priority (higher = evaluated first)

Response

{
  "id": "new-policy-uuid",
  "org_id": "org-uuid",
  "policy_name": "Block All PHI",
  "policy_type": "phi_detection",
  "scope": "organization",
  "priority": 10,
  "rules": {
    "action": "block",
    "entities": ["PERSON", "PHONE_NUMBER", "EMAIL_ADDRESS", "US_SSN"]
  },
  "enabled": true,
  "created_at": "2025-01-15T10:30:00Z"
}

Update Policy

PUT /api/admin/policies/:id

Updates an existing policy. Only modifiable fields need to be included.

Request Body

{
  "enabled": false,
  "rules": {
    "action": "warn",
    "entities": ["PERSON", "PHONE_NUMBER"]
  }
}

Policy Evaluation

Policies are evaluated in priority order (highest first). The first matching policy determines the action taken:

Evaluation Flow

  1. User sends message to AI
  2. Presidio scans for PHI entities
  3. Policies evaluated by priority (user → group → organization)
  4. First matching policy action applied:
    • block — Request rejected, PHI details logged
    • warn — Request processed, warning shown to user
    • redact — PHI replaced with placeholders, request processed
    • allow — Request processed with PHI intact (audit logged)

Error Codes

401 Unauthorized

Missing or invalid authentication token

403 Forbidden

Insufficient permissions (requires admin/manager role)

404 Not Found

Policy not found

400 Bad Request

Invalid policy data or missing required fields