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) or fpe: true.
  • type_changes and keys_redacted from the redact response, and the same field_map and hints you 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.

keysBehaviour
"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 under fpe (FF1, same digit count, first digit non-zero; needs at least 7 digits) and synthetic. Otherwise they become string tokens, listed in type_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)) == x as parsed values. Insignificant formatting (1.0 vs 1, 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.

Get a free API key

Free plan: 1,000 requests a month, all strategies. Your key is shown once — we store only a hash of it.

Prefer the terminal?
curl -s API/v1/signup \
  -H 'content-type: application/json' \
  -d '{"email":"you@company.com"}'

Contact

Our contact address is being set up.