API Reference

PII Detection & Redaction

Three endpoints that together give you a full round-trip: detect entities, replace them with placeholders, then restore the originals on the way out.

We can't guarantee every piece of PII gets caught

Detection makes a best effort, but some values will slip through — it's not a filter you can rely on 100% of the time. For traffic where even a rare slip matters, the stronger guarantee is routing: pin sensitive workloads to a Servada-hosted local model so nothing leaves Servada's perimeter in the first place. Redaction is the right fit when you need to use an external provider but want to strip identifiable fields before the request leaves; detection (/v1/pii/analyse) is useful for deciding between those paths at request time.

Typical workflow

For most use cases you'll combine redact and restore:

Call /v1/pii/redact on the input text. Keep the mapping.
Use the redacted text with whatever you want — an external LLM, a log sink, etc.
Call /v1/pii/restore with the response and the mapping to get the original values back.

If you just want to know what PII is in a piece of text without modifying it, use /v1/pii/analyse.

If you're using our chat completions, the anonymise processor does the redact/restore round-trip automatically — no manual wiring needed. For structured caller-side data (customer profiles, orders, account state), use haystack with redact: true: it walks the JSON tree leaf-by-leaf and uses your schema flags before falling back to detection. Both processors compose on the same request — they use disjoint placeholder namespaces (<INF_TYPE_N> for free-text, <INF_HAY_TYPE_N> for haystack).

Analyse text for PII

POST/v1/pii/analyse

Scopepii

Detect PII entities in text. Returns entities with type, span and confidence score.

Request

textrequiredstring: Text to analyse.
languagestring: Language code. Defaults to service default or "nl".
score_thresholdnumber: Minimum confidence (0-1). Defaults to 0.7.
service_idstring: Optional. Route to a specific PII service (see GET /v1/services). Falls back to the org’s default PII service when omitted.

json

{
  "text": "Jan Jansen woont in Amsterdam.",
  "language": "nl",
  "score_threshold": 0.7
}

Response · 200

has_piiboolean: True when at least one entity was found above the threshold.
entitiesarray: Entities with type, text, start, end (character offsets) and score.
entity_types_foundstring[]: Distinct entity types present in the result.

json

{
  "has_pii": true,
  "entities": [
    { "type": "PERSON", "text": "Jan Jansen", "start": 0, "end": 10, "score": 0.95 },
    { "type": "LOCATION", "text": "Amsterdam", "start": 20, "end": 29, "score": 0.92 }
  ],
  "entity_types_found": ["PERSON", "LOCATION"]
}

Redact PII

POST/v1/pii/redact

Scopepii

Replace PII entities with numbered placeholders like <PERSON_1>, <LOCATION_1>. Returns the redacted text and a mapping you can use to restore.

Request

Same body as /v1/pii/analyse, including the optional service_id routing override.

json

{
  "text": "Jan Jansen woont in Amsterdam.",
  "language": "nl"
}

Response · 200

redacted_textstring: Original text with entities replaced by <TYPE_N> placeholders.
mappingobject: Object mapping each placeholder back to the original value. Keep this if you want to restore later.
entities_redactednumber: Number of entities replaced.

json

{
  "redacted_text": "<PERSON_1> woont in <LOCATION_1>.",
  "mapping": {
    "<PERSON_1>": "Jan Jansen",
    "<LOCATION_1>": "Amsterdam"
  },
  "entities_redacted": 2
}

Restore PII

POST/v1/pii/restore

Scopepii

Apply a mapping to restore redacted placeholders back to their original values.

Request

textrequiredstring: Text containing placeholders — typically output from another service that you want to de-anonymise.
mappingrequiredobject: Placeholder → original-value map, from a prior /v1/pii/redact response.

json

{
  "text": "<PERSON_1> woont in <LOCATION_1>.",
  "mapping": {
    "<PERSON_1>": "Jan Jansen",
    "<LOCATION_1>": "Amsterdam"
  }
}

Response · 200

restored_textstring: Text with all matched placeholders replaced.
replacements_madenumber: Number of placeholders successfully replaced.

json

{
  "restored_text": "Jan Jansen woont in Amsterdam.",
  "replacements_made": 2
}