API reference
Endpoints
Base URL https://api.obscate.com. JSON in, JSON out. Auth with x-api-key on every endpoint except signup, verify, the playground and the public GETs. The generated OpenAPI explorer is at api.obscate.com/docs.
| Endpoint | Purpose | Units |
|---|---|---|
POST /v1/redact | Redact text | 1 per 100 KB |
POST /v1/redact/batch | Redact up to 100 texts | at least 1 per item |
POST /v1/detect | Find PII without changing it | 1 per 100 KB |
POST /v1/restore | Undo tokenize / synthetic (with the map) | free |
POST /v1/restore-fpe | Undo fpe (key only) | free |
POST /v1/redact-json | Redact values in a JSON document | 1 per 100 KB |
POST /v1/restore-json | Restore a JSON document | free |
GET /v1/usage | This month’s usage | free |
GET/POST /v1/keys, DELETE /v1/keys/{id} | Key management | free |
POST /v1/signup, /v1/verify; GET /v1/entities, /v1/plans, /v1/health | Account creation and public info | free, no key |
Common request fields
| Field | Type | Default | Meaning |
|---|---|---|---|
strategy | string | "tokenize" | One of tokenize, mask, hash, partial, synthetic, fpe. See Strategies. Note: the integrations default to fpe; the raw API defaults to tokenize. |
labels | string[] | null | all | Only detect these types, e.g. ["EMAIL","CREDIT_CARD"]. See Detectors or GET /v1/entities. |
min_confidence | number | 0.0 | Drop matches below this confidence (0–1). Raises precision, lowers recall. |
POST/v1/redact
Request: text (string, required, ≤ 200,000 characters), strategy, labels, min_confidence.
curl -s https://api.obscate.com/v1/redact -H "x-api-key: $OBSCATE_API_KEY" -H 'content-type: application/json' \
-d '{"text":"Refund card 4242 4242 4242 4242 for Priya Sharma, priya.sharma@example.com, +91 98765 43210","strategy":"fpe"}'
{"redacted": "Refund card 9244 7815 4042 5941 for [PERSON:3bihtlnay7dpeoi7coukzsn23mu4brvsh6xhlvf7cqzgi], rwkbj.mprpta@wcrwbuh.com, +31 74902 86938",
"strategy": "fpe", "reversible": true, "token_map": {},
"entities": [
{"label": "CREDIT_CARD", "text": "4242 4242 4242 4242", "replacement": "9244 7815 4042 5941", "start": 12, "end": 31, "confidence": 0.99},
{"label": "PERSON", "text": "Priya Sharma", "replacement": "[PERSON:3bihtlnay7dpeoi7coukzsn23mu4brvsh6xhlvf7cqzgi]", "start": 36, "end": 48, "confidence": 0.6},
{"label": "EMAIL", "text": "priya.sharma@example.com", "replacement": "rwkbj.mprpta@wcrwbuh.com", "start": 50, "end": 74, "confidence": 0.99},
{"label": "PHONE", "text": "+91 98765 43210", "replacement": "+31 74902 86938", "start": 76, "end": 91, "confidence": 0.7}],
"counts": {"total": 4, "by_label": {"CREDIT_CARD": 1, "PERSON": 1, "EMAIL": 1, "PHONE": 1}},
"key_version": 1}
| Response field | Meaning |
|---|---|
redacted | The text with every detected value replaced. Send this onward. |
strategy, reversible | Echo of the strategy; reversible is true for tokenize, synthetic, fpe. |
token_map | Replacement → original. Needed by /v1/restore for tokenize/synthetic. Always {} for fpe and the one-way strategies. It contains the originals: keep it in memory, don’t log it. |
entities | Per match: label, original text, replacement, start/end offsets in the input, confidence. Contains the originals too. |
counts | total and by_label. |
key_version | Integer: the key version that made these tokens. If you store fpe tokens to restore later, store this with them and pass it to /v1/restore-fpe or /v1/restore-json. |
POST/v1/redact/batch
Request: items (string[], max 100), strategy, labels, min_confidence. Each item is redacted independently, so each result has its own token_map, and [EMAIL_1] in two items can be two different emails. Restore each item with its own map. key_version is returned once, for the whole batch. Costs at least 1 unit per item.
{"results": [
{"redacted": "[EMAIL_1]", "strategy": "tokenize", "reversible": true, "token_map": {"[EMAIL_1]": "ravi@example.com"}, "entities": [ … ], "counts": { … }},
{"redacted": "call [PHONE_1]", "strategy": "tokenize", "reversible": true, "token_map": {"[PHONE_1]": "+91 98765 43210"}, "entities": [ … ], "counts": { … }}],
"count": 2, "key_version": 1}
To redact several strings with shared tokens in one unit, send them as a JSON array to /v1/redact-json. That is what the integrations do.
POST/v1/detect
Request: text, labels, min_confidence. Returns what was found without changing anything. Metered like redact.
{"entities": [
{"label": "PERSON", "text": "Priya Sharma", "start": 0, "end": 12, "confidence": 0.6},
{"label": "EMAIL", "text": "priya.sharma@example.com", "start": 14, "end": 38, "confidence": 0.99},
{"label": "PAN_IN", "text": "ABCPS1234F", "start": 44, "end": 54, "confidence": 0.99}],
"counts": {"total": 3}}
POST/v1/restore
Request: text (any text containing tokens, e.g. a model reply), token_map (object, from the redact response). For tokenize and synthetic. Free.
// request
{"text": "Hi [PERSON_1], we emailed [EMAIL_1]", "token_map": {"[PERSON_1]": "Priya Sharma", "[EMAIL_1]": "priya.sharma@example.com"}}
// response
{"text": "Hi Priya Sharma, we emailed priya.sharma@example.com"}
Only exact tokens from the map are replaced, in a single pass, so a restored value is never substituted again.
POST/v1/restore-fpe
Request: text, plus the same labels and min_confidence you used to redact (if any). Optional key_version (integer) from the redact response; it defaults to the current version, and an unknown version is a 400. Reverses fpe with your account’s key for that version; no map needed. Free.
// request
{"text": "Refund card 9244 7815 4042 5941 for [PERSON:3bihtlnay7dpeoi7coukzsn23mu4brvsh6xhlvf7cqzgi]", "key_version": 1}
// response
{"text": "Refund card 4242 4242 4242 4242 for Priya Sharma"}
There is no automatic fallback between key versions: an FF1 token decrypted under the wrong key gives a valid-looking but wrong value, not an error. Send the key_version that made the token.
Structured fpe tokens are found again by the deterministic detectors. A new structured value that you never redacted (say, an email an LLM invented) looks the same as a token and will be transformed. Bracketed [LABEL:…] tokens are authenticated and are immune.
POST/v1/redact-json
| Field | Type | Default | Meaning |
|---|---|---|---|
json | any | required | Object, array or scalar to redact. |
strategy, labels, min_confidence | As above. | ||
hints | bool | true | Built-in field-name hints: name, first_name, last_name, full_name → PERSON; email, phone, address, aadhaar, pan. |
field_map | object | null | null | Path → type, "IGNORE", "NUMBER" or null (no hint). Authoritative. |
keys | string | "report" | report: keys untouched, PII in keys counted; strict: 422 if any key contains PII; redact: keys redacted reversibly. |
Response: redacted (same shape), strategy, reversible, key_version, token_map, entities (each with a JSONPath-style path), type_changes ([{"path","from","to"}]), pii_in_keys, keys_redacted, counts. Full walkthrough: JSON & agents.
POST/v1/restore-json
Request: json (any JSON, not only the original shape), token_map or fpe: true (with optional key_version, default current, unknown → 400), plus type_changes, keys_redacted, field_map, hints, labels and min_confidence as used to redact. These contain paths and flags only, never PII. Response: {"json": …}. Free.
GET/v1/usage
{"plan": "free", "period": "2026-11", "units": 7, "requests": 7, "entities": 27,
"included_units": 1000, "overage_per_1k_usd": null, "per_minute": 60, "calls": 7}
units is what counts against your plan; requests counts metered calls; entities counts values found. overage_per_1k_usd: null means a hard cap (Free). Restores are not counted.
Public endpoints
POST /v1/signup{"email"}→201 {"account_id", "api_key", "plan", "note"}. 5 per hour per network. See Authentication.POST /v1/verify{"account_id", "token"}→{"verified": true}(from the verification email).GET /v1/entities→ supported labels and strategies.GET /v1/plans→ plans and the metering rule.GET /v1/health→ liveness.POST /v1/playground/redactand/v1/playground/restorepower the homepage demo: no key, demo-only keys, 2,000 characters, 10 a minute per network. Not for production use.
Response headers
Every response carries x-request-id; quote it when you contact us. Metered calls also carry x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset.
Errors
Errors are {"detail": …} and never echo your input.
| Status | Meaning |
|---|---|
400 | Account error: bad email, duplicate sign-up, bad verification token, key limit reached; or an unknown key_version on restore. |
401 | Missing, invalid or revoked API key. |
402 | Free-plan monthly quota reached. Paid plans go into overage instead. |
403 | Account suspended. |
413 | Body over 1 MB. |
422 | Invalid request (e.g. {"detail": [{"loc": ["body","text"], "msg": "Field required", "type": "missing"}]}), unknown strategy, or a JSON policy refusal such as keys: "strict" ("PII detected in object keys (keys='strict')"). |
429 | Rate limit. Wait retry-after seconds. |
503 | Detection failed closed: nothing was redacted or returned. Safe to retry. |