API Reference

API Reference

Base URL: https://masker.kikuai.dev
API Version: 1.0.0

---

Endpoints

POST /v1/redact

Main endpoint for PII redaction. Supports both text and JSON input modes.

Request:

POST /v1/redact
Content-Type: application/json

Request Body:

Field	Type	Required	Default	Description
text	string	One of text/json	-	Plain text to process (max 32KB)
json	object	One of text/json	-	JSON object/array to process (max 64KB total)
mode	string	No	"mask"	Redaction mode: "mask" or "placeholder"
entities	array	No	null	Filter specific entity types: ["PERSON", "EMAIL", "PHONE", "CARD"]
language	string	No	"en"	Language code: "en" or "ru"

Response:

{
  "redacted_text": "string | null",
  "redacted_json": "object | null",
  "items": [
    {
      "entity_type": "PERSON | EMAIL | PHONE | CARD",
      "path": "string | null",
      "start": 0,
      "end": 8,
      "score": 0.85
    }
  ],
  "processing_time_ms": 15.29
}

Status Codes:

Code	Description
200	Success
400	Bad Request (invalid input)
413	Payload Too Large
500	Internal Server Error

---

GET /health

Health check endpoint. No authentication required.

Response:

{
  "status": "ok",
  "version": "1.0.0"
}

---

GET /docs

Interactive API documentation (Swagger UI). No authentication required.

---

Redaction Modes

Mode: mask

Replaces PII with *** (asterisks).

Example:

Input:  "Contact john@example.com"
Output: "Contact ***"

Mode: placeholder

Replaces PII with type-specific placeholders:

• <PERSON> for person names
• <EMAIL> for email addresses
• <PHONE> for phone numbers
• <CARD> for credit card numbers

Example:

Input:  "Contact john@example.com"
Output: "Contact <EMAIL>"

---

Entity Types

PERSON

Person names detected using spaCy NER (Named Entity Recognition).

• Languages: English, Russian
• Confidence: ~0.85 average
• Example: "John Doe", "Иван Иванов"

EMAIL

Email addresses detected using regex.

• Confidence: 1.0 (100%)
• Example: "john@example.com"

PHONE

Phone numbers detected using regex (international formats).

• Confidence: 1.0 (100%)
• Example: "+1-555-123-4567", "+7 999 123 45 67"

CARD

Credit/debit card numbers detected using regex with Luhn validation.

• Confidence: 1.0 (100%)
• Example: "4111-1111-1111-1111"

---

JSON Mode

JSON mode processes JSON structures recursively, only modifying string values:

{
  "json": {
    "user": {
      "name": "John Doe",
      "email": "john@example.com",
      "age": 30
    }
  },
  "mode": "placeholder"
}

Result:

{
  "user": {
    "name": "<PERSON>",
    "email": "<EMAIL>",
    "age": 30
  }
}

Notes:

• Only string values are processed
• JSON structure is preserved
• Non-string values (numbers, booleans, null) are unchanged
• Arrays are processed recursively

---

Response Headers

All responses include:

Header	Description
X-Request-ID	Unique request identifier for tracking
X-Processing-Time	Processing time in milliseconds
Content-Type	application/json

---

Last Updated: 2025-11-27
API Version: 1.0.0