{"openapi":"3.0.3","info":{"title":"PII Shield API","version":"1.0.0","description":"One deterministic pass over a piece of text that tells you what personal data it contains, what to replace, how abusive it is and how spammy it looks.\n\n**Detect:** 19 detectors - email, phone, payment cards (Luhn), IBAN (mod-97), US SSN, IPv4/IPv6, URL, birth dates, passport and licence numbers (label driven), postal addresses, person names (dictionary heuristic), API keys (entropy heuristic), JWTs, crypto wallets (base58check verified), MAC addresses, GitHub tokens and AWS key ids. Findings carry a 0-1 confidence and never overlap.\n\n**Redact:** three styles. Mask keeps the last N characters, label emits stable [EMAIL_1] tokens per distinct value, hash emits [EMAIL_xxxxxxxx] from the first 8 hex characters of the value's SHA-256 so identical values correlate across documents.\n\n**Screen:** a four language profanity lexicon (en, es, fr, de) that undoes leetspeak, repeated letters and single-character separators, plus an 11 signal spam score with the points and evidence behind every signal.\n\n**Limits, stated plainly:** detection is regex plus checksum plus small dictionaries. It will miss unusual formats (spaced-out card numbers, names outside the dictionary, non-Latin scripts) and it cannot know whether a string is personal data without context - a bare date is reported at confidence 0.5 unless a birth keyword is nearby. Passport, licence and street addresses need their usual labels. No ML model, no data leaves the edge, no upstream calls: identical input always returns identical output.\n\n**Built for:** LLM prompt sanitisers, customer support desks, log pipelines, UGC platforms, GDPR/SOC2 evidence runs.","termsOfService":"https://example.com/terms","contact":{"name":"Ayam Labs","url":"https://github.com/ayam04","email":"ayamullahkhan04@gmail.com"}},"servers":[{"url":"https://piishield.ayamk.in","description":"Direct origin"},{"url":"https://rapidapi.com","description":"RapidAPI marketplace"}],"tags":[{"name":"Scan","description":"Find personal data without changing the text"},{"name":"Redact","description":"Replace personal data with masks, labels or hashes"},{"name":"Screening","description":"Profanity, spam and the combined moderation verdict"},{"name":"Catalogue","description":"Machine readable detector and signal metadata"}],"x-provider":"Ayam Labs","components":{"schemas":{"ScanResult":{"type":"object","properties":{"textLength":{"type":"integer","minimum":0,"description":"Characters analysed.","example":64},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"},"description":"Non-overlapping findings sorted by start offset (maximum 2,000)."},"counts":{"type":"object","additionalProperties":{"type":"integer"},"description":"Findings per detector id. Detectors with no findings are omitted.","example":{"EMAIL":2,"PHONE":1}},"spans":{"type":"array","items":{"$ref":"#/components/schemas/Span"},"description":"Merged, non-overlapping character spans that a redactor would replace."},"risk":{"$ref":"#/components/schemas/RiskSummary"},"truncated":{"type":"boolean","description":"True when more than 2,000 findings were detected and the list was cut.","example":false},"durationMs":{"type":"number","description":"Server side processing time.","example":4}},"required":["textLength","findings","counts","spans","risk","truncated","durationMs"]},"Finding":{"type":"object","properties":{"type":{"type":"string","enum":["EMAIL","PHONE","CREDIT_CARD","IBAN","SSN","IPV4","IPV6","URL","DATE_OF_BIRTH","PASSPORT","DRIVERS_LICENSE","POSTAL_ADDRESS","PERSON_NAME","API_KEY","JWT","CRYPTO_WALLET","MAC_ADDRESS","GITHUB_TOKEN","AWS_KEY"],"description":"Detector id. See GET /v1/types for the full catalogue.","example":"EMAIL"},"value":{"type":"string","description":"Matched substring. Truncated to 256 characters when longer (see valueTruncated).","example":"jane.doe@example.com"},"start":{"type":"integer","minimum":0,"description":"0-based UTF-16 start offset in the submitted text.","example":17},"end":{"type":"integer","minimum":0,"description":"0-based end offset, exclusive.","example":37},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Detector confidence for this match. Checksum-backed detections are 0.9 and above; heuristics are lower.","example":0.99},"validator":{"type":"string","description":"Validator applied to the match, when any.","example":"email-syntax"},"detail":{"type":"string","description":"Optional detector specific note: card brand, IBAN country, wallet chain, entropy estimate.","example":"visa"},"valueTruncated":{"type":"boolean","description":"True when the original value was longer than 256 characters and value holds only its prefix.","example":true}},"required":["type","value","start","end","confidence"]},"Span":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"example":17},"end":{"type":"integer","minimum":0,"example":37},"length":{"type":"integer","minimum":0,"example":20},"types":{"type":"array","items":{"type":"string","enum":["EMAIL","PHONE","CREDIT_CARD","IBAN","SSN","IPV4","IPV6","URL","DATE_OF_BIRTH","PASSPORT","DRIVERS_LICENSE","POSTAL_ADDRESS","PERSON_NAME","API_KEY","JWT","CRYPTO_WALLET","MAC_ADDRESS","GITHUB_TOKEN","AWS_KEY"],"description":"Detector id. See GET /v1/types for the full catalogue.","example":"EMAIL"},"description":"Detectors merged into this span.","example":["EMAIL"]}},"required":["start","end","length","types"]},"RiskSummary":{"type":"object","properties":{"level":{"type":"string","enum":["none","low","medium","high","critical"],"description":"Risk band derived from the score. It never contains the raw values.","example":"medium"},"score":{"type":"number","minimum":0,"maximum":100,"description":"0-100 weighted risk score: per-detector weight, with a small multiplier for repeated hits.","example":42},"detectedTypes":{"type":"array","items":{"type":"string","enum":["EMAIL","PHONE","CREDIT_CARD","IBAN","SSN","IPV4","IPV6","URL","DATE_OF_BIRTH","PASSPORT","DRIVERS_LICENSE","POSTAL_ADDRESS","PERSON_NAME","API_KEY","JWT","CRYPTO_WALLET","MAC_ADDRESS","GITHUB_TOKEN","AWS_KEY"],"description":"Detector id. See GET /v1/types for the full catalogue.","example":"EMAIL"},"description":"Distinct detector ids that produced at least one finding, sorted.","example":["CREDIT_CARD","EMAIL"]}},"required":["level","score","detectedTypes"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"INVALID_INPUT","description":"Stable machine-readable error code."},"message":{"type":"string","example":"Request validation failed","description":"Human-readable explanation."},"details":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},{"type":"object","additionalProperties":{"nullable":true}}],"description":"Optional structured details (usually field-level validation issues)."},"hint":{"type":"string","example":"Pass the email address in the \"email\" query parameter."}},"required":["code","message"]},"requestId":{"type":"string","example":"8f14e45f-ceea-467f-a8e7-9b5e4f0e2a31"},"timestamp":{"type":"string","example":"2026-11-21T10:15:30.000Z"}},"required":["error","requestId","timestamp"]},"RedactResult":{"type":"object","properties":{"redactedText":{"type":"string","description":"Input text with every finding replaced according to style.","example":"Contact Jane Doe at ***@***.com."},"style":{"type":"string","enum":["mask","label","hash"],"example":"mask"},"keepLast":{"type":"integer","minimum":0,"maximum":8,"description":"Effective keepLast for style mask; 0 for the other styles.","example":4},"replacementCount":{"type":"integer","minimum":0,"example":2},"changed":{"type":"boolean","description":"False when nothing matched and redactedText equals the input.","example":true},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"counts":{"type":"object","additionalProperties":{"type":"integer"},"description":"Findings per detector id. Detectors with no findings are omitted.","example":{"EMAIL":2,"PHONE":1}},"spans":{"type":"array","items":{"$ref":"#/components/schemas/Span"}},"risk":{"$ref":"#/components/schemas/RiskSummary"},"mapping":{"type":"array","items":{"$ref":"#/components/schemas/HashMapping"},"description":"Present only for style hash. Correlates identical values without echoing them; it is a fingerprint, not a reversible cipher."},"truncated":{"type":"boolean","example":false},"durationMs":{"type":"number","example":5}},"required":["redactedText","style","keepLast","replacementCount","changed","findings","counts","spans","risk","truncated","durationMs"]},"HashMapping":{"type":"object","properties":{"hash":{"type":"string","description":"First 8 hex characters of the SHA-256 of the value.","example":"9f2b7c4d"},"type":{"type":"string","enum":["EMAIL","PHONE","CREDIT_CARD","IBAN","SSN","IPV4","IPV6","URL","DATE_OF_BIRTH","PASSPORT","DRIVERS_LICENSE","POSTAL_ADDRESS","PERSON_NAME","API_KEY","JWT","CRYPTO_WALLET","MAC_ADDRESS","GITHUB_TOKEN","AWS_KEY"],"description":"Detector id. See GET /v1/types for the full catalogue.","example":"EMAIL"},"occurrences":{"type":"integer","minimum":1,"description":"How often this exact value occurred.","example":2},"firstStart":{"type":"integer","minimum":0,"description":"Offset of the first occurrence.","example":17}},"required":["hash","type","occurrences","firstStart"]},"ProfanityResult":{"type":"object","properties":{"isProfane":{"type":"boolean","description":"True when at least one lexicon term matched.","example":true},"score":{"type":"number","minimum":0,"maximum":100,"description":"Weighted severity score: low 10, medium 25, high 50 per match, capped at 100.","example":50},"highestSeverity":{"type":"string","nullable":true,"enum":["low","medium","high",null],"example":"high"},"counts":{"type":"object","properties":{"low":{"type":"integer"},"medium":{"type":"integer"},"high":{"type":"integer"}},"required":["low","medium","high"],"description":"Matches per severity.","example":{"low":0,"medium":0,"high":1}},"matches":{"type":"array","items":{"$ref":"#/components/schemas/ProfanityMatch"},"description":"Matches sorted by offset, maximum 100."},"languages":{"type":"array","items":{"type":"string","enum":["en","es","fr","de"]},"example":["en"]},"truncated":{"type":"boolean","example":false},"durationMs":{"type":"number","example":3}},"required":["isProfane","score","highestSeverity","counts","matches","languages","truncated","durationMs"]},"ProfanityMatch":{"type":"object","properties":{"term":{"type":"string","description":"Normalised lexicon term that matched.","example":"fuck"},"matched":{"type":"string","description":"Substring exactly as it appeared in the input.","example":"f.u.c.k"},"start":{"type":"integer","minimum":0,"example":12},"end":{"type":"integer","minimum":0,"example":19},"severity":{"type":"string","enum":["low","medium","high"],"example":"high"},"category":{"type":"string","enum":["profanity","sexual","promotional"],"description":"profanity | sexual | promotional","example":"profanity"},"lang":{"type":"string","enum":["en","es","fr","de"],"example":"en"},"masked":{"type":"string","description":"First character plus asterisks, safe to log.","example":"f******"},"snippet":{"type":"string","description":"About 25 characters of context on each side with the match itself masked.","example":"...this f****** is..."},"obfuscated":{"type":"boolean","description":"True when leetspeak, repeated letters or separators had to be undone.","example":true}},"required":["term","matched","start","end","severity","category","lang","masked","snippet","obfuscated"]},"SpamResult":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"description":"Sum of the contributing signal points, capped at 100.","example":62},"band":{"type":"string","enum":["clean","suspicious","spam"],"description":"clean < 25, suspicious 25-59, spam 60 and above.","example":"spam"},"isSpam":{"type":"boolean","example":true},"signals":{"type":"array","items":{"$ref":"#/components/schemas/SpamSignal"},"description":"Only signals that contributed points are returned."},"features":{"$ref":"#/components/schemas/SpamFeatures"},"thresholds":{"type":"object","properties":{"suspicious":{"type":"integer"},"spam":{"type":"integer"}},"required":["suspicious","spam"],"description":"Band thresholds applied to the score.","example":{"suspicious":25,"spam":60}},"durationMs":{"type":"number","example":2}},"required":["score","band","isSpam","signals","features","thresholds","durationMs"]},"SpamSignal":{"type":"object","properties":{"id":{"type":"string","example":"shortener_link"},"label":{"type":"string","example":"Link shortener domain"},"weight":{"type":"integer","minimum":0,"description":"Maximum points this signal can contribute.","example":14},"points":{"type":"integer","minimum":0,"description":"Points this text contributed.","example":10},"evidence":{"type":"array","items":{"type":"string"},"description":"Short, value-free evidence strings (counts and matched phrases).","example":["bit.ly"]}},"required":["id","label","weight","points","evidence"]},"SpamFeatures":{"type":"object","properties":{"characters":{"type":"integer","minimum":0,"example":120},"words":{"type":"integer","minimum":0,"example":18},"links":{"type":"integer","minimum":0,"example":2},"shortenerLinks":{"type":"integer","minimum":0,"example":1},"exclamations":{"type":"integer","minimum":0,"example":5},"capsWords":{"type":"integer","minimum":0,"example":4},"emojis":{"type":"integer","minimum":0,"example":0},"repeatedRuns":{"type":"integer","minimum":0,"example":1},"hasPhone":{"type":"boolean","example":true}},"required":["characters","words","links","shortenerLinks","exclamations","capsWords","emojis","repeatedRuns","hasPhone"]},"ModerationResult":{"type":"object","properties":{"text":{"type":"object","properties":{"characters":{"type":"integer","minimum":0},"words":{"type":"integer","minimum":0}},"required":["characters","words"],"description":"Input size.","example":{"characters":140,"words":22}},"pii":{"$ref":"#/components/schemas/ScanResult"},"profanity":{"$ref":"#/components/schemas/ProfanityResult"},"spam":{"$ref":"#/components/schemas/SpamResult"},"verdict":{"$ref":"#/components/schemas/ModerationVerdict"},"durationMs":{"type":"number","example":8}},"required":["text","pii","profanity","spam","verdict","durationMs"]},"ModerationVerdict":{"type":"object","properties":{"action":{"type":"string","enum":["allow","review","block"],"description":"allow: nothing found. review: PII at medium/high risk, suspicious spam or any profanity. block: spam band, critical PII or a high severity profanity match.","example":"block"},"score":{"type":"number","minimum":0,"maximum":100,"description":"Weighted blend: 45% PII risk, 35% spam score, 20% profanity score.","example":55},"reasons":{"type":"array","items":{"type":"string"},"description":"Human readable reasons. Detector ids, counts and scores only, never raw values.","example":["PII detected: EMAIL x1, PHONE x1 (risk medium 40/100)","Spam score 62/100 (spam)"]}},"required":["action","score","reasons"]},"DetectorCatalogue":{"type":"object","properties":{"detectors":{"type":"array","items":{"$ref":"#/components/schemas/Detector"}},"redactionStyles":{"type":"array","items":{"type":"string","enum":["mask","label","hash"]},"example":["mask","label","hash"]},"profanityLanguages":{"type":"array","items":{"type":"string","enum":["en","es","fr","de"]},"example":["en","es","fr","de"]},"spamSignals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"weight":{"type":"integer"},"description":{"type":"string"}},"required":["id","label","weight","description"]}},"spamBands":{"type":"array","items":{"type":"string","enum":["clean","suspicious","spam"]},"example":["clean","suspicious","spam"]},"limits":{"type":"object","properties":{"maxTextCharacters":{"type":"integer","example":200000},"maxFindings":{"type":"integer","example":2000},"maxProfanityMatches":{"type":"integer","example":100},"maxFindingValueCharacters":{"type":"integer","example":256}},"required":["maxTextCharacters","maxFindings","maxProfanityMatches","maxFindingValueCharacters"],"description":"Hard caps applied to every request and response."}},"required":["detectors","redactionStyles","profanityLanguages","spamSignals","spamBands","limits"]},"Detector":{"type":"object","properties":{"id":{"type":"string","enum":["EMAIL","PHONE","CREDIT_CARD","IBAN","SSN","IPV4","IPV6","URL","DATE_OF_BIRTH","PASSPORT","DRIVERS_LICENSE","POSTAL_ADDRESS","PERSON_NAME","API_KEY","JWT","CRYPTO_WALLET","MAC_ADDRESS","GITHUB_TOKEN","AWS_KEY"],"description":"Detector id. See GET /v1/types for the full catalogue.","example":"EMAIL"},"label":{"type":"string","example":"Payment card number"},"description":{"type":"string","example":"13-19 digit number that passes the Luhn checksum."},"example":{"type":"string","example":"4111 1111 1111 1111"},"validator":{"type":"string","nullable":true,"description":"Named validator, or null for pattern-only detectors.","example":"luhn"},"confidenceRange":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"example":{"min":0.9,"max":0.97}},"riskWeight":{"type":"integer","description":"Contribution of a single hit to the risk score.","example":42}},"required":["id","label","description","example","validator","confidenceRange","riskWeight"]}},"parameters":{}},"paths":{"/v1/scan":{"post":{"tags":["Scan"],"summary":"Detect personal data and secrets in free text","description":"Runs every requested detector over the text and returns non-overlapping findings sorted by offset, counts per detector, merged replacement spans and a 0-100 risk summary. Checksum backed detectors (Luhn, IBAN mod-97, base58check) only report values that pass their check; heuristics such as PERSON_NAME and API_KEY report confidence below 0.6. Maximum 2,000 findings per response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500000,"description":"Free text to analyse. Up to 200,000 characters; longer payloads are rejected with 413 PAYLOAD_TOO_LARGE before any analysis runs.","example":"Card 4111 1111 1111 1111, SSH from 203.0.113.42, key AKIAIOSFODNN7EXAMPLE."},"types":{"type":"array","items":{"type":"string","enum":["EMAIL","PHONE","CREDIT_CARD","IBAN","SSN","IPV4","IPV6","URL","DATE_OF_BIRTH","PASSPORT","DRIVERS_LICENSE","POSTAL_ADDRESS","PERSON_NAME","API_KEY","JWT","CRYPTO_WALLET","MAC_ADDRESS","GITHUB_TOKEN","AWS_KEY"],"description":"Detector id. See GET /v1/types for the full catalogue.","example":"EMAIL"},"minItems":1,"maxItems":19,"description":"Restrict the scan to these detectors. Omit to run all 19 detectors.","example":["EMAIL","CREDIT_CARD"]},"minConfidence":{"type":"number","minimum":0,"maximum":1,"description":"Drop findings below this confidence (0-1). Heuristic detectors report low confidence: PERSON_NAME 0.45-0.72, API_KEY 0.4-0.55, DATE_OF_BIRTH 0.5-0.78. Use 0.6 to keep only strong matches. Defaults to 0.","example":0.6}},"required":["text"]}}}},"responses":{"200":{"description":"Scan result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanResult"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/redact":{"post":{"tags":["Redact"],"summary":"Return the text with personal data masked, labelled or hashed","description":"Same detection pass as /v1/scan, then replaces each finding. mask keeps the last keepLast characters, label uses stable [TYPE_n] tokens per distinct value, hash uses [TYPE_xxxxxxxx] built from the first 8 hex characters of the value's SHA-256 and additionally returns a mapping of hash to occurrence count. Raw values are never echoed in the mapping.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500000,"description":"Free text to analyse. Up to 200,000 characters; longer payloads are rejected with 413 PAYLOAD_TOO_LARGE before any analysis runs.","example":"Hi, I am Jane Doe. Reach me at jane.doe@example.com or 555-123-4567."},"types":{"type":"array","items":{"type":"string","enum":["EMAIL","PHONE","CREDIT_CARD","IBAN","SSN","IPV4","IPV6","URL","DATE_OF_BIRTH","PASSPORT","DRIVERS_LICENSE","POSTAL_ADDRESS","PERSON_NAME","API_KEY","JWT","CRYPTO_WALLET","MAC_ADDRESS","GITHUB_TOKEN","AWS_KEY"],"description":"Detector id. See GET /v1/types for the full catalogue.","example":"EMAIL"},"minItems":1,"maxItems":19,"description":"Restrict redaction to these detectors. Omit to redact everything.","example":["EMAIL","PHONE"]},"minConfidence":{"type":"number","minimum":0,"maximum":1,"description":"Only redact findings at or above this confidence (0-1). Defaults to 0.","example":0.5},"style":{"type":"string","enum":["mask","label","hash"],"description":"mask: keep the last 'keepLast' characters of each value. label: replace with [TYPE_n], the same label for the same value. hash: replace with [TYPE_xxxxxxxx], the first 8 hex characters of the SHA-256 of the value. Defaults to mask.","example":"mask"},"keepLast":{"type":"integer","minimum":0,"maximum":8,"description":"mask style only: how many trailing characters of each matched value stay readable (0-8, default 4). At least one character of every match is always masked.","example":4}},"required":["text"]}}}},"responses":{"200":{"description":"Redaction result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedactResult"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/profanity":{"post":{"tags":["Screening"],"summary":"Screen text for profanity, sexual and promotional terms","description":"Matches a hand written lexicon in English, Spanish, French and German after undoing leetspeak (0 to o, 1 to i, @ to a), repeated letters and single-character punctuation separators such as f.u.c.k. Every match reports its severity (low/medium/high), category, a masked term and a masked context snippet. No slurs are shipped in the lexicon.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500000,"description":"Free text to analyse. Up to 200,000 characters; longer payloads are rejected with 413 PAYLOAD_TOO_LARGE before any analysis runs.","example":"This sh1t is f.u.c.k.ing unbelievable!!!"},"langs":{"type":"array","items":{"type":"string","enum":["en","es","fr","de"]},"minItems":1,"maxItems":4,"description":"Languages to screen. Supported: en, es, fr, de. Defaults to [\"en\"].","example":["en","es"]}},"required":["text"]}}}},"responses":{"200":{"description":"Profanity result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfanityResult"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spam":{"post":{"tags":["Screening"],"summary":"Score text from 0 to 100 with 11 spam heuristics","description":"Additive heuristic scoring: exclamation density, ALL CAPS ratio, link count, shortener domains, money and prize phrases, urgency phrases, credential phishing, emoji density, repeated characters, phone plus link, and crypto scam phrasing. Returns the score, the band (clean, suspicious or spam) and every contributing signal with its maximum weight, awarded points and short evidence strings.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500000,"description":"Free text to analyse. Up to 200,000 characters; longer payloads are rejected with 413 PAYLOAD_TOO_LARGE before any analysis runs.","example":"Contact Jane Doe at jane.doe@example.com or +1 (555) 123-4567."}},"required":["text"]}}}},"responses":{"200":{"description":"Spam score","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpamResult"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/moderation":{"post":{"tags":["Screening"],"summary":"Combined PII, profanity and spam moderation in one call","description":"Flagship endpoint: one pass returns the full PII scan, the profanity result, the spam score and a combined verdict (allow, review or block) scored 45% PII risk, 35% spam and 20% profanity. Every reason names detector ids, counts and scores only - never raw values.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500000,"description":"Free text to analyse. Up to 200,000 characters; longer payloads are rejected with 413 PAYLOAD_TOO_LARGE before any analysis runs.","example":"WIN a $1000 gift card NOW!!! Verify your account at https://bit.ly/xk9 and call 555-123-4567. Email jane.doe@example.com."},"piiTypes":{"type":"array","items":{"type":"string","enum":["EMAIL","PHONE","CREDIT_CARD","IBAN","SSN","IPV4","IPV6","URL","DATE_OF_BIRTH","PASSPORT","DRIVERS_LICENSE","POSTAL_ADDRESS","PERSON_NAME","API_KEY","JWT","CRYPTO_WALLET","MAC_ADDRESS","GITHUB_TOKEN","AWS_KEY"],"description":"Detector id. See GET /v1/types for the full catalogue.","example":"EMAIL"},"minItems":1,"maxItems":19,"description":"Restrict the PII pass to these detectors. Omit to run all of them.","example":["EMAIL","PHONE"]},"minConfidence":{"type":"number","minimum":0,"maximum":1,"description":"Minimum confidence for PII findings (0-1). Defaults to 0.","example":0.5},"profanityLangs":{"type":"array","items":{"type":"string","enum":["en","es","fr","de"]},"minItems":1,"maxItems":4,"description":"Languages for the profanity pass. Defaults to [\"en\"].","example":["en"]}},"required":["text"]}}}},"responses":{"200":{"description":"Combined moderation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerationResult"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/types":{"get":{"tags":["Catalogue"],"summary":"List every detector, redaction style and spam signal","description":"Machine readable metadata for the whole API: detector id, label, description, example, validator, confidence range and risk weight; the three redaction styles; the four profanity languages; the 11 spam signals with weights; and the hard request and response caps. Use it to build a UI or to pick the types you pass to /v1/scan.","responses":{"200":{"description":"Detector catalogue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectorCatalogue"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}