> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withperf.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies API

> Configure routing and content policies for governance and compliance

# Policies API

Policies allow you to control how Perf routes requests and handles content. Set model preferences, enforce cost limits, detect PII, and filter sensitive terms.

## Why Policies?

* **Cost Control**: Set budget limits and prefer cheaper models
* **Compliance**: Block specific providers or require certain models
* **Security**: Detect and redact PII from outputs
* **Governance**: Monitor and control content with term filtering

## Policy Types

| Type      | Description                       | Available Tiers               |
| --------- | --------------------------------- | ----------------------------- |
| `routing` | Model selection and routing rules | All tiers                     |
| `content` | PII detection and term filtering  | Pro, Growth, Team, Enterprise |

## Policy Templates API

Get pre-built policy templates to quickly enable common configurations.

### List Templates

```
GET https://api.withperf.pro/v1/policies/templates
```

**Response:**

```json theme={null}
{
  "templates": [
    {
      "slug": "budget-mode",
      "name": "Budget Mode",
      "description": "Aggressive cost optimization - prefer cheapest models",
      "category": "cost",
      "policy_type": "routing",
      "config": {
        "prefer_cheaper_models": true,
        "cost_ceiling_usd": 0.01
      }
    },
    {
      "slug": "pii-protection",
      "name": "PII Protection",
      "description": "Detect and redact PII from outputs",
      "category": "compliance",
      "policy_type": "content",
      "config": {
        "pii_detection": {
          "enabled": true,
          "types": ["ssn", "credit_card", "email"],
          "action": "redact"
        }
      }
    }
  ]
}
```

### Get Template by Slug

```
GET https://api.withperf.pro/v1/policies/templates/{slug}
```

**Example:**

```bash theme={null}
curl https://api.withperf.pro/v1/policies/templates/budget-mode \
  -H "Authorization: Bearer pk_live_abc123"
```

## Available Templates

### Routing Templates

| Template         | Slug               | Category    | Description                              |
| ---------------- | ------------------ | ----------- | ---------------------------------------- |
| Budget Mode      | `budget-mode`      | cost        | Prefer cheapest models, set cost ceiling |
| Performance Mode | `performance-mode` | performance | Optimize for low latency                 |
| Quality Mode     | `quality-mode`     | performance | Maximize output quality with best models |
| No OpenAI        | `no-openai`        | compliance  | Block all OpenAI models                  |
| No Anthropic     | `no-anthropic`     | compliance  | Block all Anthropic models               |
| Google Only      | `google-only`      | compliance  | Only use Google Gemini models            |

### Content Templates (Pro+)

| Template                   | Slug                         | Category   | Description                               |
| -------------------------- | ---------------------------- | ---------- | ----------------------------------------- |
| PII Protection             | `pii-protection`             | compliance | Detect and redact PII from outputs        |
| Healthcare Compliance      | `healthcare-compliance`      | compliance | Medical context awareness + PII detection |
| Child-Safe Content         | `child-safe`                 | compliance | Age-appropriate content enforcement       |
| Professional Communication | `professional-communication` | compliance | Business-appropriate tone                 |
| Custom Terms Filter        | `custom-terms-filter`        | compliance | Block or require specific terms           |

## Routing Policy Options

Configure how Perf selects models:

| Option                  | Type      | Description                                          |
| ----------------------- | --------- | ---------------------------------------------------- |
| `model_allow_list`      | string\[] | Only allow these specific models                     |
| `model_block_list`      | string\[] | Block these models from selection                    |
| `provider_allow_list`   | string\[] | Only use these providers (openai, anthropic, google) |
| `provider_block_list`   | string\[] | Block these providers                                |
| `cost_ceiling_usd`      | number    | Maximum cost per API call                            |
| `prefer_cheaper_models` | boolean   | Prefer lower-cost models when quality is similar     |
| `latency_target_ms`     | number    | Target maximum latency                               |
| `prefer_faster_models`  | boolean   | Prefer lower-latency models                          |
| `on_violation`          | string    | Action: `info`, `warn`, `soft_block`, `hard_block`   |

