Getting Started with Redactly API

Privacy Middleware for Safer LLMs

Introduction

Redactly is a powerful API service for detecting and redacting Personally Identifiable Information (PII) from text data. This guide will help you quickly integrate Redactly into your applications to protect user privacy by identifying and masking sensitive information.

Accessing Redactly’s API

For an API key, please reach out to jordon@getredactly.com.

Authentication

Redactly uses Bearer token authentication to secure API requests.

Authorization: Bearer YOUR_JWT_TOKEN

To access the API:

Obtain your JWT token through your account administrator
Include this token in the `Authorization` header with every API request
Keep your token secure and never expose it in client-side code

Core Endpoints

Redactly offers several endpoints for different PII protection needs:

Endpoint	Purpose	Use Case
`/redact-prompt`	Redact PII from a single text	Use before sending user input to an LLM
`/redact-batch`	Process multiple texts in one request	Use to sanitize multiple entries (chat logs, etc.)
`/redact-json`	Redact PII from specific JSON fields	Use to redact JSON formatted input
`/detect-pii`	Identify PII without redacting it	Use to preview/highlight PII before redaction

Basic Usage

Redacting PII from Text

Send a POST request to /redact-prompt with text to be processed:

{
  "text": "My name is John Doe and my email is john@example.com",
  "entity_types": ["PERSON", "EMAIL_ADDRESS"],
  "return_scores": false
}

Response:

{
  "text": "My name is [REDACTED] and my email is [REDACTED]",
  "entity_types": ["PERSON", "EMAIL_ADDRESS"]
}

Processing Multiple Texts

For batch processing, use the /redact-batch endpoint:

{
  "texts": ["John Doe lives at 123 Main St", "Contact jane@example.com"],
  "entity_types": ["PERSON", "LOCATION", "EMAIL_ADDRESS"]
}

Redacting PII from JSON

To redact specific fields in JSON data:

{
  "fields": [
    {
      "path": "user.name",
      "value": "John Smith"
    },
    {
      "path": "user.address",
      "value": "123 Main Street, Boston MA 02110"
    }
  ],
  "entity_types": ["PERSON", "LOCATION"]
}

Detecting PII Without Redaction

To identify PII entities without redacting the text:

{
  "text": "John Doe lives at 123 Main St",
  "entity_types": ["PERSON", "LOCATION"],
  "return_scores": true
}

Response:

{
  "entities": [
    {
      "type": "PERSON",
      "start": 0,
      "end": 8,
      "text": "John Doe",
      "score": 0.95
    },
    {
      "type": "LOCATION",
      "start": 18,
      "end": 30,
      "text": "123 Main St",
      "score": 0.92
    }
  ]
}

Entity Types

Redactly can detect and redact various types of PII:

PERSON: Names of individuals
LOCATION: Addresses, cities, states, etc.
DATE_TIME: Dates and times
EMAIL_ADDRESS: Email addresses
PHONE_NUMBER: Phone numbers
ORGANIZATION: Company and organization names
URL: Web addresses
CREDIT_CARD: Credit card numbers
US_SSN: Social Security Numbers
US_BANK_NUMBER: Bank account numbers

Error Handling

The API returns standard HTTP status codes:

200: Success
400: Bad request (check your request format)
401: Unauthorized (check your authentication token)
500: Server error

Error responses include an error message:

{
  "error": "Invalid JSON format"
}

Best Practices

Limit Entity Types: Only specify entity types you need to redact for better performance
Use Batch Processing: When processing multiple texts, use the batch endpoint for efficiency
Handle Errors: Implement proper error handling in your client cod
Verify Results: Always verify redaction results in sensitive applications
Cache Authentication: Cache your token to avoid authentication overhead on every request

Service Status

Check API availability and performance using the `/status` endpoint:

GET /status

Rate Limits

Contact your account administrator for information about rate limits for your specific plan.

Need Help?

For additional support, please reach out to Redactly Support or consult the full API documentation.