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.

EndpointPurposeUnits
POST /v1/redactRedact text1 per 100 KB
POST /v1/redact/batchRedact up to 100 textsat least 1 per item
POST /v1/detectFind PII without changing it1 per 100 KB
POST /v1/restoreUndo tokenize / synthetic (with the map)free
POST /v1/restore-fpeUndo fpe (key only)free
POST /v1/redact-jsonRedact values in a JSON document1 per 100 KB
POST /v1/restore-jsonRestore a JSON documentfree
GET /v1/usageThis month’s usagefree
GET/POST /v1/keys, DELETE /v1/keys/{id}Key managementfree
POST /v1/signup, /v1/verify; GET /v1/entities, /v1/plans, /v1/healthAccount creation and public infofree, no key

Common request fields

FieldTypeDefaultMeaning
strategystring"tokenize"One of tokenize, mask, hash, partial, synthetic, fpe. See Strategies. Note: the integrations default to fpe; the raw API defaults to tokenize.
labelsstring[] | nullallOnly detect these types, e.g. ["EMAIL","CREDIT_CARD"]. See Detectors or GET /v1/entities.
min_confidencenumber0.0Drop 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 fieldMeaning
redactedThe text with every detected value replaced. Send this onward.
strategy, reversibleEcho of the strategy; reversible is true for tokenize, synthetic, fpe.
token_mapReplacement → 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.
entitiesPer match: label, original text, replacement, start/end offsets in the input, confidence. Contains the originals too.
countstotal and by_label.
key_versionInteger: 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

FieldTypeDefaultMeaning
jsonanyrequiredObject, array or scalar to redact.
strategy, labels, min_confidenceAs above.
hintsbooltrueBuilt-in field-name hints: name, first_name, last_name, full_name → PERSON; email, phone, address, aadhaar, pan.
field_mapobject | nullnullPath → type, "IGNORE", "NUMBER" or null (no hint). Authoritative.
keysstring"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/redact and /v1/playground/restore power 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.

StatusMeaning
400Account error: bad email, duplicate sign-up, bad verification token, key limit reached; or an unknown key_version on restore.
401Missing, invalid or revoked API key.
402Free-plan monthly quota reached. Paid plans go into overage instead.
403Account suspended.
413Body over 1 MB.
422Invalid 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')").
429Rate limit. Wait retry-after seconds.
503Detection failed closed: nothing was redacted or returned. Safe to retry.

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.