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

# REST API Reference

> Complete HTTP API documentation for Blindfold

The Blindfold REST API provides direct HTTP access to all privacy protection features. Use any programming language or HTTP client to integrate with Blindfold.

## Base URL

```
https://api.blindfold.dev/api/public/v1
```

### Regional Endpoints

| Region           | Base URL                                                 |
| ---------------- | -------------------------------------------------------- |
| **EU** (default) | `https://eu-api.blindfold.dev/api/public/v1`             |
| **US**           | `https://us-api.blindfold.dev/api/public/v1`             |
| **Global**       | `https://api.blindfold.dev/api/public/v1` (routes to EU) |

See [Regions](/essentials/regions) for details on data residency and region selection.

## Authentication

All API requests require authentication using an API key in the `X-API-Key` header:

```http theme={null}
X-API-Key: your-api-key-here
```

### Getting Your API Key

1. Sign up at [app.blindfold.dev](https://app.blindfold.dev)
2. Navigate to **API Keys** in the dashboard
3. Click **Create API Key**
4. Copy and securely store your key

<Warning>
  Keep your API key secure. Never commit it to version control or expose it in client-side code.
</Warning>

## Request Format

All requests must:

* Use `Content-Type: application/json`
* Include the `X-API-Key` header
* Send data as JSON in the request body

```http theme={null}
POST /api/public/v1/tokenize HTTP/1.1
Host: api.blindfold.dev
X-API-Key: your-api-key-here
Content-Type: application/json

{
  "text": "Your text here"
}
```

## Response Format

All successful responses return JSON with:

* `text`: The processed text
* `detected_entities`: Array of detected entities (if applicable)
* `entities_count`: Number of entities detected
* Additional method-specific fields

### Success Response (200 OK)

```json theme={null}
{
  "text": "Processed text",
  "entities_count": 2,
  "detected_entities": [
    {
      "type": "EMAIL_ADDRESS",
      "text": "john@example.com",
      "start": 12,
      "end": 28,
      "score": 1.0
    }
  ]
}
```

### Error Response (4xx, 5xx)

```json theme={null}
{
  "detail": "Error message describing what went wrong"
}
```

## Policy-Based Detection

Blindfold supports **policy-based PII detection** for simplified configuration and compliance. Instead of manually specifying entities and thresholds for each request, use pre-configured policies or create custom ones.

### Available Global Policies

| Policy Name | Description           | Threshold | Use Case                            |
| ----------- | --------------------- | --------- | ----------------------------------- |
| `basic`     | Minimal PII detection | 0.30      | General purpose, fast detection     |
| `gdpr_eu`   | GDPR EU compliant     | 0.35      | European data protection compliance |
| `hipaa_us`  | HIPAA compliant       | 0.40      | US healthcare data compliance       |
| `pci_dss`   | PCI DSS compliant     | 0.45      | Payment card industry compliance    |
| `strict`    | Maximum detection     | 0.25      | Comprehensive PII protection        |

### Using Policies in API Calls

All detection endpoints (`/detect`, `/tokenize`, `/mask`, `/redact`, `/hash`, `/encrypt`) support an optional `policy` parameter:

```json theme={null}
{
  "text": "Your text here",
  "policy": "gdpr_eu"
}
```

<Info>
  Using policies simplifies your code and ensures consistent PII detection across your application. Policies can be managed through the dashboard.
</Info>

## Batch Processing

All privacy method endpoints support **batch processing** — send multiple texts in a single request by using `texts` (array) instead of `text` (string). Configuration parameters (`policy`, `entities`, `score_threshold`) apply to all texts in the batch.

### Batch Request Format

```json theme={null}
{
  "texts": ["Text one with PII", "Text two with PII", "Text three"],
  "policy": "gdpr_eu"
}
```

### Batch Response Format

```json theme={null}
{
  "results": [
    { "text": "...", "detected_entities": [...], "entities_count": 1 },
    { "text": "...", "detected_entities": [...], "entities_count": 0 },
    { "error": "Processing failed for this item" }
  ],
  "total": 3,
  "succeeded": 2,
  "failed": 1
}
```

### Batch Limits

| Limit                   | Value                           |
| ----------------------- | ------------------------------- |
| Max texts per request   | 100                             |
| Max characters per text | 100,000                         |
| Rate limiting           | Once per request (not per text) |

<Warning>
  You must provide either `text` (single) or `texts` (batch), not both. Each text in the batch must be non-empty.
</Warning>

### Batch Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/tokenize \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "texts": [
        "Contact John Doe at john@example.com",
        "Call Jane at +1-555-9876",
        "No sensitive data here"
      ],
      "policy": "gdpr_eu"
    }'
  ```

  ```python Python SDK theme={null}
  from blindfold import Blindfold

  client = Blindfold(api_key="your-api-key-here")

  result = client.tokenize_batch(
      texts=["John Doe john@example.com", "Jane Smith +1-555-9876"],
      policy="gdpr_eu"
  )

  print(f"Processed {result.succeeded}/{result.total} texts")
  for item in result.results:
      print(item["text"])
  ```

  ```typescript JavaScript SDK theme={null}
  import { Blindfold } from '@blindfold/sdk'

  const client = new Blindfold({ apiKey: 'your-api-key-here' })

  const result = await client.tokenizeBatch(
    ['John Doe john@example.com', 'Jane Smith +1-555-9876'],
    { policy: 'gdpr_eu' }
  )

  console.log(`Processed ${result.succeeded}/${result.total} texts`)
  result.results.forEach(item => console.log(item.text))
  ```
</CodeGroup>

<Tip>
  Batch processing is available on all 7 privacy methods: **tokenize**, **detect**, **redact**, **mask**, **synthesize**, **hash**, and **encrypt**. The `/detokenize` and `/discover` endpoints do not support batch mode.
</Tip>

***

## API Endpoints

<CardGroup cols={2}>
  <Card title="Privacy Methods" icon="shield-check" href="#privacy-method-endpoints">
    Tokenize, mask, redact, hash, encrypt, synthesize
  </Card>

  <Card title="Utilities" icon="wrench" href="#utility-endpoints">
    Detokenization and health checks
  </Card>

  <Card title="Best Practices" icon="star" href="#best-practices">
    Security, rate limiting, examples
  </Card>
</CardGroup>

***

## Privacy Method Endpoints

These endpoints apply different privacy-preserving transformations to your text.

### Method Comparison

Choose the right privacy method for your use case:

| Method                         | Reversible | Output Example        | Best For                    |
| ------------------------------ | ---------- | --------------------- | --------------------------- |
| [Detect](#post-detect)         | N/A        | `[{type, text, ...}]` | DLP, monitoring, compliance |
| [Tokenize](#post-tokenize)     | ✅ Yes      | `<person_1>`          | AI processing, chatbots     |
| [Mask](#post-mask)             | ❌ No       | `***3456`             | Display to users            |
| [Redact](#post-redact)         | ❌ No       | \`\` (removed)        | Permanent removal, logs     |
| [Hash](#post-hash)             | ❌ No       | `ID_a3f8b9`           | Analytics, deduplication    |
| [Encrypt](#post-encrypt)       | ✅ Yes      | `gAAAAABh...`         | Secure storage              |
| [Synthesize](#post-synthesize) | ❌ No       | `Jane Smith` (fake)   | Testing, demos              |

<Tip>
  **For AI applications:** Use **tokenize** + **detokenize** to protect PII while maintaining context for the AI model.

  **For compliance:** Use policies like `gdpr_eu`, `hipaa_us`, or `pci_dss` to automatically apply the correct entity types and thresholds.
</Tip>

***

### POST /detect

Detect PII in text without modifying it. Returns only the detected entities.

<CodeGroup>
  ```bash cURL (with policy) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/detect \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Contact John Doe at john@example.com",
      "policy": "gdpr_eu"
    }'
  ```

  ```python Python (with policy) theme={null}
  import requests

  response = requests.post(
      "https://api.blindfold.dev/api/public/v1/detect",
      headers={
          "X-API-Key": "your-api-key-here",
          "Content-Type": "application/json"
      },
      json={
          "text": "Contact John Doe at john@example.com",
          "policy": "gdpr_eu"
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript (with policy) theme={null}
  const response = await fetch(
    'https://api.blindfold.dev/api/public/v1/detect',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text: 'Contact John Doe at john@example.com',
        policy: 'gdpr_eu'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**Request Body:**

| Field             | Type      | Required | Description                               |
| ----------------- | --------- | -------- | ----------------------------------------- |
| `text`            | string    | Yes      | Text to analyze for PII                   |
| `policy`          | string    | No       | Policy name (e.g., `gdpr_eu`, `hipaa_us`) |
| `entities`        | string\[] | No       | Filter specific entity types              |
| `score_threshold` | number    | No       | Minimum confidence (0.0-1.0)              |

**Response:**

```json theme={null}
{
  "entities_count": 2,
  "detected_entities": [
    {
      "type": "Person",
      "text": "John Doe",
      "start": 8,
      "end": 16,
      "score": 0.95
    },
    {
      "type": "Email Address",
      "text": "john@example.com",
      "start": 20,
      "end": 36,
      "score": 1.0
    }
  ]
}
```

<Info>
  Unlike other methods, `/detect` does not return a `text` field — it only returns the detected entities. Use this when you need to know **what** PII exists without transforming the text.
</Info>

***

### POST /tokenize

Replace sensitive data with reversible tokens. Returns a mapping to restore original values.

<CodeGroup>
  ```bash cURL (with policy) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/tokenize \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Contact John Doe at john@example.com",
      "policy": "gdpr_eu"
    }'
  ```

  ```bash cURL (manual config) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/tokenize \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Contact John Doe at john@example.com",
      "entities": ["person", "email address"],
      "score_threshold": 0.4
    }'
  ```

  ```python Python (with policy) theme={null}
  import requests

  response = requests.post(
      "https://api.blindfold.dev/api/public/v1/tokenize",
      headers={
          "X-API-Key": "your-api-key-here",
          "Content-Type": "application/json"
      },
      json={
          "text": "Contact John Doe at john@example.com",
          "policy": "gdpr_eu"  # Use GDPR policy
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript (with policy) theme={null}
  const response = await fetch(
    'https://api.blindfold.dev/api/public/v1/tokenize',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text: 'Contact John Doe at john@example.com',
        policy: 'gdpr_eu'  // Use GDPR policy
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**Request Body:**

| Field             | Type      | Required | Description                                                                      |
| ----------------- | --------- | -------- | -------------------------------------------------------------------------------- |
| `text`            | string    | Yes      | Text to tokenize                                                                 |
| `policy`          | string    | No       | Policy name (e.g., `gdpr_eu`, `hipaa_us`) - uses policy's entities and threshold |
| `entities`        | string\[] | No       | Filter specific entity types (alternative to policy)                             |
| `score_threshold` | number    | No       | Minimum confidence (0.0-1.0) (alternative to policy)                             |

**Policy Usage Example:**

```bash theme={null}
# Using a policy
curl -X POST https://api.blindfold.dev/api/public/v1/tokenize \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Contact John Doe at john@example.com",
    "policy": "gdpr_eu"
  }'
```

**Response:**

```json theme={null}
{
  "text": "Contact <PERSON_1> at <EMAIL_ADDRESS_1>",
  "mapping": {
    "<PERSON_1>": "John Doe",
    "<EMAIL_ADDRESS_1>": "john@example.com"
  },
  "entities_count": 2,
  "detected_entities": [
    {
      "type": "PERSON",
      "text": "John Doe",
      "start": 8,
      "end": 16,
      "score": 0.95
    },
    {
      "type": "EMAIL_ADDRESS",
      "text": "john@example.com",
      "start": 20,
      "end": 36,
      "score": 1.0
    }
  ]
}
```

***

## Utility Endpoints

These endpoints provide utility functions and service information.

### POST /detokenize

Restore original values from tokens using the mapping from `/tokenize`.

**Use with:** `/tokenize` endpoint to complete the privacy-preserving workflow.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/detokenize \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "AI response for <PERSON_1> at <EMAIL_ADDRESS_1>",
      "mapping": {
        "<PERSON_1>": "John Doe",
        "<EMAIL_ADDRESS_1>": "john@example.com"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.blindfold.dev/api/public/v1/detokenize",
      headers={
          "X-API-Key": "your-api-key-here",
          "Content-Type": "application/json"
      },
      json={
          "text": "AI response for <PERSON_1> at <EMAIL_ADDRESS_1>",
          "mapping": {
              "<PERSON_1>": "John Doe",
              "<EMAIL_ADDRESS_1>": "john@example.com"
          }
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.blindfold.dev/api/public/v1/detokenize',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text: 'AI response for <PERSON_1> at <EMAIL_ADDRESS_1>',
        mapping: {
          '<PERSON_1>': 'John Doe',
          '<EMAIL_ADDRESS_1>': 'john@example.com'
        }
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**Request Body:**

| Field     | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `text`    | string | Yes      | Text containing tokens |
| `mapping` | object | Yes      | Token-to-value mapping |

**Response:**

```json theme={null}
{
  "text": "AI response for John Doe at john@example.com",
  "replacements_made": 2
}
```

***

### POST /mask

Partially hide sensitive data (e.g., `****-****-****-1234`).

<CodeGroup>
  ```bash cURL (with policy) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/mask \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Credit card: 4532-7562-9102-3456",
      "policy": "pci_dss",
      "masking_char": "*",
      "chars_to_show": 4,
      "from_end": true
    }'
  ```

  ```bash cURL (manual config) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/mask \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Credit card: 4532-7562-9102-3456",
      "entities": ["credit card number"],
      "masking_char": "*",
      "chars_to_show": 4,
      "from_end": true
    }'
  ```

  ```python Python (with policy) theme={null}
  import requests

  response = requests.post(
      "https://api.blindfold.dev/api/public/v1/mask",
      headers={
          "X-API-Key": "your-api-key-here",
          "Content-Type": "application/json"
      },
      json={
          "text": "Credit card: 4532-7562-9102-3456",
          "policy": "pci_dss",  # PCI DSS policy for payment cards
          "masking_char": "*",
          "chars_to_show": 4,
          "from_end": True
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript (with policy) theme={null}
  const response = await fetch(
    'https://api.blindfold.dev/api/public/v1/mask',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text: 'Credit card: 4532-7562-9102-3456',
        policy: 'pci_dss',  // PCI DSS policy for payment cards
        masking_char: '*',
        chars_to_show: 4,
        from_end: true
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**Request Body:**

| Field             | Type      | Required | Description                      |
| ----------------- | --------- | -------- | -------------------------------- |
| `text`            | string    | Yes      | Text to mask                     |
| `masking_char`    | string    | No       | Masking character (default: `*`) |
| `chars_to_show`   | number    | No       | Characters to show (default: 4)  |
| `from_end`        | boolean   | No       | Show from end (default: true)    |
| `entities`        | string\[] | No       | Filter specific entity types     |
| `score_threshold` | number    | No       | Minimum confidence (0.0-1.0)     |

**Response:**

```json theme={null}
{
  "text": "Credit card: ***************3456",
  "entities_count": 1,
  "detected_entities": [
    {
      "type": "CREDIT_CARD",
      "text": "4532-7562-9102-3456",
      "start": 13,
      "end": 32,
      "score": 1.0
    }
  ]
}
```

***

### POST /redact

Permanently remove sensitive data.

<CodeGroup>
  ```bash cURL (with policy) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/redact \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Patient: Jane Smith, SSN: 123-45-6789, DOB: 1985-04-12",
      "policy": "hipaa_us"
    }'
  ```

  ```bash cURL (manual config) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/redact \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "My SSN is 123-45-6789",
      "entities": ["social security number"],
      "score_threshold": 0.5
    }'
  ```

  ```python Python (with policy) theme={null}
  import requests

  response = requests.post(
      "https://api.blindfold.dev/api/public/v1/redact",
      headers={
          "X-API-Key": "your-api-key-here",
          "Content-Type": "application/json"
      },
      json={
          "text": "Patient: Jane Smith, SSN: 123-45-6789, DOB: 1985-04-12",
          "policy": "hipaa_us"  # HIPAA policy for healthcare data
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript (with policy) theme={null}
  const response = await fetch(
    'https://api.blindfold.dev/api/public/v1/redact',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text: 'Patient: Jane Smith, SSN: 123-45-6789, DOB: 1985-04-12',
        policy: 'hipaa_us'  // HIPAA policy for healthcare data
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**Request Body:**

| Field             | Type      | Required | Description                  |
| ----------------- | --------- | -------- | ---------------------------- |
| `text`            | string    | Yes      | Text to redact               |
| `entities`        | string\[] | No       | Filter specific entity types |
| `score_threshold` | number    | No       | Minimum confidence (0.0-1.0) |

**Response:**

```json theme={null}
{
  "text": "My SSN is ",
  "entities_count": 1,
  "detected_entities": [
    {
      "type": "US_SSN",
      "text": "123-45-6789",
      "start": 10,
      "end": 21,
      "score": 1.0
    }
  ]
}
```

***

### POST /hash

Replace data with deterministic hashes.

<CodeGroup>
  ```bash cURL (with policy) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/hash \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "User john@example.com purchased item",
      "policy": "basic",
      "hash_type": "sha256",
      "hash_prefix": "ID_",
      "hash_length": 16
    }'
  ```

  ```bash cURL (manual config) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/hash \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "User john@example.com purchased item",
      "entities": ["email address"],
      "hash_type": "sha256",
      "hash_prefix": "ID_",
      "hash_length": 16
    }'
  ```

  ```python Python (with policy) theme={null}
  import requests

  response = requests.post(
      "https://api.blindfold.dev/api/public/v1/hash",
      headers={
          "X-API-Key": "your-api-key-here",
          "Content-Type": "application/json"
      },
      json={
          "text": "User john@example.com purchased item",
          "policy": "basic",  # Basic policy for common PII
          "hash_type": "sha256",
          "hash_prefix": "ID_",
          "hash_length": 16
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript (with policy) theme={null}
  const response = await fetch(
    'https://api.blindfold.dev/api/public/v1/hash',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text: 'User john@example.com purchased item',
        policy: 'basic',  // Basic policy for common PII
        hash_type: 'sha256',
        hash_prefix: 'ID_',
        hash_length: 16
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**Request Body:**

| Field             | Type      | Required | Description                                                                               |
| ----------------- | --------- | -------- | ----------------------------------------------------------------------------------------- |
| `text`            | string    | Yes      | Text to hash                                                                              |
| `hash_type`       | string    | No       | Hash algorithm: `md5`, `sha1`, `sha224`, `sha256`, `sha384`, `sha512` (default: `sha256`) |
| `hash_prefix`     | string    | No       | Prefix for hashes (default: `""`)                                                         |
| `hash_length`     | number    | No       | Hash length to use (default: 16)                                                          |
| `entities`        | string\[] | No       | Filter specific entity types                                                              |
| `score_threshold` | number    | No       | Minimum confidence (0.0-1.0)                                                              |

**Response:**

```json theme={null}
{
  "text": "User ID_a3f8b9c2d4e5f6g7 purchased item",
  "entities_count": 1,
  "detected_entities": [
    {
      "type": "EMAIL_ADDRESS",
      "text": "john@example.com",
      "start": 5,
      "end": 21,
      "score": 1.0
    }
  ]
}
```

***

### POST /synthesize

Replace real data with realistic fake data.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/synthesize \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "John lives in New York",
      "language": "en"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.blindfold.dev/api/public/v1/synthesize",
      headers={
          "X-API-Key": "your-api-key-here",
          "Content-Type": "application/json"
      },
      json={
          "text": "John lives in New York",
          "language": "en"
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.blindfold.dev/api/public/v1/synthesize',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text: 'John lives in New York',
        language: 'en'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**Request Body:**

| Field             | Type      | Required | Description                                                              |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------ |
| `text`            | string    | Yes      | Text to synthesize                                                       |
| `language`        | string    | No       | Language: `en`, `cs`, `de`, `fr`, `es`, `it`, `pl`, `sk` (default: `en`) |
| `entities`        | string\[] | No       | Filter specific entity types                                             |
| `score_threshold` | number    | No       | Minimum confidence (0.0-1.0)                                             |

**Response:**

```json theme={null}
{
  "text": "Michael Smith lives in Boston",
  "entities_count": 2,
  "detected_entities": [
    {
      "type": "PERSON",
      "text": "John",
      "start": 0,
      "end": 4,
      "score": 0.95
    },
    {
      "type": "LOCATION",
      "text": "New York",
      "start": 14,
      "end": 22,
      "score": 0.90
    }
  ]
}
```

***

### POST /encrypt

Encrypt sensitive data using AES encryption.

<CodeGroup>
  ```bash cURL (with policy) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/encrypt \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Secret: API key is sk-12345, Password: myPass123",
      "policy": "strict",
      "encryption_key": "my-secure-encryption-key"
    }'
  ```

  ```bash cURL (manual config) theme={null}
  curl -X POST https://api.blindfold.dev/api/public/v1/encrypt \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Secret: API key is sk-12345",
      "entities": ["username", "password"],
      "encryption_key": "my-secure-encryption-key"
    }'
  ```

  ```python Python (with policy) theme={null}
  import requests

  response = requests.post(
      "https://api.blindfold.dev/api/public/v1/encrypt",
      headers={
          "X-API-Key": "your-api-key-here",
          "Content-Type": "application/json"
      },
      json={
          "text": "Secret: API key is sk-12345, Password: myPass123",
          "policy": "strict",  # Strict policy for maximum detection
          "encryption_key": "my-secure-encryption-key"
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript (with policy) theme={null}
  const response = await fetch(
    'https://api.blindfold.dev/api/public/v1/encrypt',
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text: 'Secret: API key is sk-12345, Password: myPass123',
        policy: 'strict',  // Strict policy for maximum detection
        encryption_key: 'my-secure-encryption-key'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**Request Body:**

| Field             | Type      | Required | Description                   |
| ----------------- | --------- | -------- | ----------------------------- |
| `text`            | string    | Yes      | Text to encrypt               |
| `encryption_key`  | string    | No       | Encryption key (min 16 chars) |
| `entities`        | string\[] | No       | Filter specific entity types  |
| `score_threshold` | number    | No       | Minimum confidence (0.0-1.0)  |

**Response:**

```json theme={null}
{
  "text": "Secret: gAAAAABh3K7x...",
  "entities_count": 1,
  "detected_entities": [
    {
      "type": "API_KEY",
      "text": "sk-12345",
      "start": 19,
      "end": 27,
      "score": 0.85
    }
  ]
}
```

***

### GET /health

Health check endpoint.

```bash theme={null}
curl https://api.blindfold.dev/api/public/v1/health
```

**Response:**

```json theme={null}
{
  "status": "healthy",
  "service": "Public API",
  "version": "v1",
  "endpoints": [
    "/v1/tokenize",
    "/v1/detokenize",
    "/v1/redact",
    "/v1/mask",
    "/v1/synthesize",
    "/v1/hash",
    "/v1/encrypt"
  ]
}
```

## Supported Entity Types

All detection endpoints support filtering by entity type using **natural language names** (lowercase). Blindfold supports 60+ pre-trained entity types.

<Card title="View All Entities" icon="list" href="/essentials/supported-entities" horizontal>
  See the complete list of 60+ entity types organized by category
</Card>

### Quick Reference

### Personal Information

* `person` - Person names
* `email` / `email address` - Email addresses
* `phone number` / `mobile phone number` - Phone numbers
* `date of birth` - Birth dates
* `blood type` - Blood type classification

### Contact Information

* `address` / `postal code` - Physical addresses and postal codes
* `landline phone number` - Fixed-line phone numbers
* `fax number` - Fax numbers

### Financial

* `credit card number` - Credit card numbers
* `credit card brand` - Card issuer (Visa, Mastercard, etc.)
* `credit card expiration date` - Card expiration dates
* `cvv` / `cvc` - Card verification codes
* `bank account number` - Bank account numbers
* `iban` - International Bank Account Numbers
* `tax identification number` - Tax IDs

### Government IDs

* `social security number` - Social security numbers
* `passport number` - Passport numbers
* `driver's license number` - Driver's licenses
* `national id number` - National ID cards
* `cpf` - Brazilian individual taxpayer ID
* `cnpj` - Brazilian company registry

### Healthcare

* `health insurance number` - Health insurance IDs
* `medical condition` - Medical diagnoses
* `medication` - Medication names
* `insurance company` - Insurance provider names

### Digital & Technical

* `ip address` - IPv4 and IPv6 addresses
* `username` - User identifiers
* `social media handle` - Social media usernames

### Travel & Transactions

* `flight number` - Airline flight numbers
* `reservation number` - Booking confirmations
* `transaction number` - Transaction IDs

### Registration

* `license plate number` - Vehicle plates
* `student id number` - Student IDs
* `serial number` - Product serial numbers

<Info>
  See the complete list of 60+ entity types in the [Supported Entities](/essentials/supported-entities) documentation.
</Info>

## Plans & Limits

|                          | Free         | Pay As You Go           |
| ------------------------ | ------------ | ----------------------- |
| **Characters**           | 500K / month | Unlimited (\$0.50 / 1M) |
| **Max text per request** | 5K chars     | 500K chars              |

The API returns a `429 Too Many Requests` response when you exceed your plan limits. Implement retry logic with exponential backoff for production use.

## Error Codes

| Code | Description                               |
| ---- | ----------------------------------------- |
| 200  | Success                                   |
| 400  | Bad Request - Invalid parameters          |
| 401  | Unauthorized - Invalid or missing API key |
| 429  | Too Many Requests - Rate limit exceeded   |
| 500  | Internal Server Error - Server-side issue |

## Best Practices

### 1. Store API Keys Securely

```bash theme={null}
# Use environment variables
export BLINDFOLD_API_KEY="your-api-key-here"
```

### 2. Handle Rate Limits

Implement exponential backoff for rate limit errors:

```python theme={null}
import time
import requests

def make_request_with_retry(url, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, json=data, headers=headers)

        if response.status_code == 429:
            # Rate limited - wait and retry
            wait_time = 2 ** attempt
            time.sleep(wait_time)
            continue

        return response

    raise Exception("Max retries exceeded")
```

### 3. Validate Responses

Always check the response status and handle errors:

```python theme={null}
response = requests.post(url, json=data, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(f"Success: {data['text']}")
elif response.status_code == 401:
    print("Invalid API key")
elif response.status_code == 429:
    print("Rate limit exceeded")
else:
    print(f"Error: {response.json()['detail']}")
```

### 4. Use Connection Pooling

For high-throughput applications, use connection pooling:

```python theme={null}
import requests

session = requests.Session()
# Reuse session for multiple requests
response = session.post(url, json=data, headers=headers)
```

## Complete Examples

Real-world integration patterns using the Blindfold REST API.

<CardGroup cols={2}>
  <Card title="AI Integration" icon="robot">
    Complete tokenize → AI → detokenize workflow
  </Card>

  <Card title="Compliance" icon="scale-balanced">
    GDPR, HIPAA, PCI DSS policy usage
  </Card>
</CardGroup>

### Example 1: AI Integration with GDPR Compliance

```python theme={null}
import requests
import os

API_KEY = os.environ.get("BLINDFOLD_API_KEY")
BASE_URL = "https://api.blindfold.dev/api/public/v1"

headers = {
    "X-API-Key": f"{API_KEY}",
    "Content-Type": "application/json"
}

# 1. Tokenize user input using GDPR policy
user_message = "My name is John Doe, email john@example.com, phone +49 30 12345678"

tokenize_response = requests.post(
    f"{BASE_URL}/tokenize",
    headers=headers,
    json={
        "text": user_message,
        "policy": "gdpr_eu"  # Use GDPR-compliant policy
    }
)

tokenize_data = tokenize_response.json()
protected_text = tokenize_data["text"]
mapping = tokenize_data["mapping"]

print(f"Protected: {protected_text}")
# Output: "My name is <person_1>, email <email_address_1>, phone <phone_number_1>"

# 2. Send to AI (using protected text)
# ... AI processing ...

# 3. Detokenize AI response
ai_response = f"Thank you {protected_text.split()[3]}!"  # Example AI response

detokenize_response = requests.post(
    f"{BASE_URL}/detokenize",
    headers=headers,
    json={
        "text": ai_response,
        "mapping": mapping
    }
)

final_text = detokenize_response.json()["text"]
print(f"Final: {final_text}")
# Output: "Thank you John Doe!"
```

### Example 2: Healthcare Data with HIPAA Policy

```python theme={null}
import requests
import os

API_KEY = os.environ.get("BLINDFOLD_API_KEY")
BASE_URL = "https://api.blindfold.dev/api/public/v1"

headers = {
    "X-API-Key": f"{API_KEY}",
    "Content-Type": "application/json"
}

# Redact healthcare data using HIPAA policy
patient_data = """
Patient: Jane Smith
DOB: 1985-04-12
SSN: 123-45-6789
Health Insurance: ABC123456
Diagnosis: Type 2 Diabetes
Medication: Metformin 500mg
"""

redact_response = requests.post(
    f"{BASE_URL}/redact",
    headers=headers,
    json={
        "text": patient_data,
        "policy": "hipaa_us"  # Use HIPAA-compliant policy
    }
)

redacted_data = redact_response.json()
print(f"Redacted data:\n{redacted_data['text']}")
print(f"Entities found: {redacted_data['entities_count']}")
```

### Example 3: Payment Card Data with PCI DSS Policy

```python theme={null}
import requests
import os

API_KEY = os.environ.get("BLINDFOLD_API_KEY")
BASE_URL = "https://api.blindfold.dev/api/public/v1"

headers = {
    "X-API-Key": f"{API_KEY}",
    "Content-Type": "application/json"
}

# Mask payment card data using PCI DSS policy
transaction_data = "Transaction for card 4532-7562-9102-3456, CVV: 123, expires 12/25"

mask_response = requests.post(
    f"{BASE_URL}/mask",
    headers=headers,
    json={
        "text": transaction_data,
        "policy": "pci_dss",  # Use PCI DSS policy for payment cards
        "masking_char": "*",
        "chars_to_show": 4,
        "from_end": True
    }
)

masked_data = mask_response.json()
print(f"Masked data: {masked_data['text']}")
print(f"Entities found: {masked_data['entities_count']}")
```

## Need Help?

* **Email Support**: [hello@blindfold.dev](mailto:hello@blindfold.dev)
* **SDK Documentation**: [Python SDK](/sdks/python-sdk) | [JavaScript SDK](/sdks/javascript-sdk)
* **Examples**: [See practical examples](/examples)