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

# POST /v1/patterns

> Create custom entity patterns for your organization

## Why Custom Patterns?

Standard entities cover names, emails, etc. Custom patterns let you detect org-specific data like employee IDs (`EMP-123456`), project codes, internal account numbers, or any custom identifier.

## Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Pattern name (e.g., "EMPLOYEE\_ID") |
| `pattern` | string | Yes | Regex pattern to match |
| `description` | string | No | Human-readable description |
| `examples` | array | No | Example matches for validation |

### Example Request

```bash theme={null}
curl -X POST https://api.ambientmeta.com/v1/patterns \
  -H "X-API-Key: am_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EMPLOYEE_ID",
    "pattern": "EMP-[0-9]{6}",
    "description": "Internal employee identifier",
    "examples": ["EMP-123456", "EMP-789012"]
  }'
```

## Response

| Field | Type | Description |
| - | - | - |
| `pattern_id` | string | Unique pattern identifier |
| `name` | string | Pattern name |
| `status` | string | Pattern status (`"active"`) |
| `analysis` | object\|null | Overlap and quality analysis (see below) |
| `conflict` | object\|null | Conflict details if overlaps are detected |

### Example Response

```json theme={null}
{
  "pattern_id": "pat_xyz789",
  "name": "EMPLOYEE_ID",
  "status": "active",
  "analysis": {
    "overlaps_with": [],
    "overlap_count": 0,
    "contradiction_risk": "low",
    "golden_set_coverage": 0,
    "suggested_improvements": []
  },
  "conflict": null
}
```

### Response with Conflict

If the new pattern overlaps with existing entity detections, the response includes a `conflict` block:

```json theme={null}
{
  "pattern_id": "pat_abc123",
  "name": "ACCOUNT_NUMBER",
  "status": "active",
  "analysis": {
    "overlaps_with": ["PHONE_NUMBER"],
    "overlap_count": 23,
    "contradiction_risk": "medium",
    "golden_set_coverage": 0,
    "suggested_improvements": []
  },
  "conflict": {
    "has_conflict": true,
    "conflicting_spans": 23,
    "conflicting_type": "PHONE_NUMBER",
    "resolution_required": true,
    "resolution_options": [
      {"option": "reclassify_all", "description": "Reclassify all 23 spans as ACCOUNT_NUMBER"},
      {"option": "add_context_condition", "description": "Add context rule to distinguish"},
      {"option": "refine_pattern", "description": "Narrow the pattern to avoid overlap"}
    ],
    "insight_id": "ins_abc"
  }
}
```

<Info>
  When a conflict is detected, an insight is automatically created. Use the [Insights API](/api-reference/insights) to resolve it.
</Info>

## Using Custom Patterns

Once created, custom patterns are automatically included in sanitization when `config.custom_patterns` is set to `true` in the request body:

```bash theme={null}
curl -X POST https://api.ambientmeta.com/v1/sanitize \
  -H "X-API-Key: am_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Contact EMP-123456 about the project",
    "config": {"custom_patterns": true}
  }'
```

Response:

```json theme={null}
{
  "sanitized": "Contact [EMPLOYEE_ID_1] about the project",
  "session_id": "ses_...",
  "entities_found": 1
}
```

## List Patterns

`GET /v1/patterns` returns all patterns for your organization.

## Delete Patterns

`DELETE /v1/patterns/{pattern_id}` removes a pattern.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.