POST /v1/cloak/detect

Finds personal data and returns a type, a category, a score, and a range for each entity. It never returns the matched value and it rewrites nothing. The caller already holds the text, so the caller cuts the ranges itself.

Request

string

required

The text. At most 12,000 characters. A longer text is refused with 400, never truncated.

string[]

Entity types to detect. Defaults to every type except location and date. An unknown type is a 400.

number

default:"0.5"

Lowest score to accept, from 0 to 1.

curl https://api.frostwolf.app/v1/cloak/detect \
  -H "Authorization: Bearer fw_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Contact jane@example.com", "entities": ["email"]}'

Response

object[]

Show properties

string

One of the 24 entity types.

string

pii, phi, pci, or credential.

integer

Inclusive, in UTF-16 code units.

integer

Exclusive, in UTF-16 code units.

number

The detector’s score.

integer

Characters in the submitted text.

string

Identity of the type mapping, so a change is auditable.

object

{ ran: true, latency_ms }.

{
  "entities": [
    { "type": "email", "category": "pii", "start": 8, "end": 24, "confidence": 1 }
  ],
  "scanned_chars": 24,
  "taxonomy_version": "2026.09.30",
  "ner": { "ran": true, "latency_ms": 41.5 }
}

Entities never overlap

The detector may label one region several ways. Overlapping detections are merged into their union, and the merged entity takes the type of the strongest member. A region is never reported twice.

Failure

There is no fail-open path. When detection is not configured the route answers 503 not_configured, and when the detector does not answer, or answers with something that cannot be trusted, it answers 503 unavailable. A clean-looking response after a failed check would report a payload as free of personal data that nobody looked at. The response is not cacheable, and nothing about the request is recorded.

​Request

​Response

​Entities never overlap

​Failure

Request

Response

Entities never overlap

Failure