API reference
JSON & agents
An agent is about to send a payload to another model, a tool or a third-party API. Redact it on the way out; restore the reply on the way back.
your agent ──redact-json──▶ model / tool / 3rd party ──reply──▶ restore-json ──▶ your user
(PII → tokens) sees tokens only (tokens → PII)
Keys, nesting and non-sensitive values are unchanged, so the other side’s schema still works. One request per payload (1 unit up to 100 KB); restore is free.
The round trip, runnable
# pip install requests
import json
import os
import requests
API = os.environ.get("OBSCATE_BASE_URL", "https://api.obscate.com")
H = {"x-api-key": os.environ["OBSCATE_API_KEY"]}
payload = {
"customer": {"name": "Priya Sharma", "email": "priya.sharma@example.com", "pan": "ABCPS1234F"},
"txn": {"card": "4242424242424242", "amount": 1299.5},
}
# 1) Outbound: redact (keys, nesting and non-PII values are unchanged)
r = requests.post(f"{API}/v1/redact-json", headers=H, json={"json": payload, "strategy": "tokenize"})
r.raise_for_status()
red = r.json()
print("the model/tool sees:", json.dumps(red["redacted"]))
# 2) Your model or tool works on redacted data only (stand-in here)
c = red["redacted"]["customer"]
reply = {"to": c["email"], "body": f"Hi {c['name']}, your refund on card {red['redacted']['txn']['card']} is on its way."}
# 3) Inbound: restore the reply (free). Any JSON shape works, not just the original.
r = requests.post(f"{API}/v1/restore-json", headers=H, json={"json": reply, "token_map": red["token_map"]})
r.raise_for_status()
restored = r.json()["json"]
print("your user gets:", json.dumps(restored))
assert restored["to"] == "priya.sharma@example.com"
the model/tool sees: {"customer": {"name": "[PERSON_1]", "email": "[EMAIL_1]", "pan": "[PAN_IN_1]"}, "txn": {"card": "[CREDIT_CARD_1]", "amount": 1299.5}}
your user gets: {"to": "priya.sharma@example.com", "body": "Hi Priya Sharma, your refund on card 4242424242424242 is on its way."}
With fpe
With "strategy": "fpe" there is no map, and values keep their formats:
{"customer": {"name": "[PERSON:3bihtlnay7dpeoi7coukzsn23mu4brvsh6xhlvf7cqzgi]",
"email": "rwkbj.mprpta@wcrwbuh.com", "pan": "KJPDC7676P"},
"txn": {"card": "9244781540425941", "amount": 1299.5}}
Restore with {"json": …, "fpe": true}, plus type_changes if any.
What to pass back to restore-json
token_map(tokenize / synthetic) orfpe: true.type_changesandkeys_redactedfrom the redact response, and the samefield_mapandhintsyou sent. These hold paths and flags only, never PII.- The JSON can be any shape, such as the model’s reply. Tokens are restored wherever they appear.
Field-name hints and your own field map
Short values without context ({"name": "Ravi"}) are hard for any NER model. So, on by default, values under these keys are treated as that type regardless of the detector: name, first_name, last_name, full_name → PERSON, plus email, phone, address, aadhaar, pan. Matching ignores case and _/- (firstName works). "hints": false turns them off.
You know your schema better than a heuristic, so field_map is authoritative:
"field_map": {
"product.name": null, // a product, not a person: no hint, normal detection
"$.rows[*].label": "PERSON", // JSONPath-style, [*] matches any index
"sku": "IGNORE", // never scan or change
"balance": "NUMBER" // a genuine quantity (see Numbers)
}
PII in keys
Keys are never changed by default, but PII in keys ({"ravi@example.com": {…}}) is counted in pii_in_keys.
keys | Behaviour |
|---|---|
"report" (default) | Keys untouched, count reported. |
"strict" | Request refused (HTTP 422) if any key contains PII. |
"redact" | Keys redacted reversibly (fpe → map-free; other strategies → tokens in token_map). Pass keys_redacted: true to restore. |
Numbers
- Identifiers stored as numbers (a card or Aadhaar caught by checksum, or a number under a hinted or mapped identifier field) are redacted as strings. Each change is listed in
type_changes, e.g.[{"path": "$.txn.card", "from": "number", "to": "string"}], and undone by restore-json. - Genuine quantities (
field_map→"NUMBER") stay numbers underfpe(FF1, same digit count, first digit non-zero; needs at least 7 digits) andsynthetic. Otherwise they become string tokens, listed intype_changes.
JavaScript clients: send card numbers and other long IDs as strings. 4242424242424242 exceeds Number.MAX_SAFE_INTEGER (253 − 1); JSON.parse silently rounds it before it ever reaches us, so the original is already lost.
Guarantee and limits
restore-json(redact-json(x)) == xas parsed values. Insignificant formatting (1.0vs1, whitespace) isn’t preserved: it isn’t data. Property-tested on 10,000 generated nested payloads across strategies and key modes.- Depth up to 64, up to 10,000 values per payload, 1 MB body.
- If detection fails anywhere in the payload, the whole request is refused (503), never a partially redacted object.
Prefer a package?
The MCP server exposes redact_json/restore_json as agent tools; LangChain’s middleware and LlamaIndex’s query engine do the round trip for you.