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

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 Authorization header
Send data as JSON in the request body

POST /api/public/v1/tokenize HTTP/1.1
Host: api.blindfold.dev
Authorization: Bearer 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": [
    {
      "entity_type": "EMAIL_ADDRESS",
      "text": "[email protected]",
      "start": 12,
      "end": 28,
      "score": 1.0
    }
  ]
}

Error Response (4xx, 5xx)

{
  "detail": "Error message describing what went wrong"
}

API Endpoints

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 [email protected]",
    "entities": ["PERSON", "EMAIL_ADDRESS"],
    "score_threshold": 0.4
  }'

Request Body:

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

Response:

{
  "text": "Contact <PERSON_1> at <EMAIL_ADDRESS_1>",
  "mapping": {
    "<PERSON_1>": "John Doe",
    "<EMAIL_ADDRESS_1>": "[email protected]"
  },
  "entities_count": 2,
  "detected_entities": [
    {
      "entity_type": "PERSON",
      "text": "John Doe",
      "start": 8,
      "end": 16,
      "score": 0.95
    },
    {
      "entity_type": "EMAIL_ADDRESS",
      "text": "[email protected]",
      "start": 20,
      "end": 36,
      "score": 1.0
    }
  ]
}

POST /detokenize

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

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>": "[email protected]"
    }
  }'

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 [email protected]",
  "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",
    "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": [
    {
      "entity_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": "My SSN is 123-45-6789",
    "entities": ["US_SSN"],
    "score_threshold": 0.5
  }'

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": [
    {
      "entity_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 [email protected] purchased item",
    "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": [
    {
      "entity_type": "EMAIL_ADDRESS",
      "text": "[email protected]",
      "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": [
    {
      "entity_type": "PERSON",
      "text": "John",
      "start": 0,
      "end": 4,
      "score": 0.95
    },
    {
      "entity_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",
    "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": [
    {
      "entity_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. Common entities include:

Personal Information

PERSON - Person names
EMAIL_ADDRESS - Email addresses
PHONE_NUMBER - Phone numbers
DATE_TIME - Dates and times

Financial

CREDIT_CARD - Credit card numbers
IBAN_CODE - International Bank Account Numbers
CRYPTO - Cryptocurrency addresses

Government IDs

US_SSN - US Social Security Numbers
US_DRIVER_LICENSE - US Driver Licenses
US_PASSPORT - US Passport Numbers

Medical

MEDICAL_LICENSE - Medical license numbers
US_ITIN - Individual Taxpayer IDs

Technical

IP_ADDRESS - IP addresses
URL - URLs and domains
API_KEY - API keys and tokens

Location

LOCATION - Cities and locations
ADDRESS - Physical addresses

Rate Limiting

The API has the following rate limits:

Free Tier: 1,000 requests per day
Pro Tier: 100,000 requests per day
Enterprise: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

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 Example

Here’s a complete workflow using the REST API:

import requests
import os

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

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 1. Tokenize user input
user_message = "My name is John Doe and email is [email protected]"

tokenize_response = requests.post(
    f"{BASE_URL}/tokenize",
    headers=headers,
    json={"text": user_message}
)

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

print(f"Protected: {protected_text}")

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

# 3. Detokenize AI response
ai_response = f"Hello {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}")

Need Help?

Email Support: [email protected]
SDK Documentation: Python SDK | JavaScript SDK
Examples: See practical examples

REST API

​Base URL

​Authentication

​Getting Your API Key

​Request Format

​Response Format

​Success Response (200 OK)

​Error Response (4xx, 5xx)

​API Endpoints

​POST /tokenize

​POST /detokenize

​POST /mask

​POST /redact

​POST /hash

​POST /synthesize

​POST /encrypt

​GET /health

​Supported Entity Types

​Personal Information

​Financial

​Government IDs

​Medical

​Technical

​Location

​Rate Limiting

​Error Codes

​Best Practices

​1. Store API Keys Securely

​2. Handle Rate Limits

​3. Validate Responses

​4. Use Connection Pooling

​Complete Example

​Need Help?

Base URL

Authentication

Getting Your API Key

Request Format

Response Format

Success Response (200 OK)

Error Response (4xx, 5xx)

API Endpoints

POST /tokenize

POST /detokenize

POST /mask

POST /redact

POST /hash

POST /synthesize

POST /encrypt

GET /health

Supported Entity Types

Personal Information

Financial

Government IDs

Medical

Technical

Location

Rate Limiting

Error Codes

Best Practices

1. Store API Keys Securely

2. Handle Rate Limits

3. Validate Responses

4. Use Connection Pooling

Complete Example

Need Help?