**Example - Google Only Policy:**

```json theme={null}
{
  "name": "Google Only",
  "policy_type": "routing",
  "config": {
    "provider_allow_list": ["google"],
    "on_violation": "hard_block"
  }
}
```

## Content Policy Options

Configure content filtering and PII detection:

| Option                           | Type      | Description                            |
| -------------------------------- | --------- | -------------------------------------- |
| `evaluate_output`                | boolean   | Evaluate model output (default: true)  |
| `pii_detection.enabled`          | boolean   | Enable PII detection                   |
| `pii_detection.types`            | string\[] | PII types to detect                    |
| `pii_detection.action`           | string    | Action: `warn`, `redact`, `block`      |
| `pii_detection.redaction_format` | string    | Redaction text (default: `[REDACTED]`) |
| `blocked_terms.enabled`          | boolean   | Enable blocked term detection          |
| `blocked_terms.terms`            | string\[] | List of terms to block                 |
| `blocked_terms.action`           | string    | Action: `warn`, `redact`, `block`      |
| `on_violation`                   | string    | Overall violation action               |

**Example - PII Protection Policy:**

```json theme={null}
{
  "name": "PII Protection",
  "policy_type": "content",
  "config": {
    "evaluate_output": true,
    "pii_detection": {
      "enabled": true,
      "types": ["ssn", "credit_card", "email", "phone_us"],
      "action": "redact",
      "redaction_format": "[REDACTED]"
    },
    "on_violation": "soft_block"
  }
}
```

## Supported PII Types

| Type            | Pattern                                   | Description                         |
| --------------- | ----------------------------------------- | ----------------------------------- |
| `ssn`           | XXX-XX-XXXX                               | Social Security Numbers             |
| `ssn_no_dash`   | XXXXXXXXX                                 | SSN without dashes                  |
| `credit_card`   | 13-19 digits                              | Credit cards (with Luhn validation) |
| `email`         | [user@domain.com](mailto:user@domain.com) | Email addresses                     |
| `phone_us`      | (XXX) XXX-XXXX                            | US phone numbers                    |
| `ip_address`    | X.X.X.X                                   | IPv4 addresses                      |
| `date_of_birth` | MM/DD/YYYY                                | Dates of birth                      |

## Violation Actions

| Action       | Description                                                         |
| ------------ | ------------------------------------------------------------------- |
| `info`       | Log only (audit mode) - request proceeds                            |
| `warn`       | Log warning - request proceeds with warning in response             |
| `soft_block` | Apply modifications (redact PII, override model) - request proceeds |
| `hard_block` | Reject request with 403 error                                       |

## Policy Blocked Response

When a request is blocked by a `hard_block` policy:

```json theme={null}
{
  "error": "Request blocked by policy",
  "code": "POLICY_BLOCKED",
  "message": "Request blocked by policy: Model gpt-4o-mini is not in allow list",
  "policy_evaluation": {
    "result": "hard_block",
    "violations": [
      {
        "policy_name": "Google Only",
        "rule": "model_allow_list",
        "message": "Model gpt-4o-mini is not in allow list"
      }
    ]
  }
}
```

## Managing Policies via Dashboard

Policies are configured per-project in the Perf Dashboard:

1. Navigate to **Configure > Policies**
2. Click **Create Policy** or **Apply Template**
3. Configure rules and violation actions
4. Set priority (lower number = higher priority)
5. Enable the policy

Multiple policies can be active simultaneously. They are evaluated in priority order.

## Plan Limits

| Tier       | Max Policies | Policy Types     |
| ---------- | ------------ | ---------------- |
| Starter    | 3            | routing          |
| Pro        | 10           | routing, content |
| Growth     | 25           | routing, content |
| Team       | 50           | routing, content |
| Enterprise | 1000         | all types        |

## Related

* [Chat API](./chat) - See policy evaluation in responses
* [Schema Enforcement](./schemas) - Validate JSON output structure