> ## 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/sanitize

> Strip PII from text before sending to external LLMs

## Authentication

```
X-API-Key: am_live_your_key_here
```

## Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `text` | string | Yes | Text to sanitize (max 100KB) |
| `mode` | string | No | `"sanitize"` (default) or `"redact"`. Redact mode permanently removes PII and returns `session_id: null`. |
| `config.entities` | array | No | Entity types to detect (default: all). See entity types below. |
| `config.confidence_threshold` | float | No | Minimum confidence score to include a detection (default: 0.0) |
| `config.custom_patterns` | boolean | No | Include org's custom patterns (default: false) |
| `config.storage_overrides` | object | No | Per-entity storage tier overrides (e.g., `{"SSN": 1}` for never-store) |

### Example Request

```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": "Email John Smith at john@acme.com about the NYC merger",
    "config": {"entities": ["PERSON", "EMAIL_ADDRESS", "LOCATION"]}
  }'
```

## Response

| Field | Type | Description |
| - | - | - |
| `sanitized` | string | Text with PII replaced by placeholders |
| `session_id` | string\|null | ID for rehydration (valid 24 hours). `null` when `mode="redact"`. |
| `redacted` | boolean | `true` if redact mode was used |
| `entities_found` | integer | Number of entities detected |
| `entities` | array | Details of each detected entity (see below) |
| `metadata` | object | Processing metadata including `format_type` and `disambiguation_applied` |
| `processing_ms` | float | Processing time in milliseconds |

### Entity Object

| Field | Type | Description |
| - | - | - |
| `placeholder` | string | The replacement token, e.g. `[PERSON_1]` |
| `type` | string | Entity type (see Entity Types below) |
| `confidence` | float | Detection confidence score (0.0 to 1.0) |
| `start` | integer | Start character offset in the original text |
| `end` | integer | End character offset in the original text |
| `structure` | object\|null | Structural context: `region_type`, `label`, `line` |

### Example Response

```json theme={null}
{
  "sanitized": "Email [PERSON_1] at [EMAIL_ADDRESS_1] about the [LOCATION_1] merger",
  "session_id": "ses_a1b2c3d4e5f6",
  "redacted": false,
  "entities_found": 3,
  "entities": [
    {
      "placeholder": "[PERSON_1]",
      "type": "PERSON",
      "confidence": 0.97,
      "start": 6,
      "end": 16,
      "structure": null
    },
    {
      "placeholder": "[EMAIL_ADDRESS_1]",
      "type": "EMAIL_ADDRESS",
      "confidence": 0.99,
      "start": 20,
      "end": 33,
      "structure": null
    },
    {
      "placeholder": "[LOCATION_1]",
      "type": "LOCATION",
      "confidence": 0.92,
      "start": 44,
      "end": 47,
      "structure": null
    }
  ],
  "metadata": {
    "format_type": "plain_prose",
    "disambiguation_applied": false
  },
  "processing_ms": 14.2
}
```

## Redact Mode

Set `mode: "redact"` to permanently remove PII. Redacted responses cannot be rehydrated.

```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": "Email john@acme.com", "mode": "redact"}'
```

Response will have `"session_id": null` and `"redacted": true`.

## Entity Types

| Type | Description | Detection | Examples |
| - | - | - | - |
| `PERSON` | Names of people | NER + patterns | John Smith, Dr. Jane Doe |
| `EMAIL_ADDRESS` | Email addresses | Regex + validation | [john@acme.com](mailto:john@acme.com) |
| `PHONE_NUMBER` | Phone numbers | Multi-format regex | (555) 123-4567 |
| `SSN` | Social Security Numbers | Regex + checksum | 123-45-6789 |
| `CREDIT_CARD` | Credit card numbers | Regex + Luhn | 4532-1234-5678-9012 |
| `LOCATION` | Places, cities | NER | NYC, San Francisco |
| `ADDRESS` | Physical addresses | Regex + NER | 123 Main St, Suite 200 |
| `NPI` | National Provider Identifier | Regex + Luhn (10-digit) | 1234567890 |
| `DEA_NUMBER` | DEA Registration Number | Regex + checksum | AB1234567 |
| `MRN` | Medical Record Number | Context-aware regex | MRN-12345678 |

<Note>
  `EMAIL` and `PHONE` are accepted as aliases for `EMAIL_ADDRESS` and `PHONE_NUMBER` in the `config.entities` array.
</Note>

## Errors

| Code | HTTP Status | Description |
| - | - | - |
| `invalid_api_key` | 401 | API key is missing or invalid |
| `empty_text` | 400 | Text field is empty |
| `text_too_large` | 413 | Text exceeds 100KB limit |
| `rate_limited` | 429 | Too many requests |

[View all error codes](/api-reference/errors)


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