REST API Reference

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 for details on data residency and region selection.

Authentication

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

X-API-Key: your-api-key-here

Getting Your API Key

Sign up at app.blindfold.dev
Navigate to API Keys in the dashboard
Click Create API Key
Copy and securely store your key

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

Request Format

All requests must:

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

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)

{
  "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)

{
  "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:

{
  "text": "Your text here",
  "policy": "gdpr_eu"
}

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

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

{
  "texts": ["Text one with PII", "Text two with PII", "Text three"],
  "policy": "gdpr_eu"
}

Batch Response Format

{
  "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)

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

Batch Example

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"
  }'

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.

API Endpoints

Privacy Methods

Tokenize, mask, redact, hash, encrypt, synthesize

Utilities

Detokenization and health checks

Best Practices

Security, rate limiting, examples

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	N/A	`[{type, text, ...}]`	DLP, monitoring, compliance
Tokenize	✅ Yes	`<person_1>`	AI processing, chatbots
Mask	❌ No	`***3456`	Display to users
Redact	❌ No	“ (removed)	Permanent removal, logs
Hash	❌ No	`ID_a3f8b9`	Analytics, deduplication
Encrypt	✅ Yes	`gAAAAABh...`	Secure storage
Synthesize	❌ No	`Jane Smith` (fake)	Testing, demos

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.

POST /detect

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

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"
  }'

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:

{
  "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
    }
  ]
}

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.

POST /tokenize

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

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"
  }'

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:

# 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:

{
  "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.

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"
    }
  }'

Request Body:

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

Response:

{
  "text": "AI response for John Doe at john@example.com",
  "replacements_made": 2
}

POST /mask

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

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
  }'

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:

{
  "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.

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"
  }'

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:

{
  "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.

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
  }'

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:

{
  "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.

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"
  }'

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:

{
  "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.

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"
  }'

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:

{
  "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.

curl https://api.blindfold.dev/api/public/v1/health

Response:

{
  "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.

View All Entities

See the complete list of 60+ entity types organized by category

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

See the complete list of 60+ entity types in the Supported Entities documentation.

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

# Use environment variables
export BLINDFOLD_API_KEY="your-api-key-here"

2. Handle Rate Limits

Implement exponential backoff for rate limit errors:

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:

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:

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.

AI Integration

Complete tokenize → AI → detokenize workflow

Compliance

GDPR, HIPAA, PCI DSS policy usage

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

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

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
SDK Documentation: Python SDK | JavaScript SDK
Examples: See practical examples

REST API

​Base URL

​Regional Endpoints

​Authentication

​Getting Your API Key

​Request Format

​Response Format

​Success Response (200 OK)

​Error Response (4xx, 5xx)

​Policy-Based Detection

​Available Global Policies

​Using Policies in API Calls

​Batch Processing

​Batch Request Format

​Batch Response Format

​Batch Limits

​Batch Example

​API Endpoints

Privacy Methods

Utilities

Best Practices

​Privacy Method Endpoints

​Method Comparison

​POST /detect

​POST /tokenize

​Utility Endpoints

​POST /detokenize

​POST /mask

​POST /redact

​POST /hash

​POST /synthesize

​POST /encrypt

​GET /health

​Supported Entity Types

View All Entities

​Quick Reference

​Personal Information

​Contact Information

​Financial

​Government IDs

​Healthcare

​Digital & Technical

​Travel & Transactions

​Registration

​Plans & Limits

​Error Codes

​Best Practices

​1. Store API Keys Securely

​2. Handle Rate Limits

​3. Validate Responses

​4. Use Connection Pooling

​Complete Examples

AI Integration

Compliance

​Example 1: AI Integration with GDPR Compliance

​Example 2: Healthcare Data with HIPAA Policy

​Example 3: Payment Card Data with PCI DSS Policy

​Need Help?

Base URL

Regional Endpoints

Authentication

Getting Your API Key

Request Format

Response Format

Success Response (200 OK)

Error Response (4xx, 5xx)

Policy-Based Detection

Available Global Policies

Using Policies in API Calls

Batch Processing

Batch Request Format

Batch Response Format

Batch Limits

Batch Example

API Endpoints

Privacy Method Endpoints

Method Comparison

POST /detect

POST /tokenize

Utility Endpoints

POST /detokenize

POST /mask

POST /redact

POST /hash

POST /synthesize

POST /encrypt

GET /health

Supported Entity Types

Quick Reference

Personal Information

Contact Information

Financial

Government IDs

Healthcare

Digital & Technical

Travel & Transactions

Registration

Plans & Limits

Error Codes

Best Practices

1. Store API Keys Securely

2. Handle Rate Limits

3. Validate Responses

4. Use Connection Pooling

Complete Examples

Example 1: AI Integration with GDPR Compliance

Example 2: Healthcare Data with HIPAA Policy

Example 3: Payment Card Data with PCI DSS Policy

Need Help?