{"openapi":"3.1.0","info":{"title":"Hush PII Redaction API","description":"Find personal data in text (emails, phone numbers, IBANs, payment cards, IP addresses, URLs, Portuguese NIF/NIPC and Cartão de Cidadão, Spanish DNI/NIE, Italian codice fiscale, German tax ID) with patterns and check digits, and replace it with placeholders before the text goes to an LLM, a log or a ticket system. /v1/restore puts the originals back from the mapping you keep. Stateless: nothing is stored and request content is never logged.","version":"0.2.0"},"paths":{"/v1/health":{"get":{"tags":["meta"],"summary":"Liveness and version (no auth)","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"example":{"ok":true,"version":"0.2.0","uptime_s":42}}}}}}},"/v1/redact":{"post":{"tags":["redact"],"summary":"Find PII (emails, phones, IBANs, cards, IPs, URLs, PT/ES/IT/DE IDs) and replace it with placeholders, masks or hashes","operationId":"redact_text_v1_redact_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedactRequest"},"examples":{"placeholder":{"summary":"Support ticket, placeholders (reversible)","value":{"text":"Hello, I was charged twice for order 48213. My card is 4111 1111 1111 1111 and the refund should go to PT50 0002 0123 1234 5678 9015 4. Invoice NIF: 123456789. Reach me at joana.silva@example.com or +351 912 345 678."}},"mask":{"summary":"Masked, keeps a hint","value":{"text":"Hello, I was charged twice for order 48213. My card is 4111 1111 1111 1111 and the refund should go to PT50 0002 0123 1234 5678 9015 4. Invoice NIF: 123456789. Reach me at joana.silva@example.com or +351 912 345 678.","mode":"mask"}},"hash":{"summary":"Hashed (pseudonymisation)","value":{"text":"Hello, I was charged twice for order 48213. My card is 4111 1111 1111 1111 and the refund should go to PT50 0002 0123 1234 5678 9015 4. Invoice NIF: 123456789. Reach me at joana.silva@example.com or +351 912 345 678.","mode":"hash"}},"filter":{"summary":"Only emails and phones, Portuguese formats","value":{"text":"Call 912 345 678 or write to ana@example.pt","entities":["EMAIL","PHONE"],"locale":"pt-PT"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedactResponse"},"examples":{"placeholder":{"summary":"Support ticket, placeholders (reversible)","value":{"redacted":"Hello, I was charged twice for order 48213. My card is and the refund should go to . Invoice NIF: . Reach me at or .","entities":[{"type":"CREDIT_CARD","start":55,"end":74,"placeholder":""},{"type":"IBAN","start":103,"end":134,"placeholder":""},{"type":"PT_NIF","start":149,"end":158,"placeholder":""},{"type":"EMAIL","start":172,"end":195,"placeholder":""},{"type":"PHONE","start":199,"end":215,"placeholder":""}],"mapping":{"":"4111 1111 1111 1111","":"PT50 0002 0123 1234 5678 9015 4","":"123456789","":"joana.silva@example.com","":"+351 912 345 678"}}},"mask":{"summary":"Masked, keeps a hint","value":{"redacted":"Hello, I was charged twice for order 48213. My card is **** **** **** 1111 and the refund should go to PT** **** **** **** **** *015 4. Invoice NIF: ******789. Reach me at j***@***.com or +351 *** *** 678.","entities":[{"type":"CREDIT_CARD","start":55,"end":74,"placeholder":"**** **** **** 1111"},{"type":"IBAN","start":103,"end":134,"placeholder":"PT** **** **** **** **** *015 4"},{"type":"PT_NIF","start":149,"end":158,"placeholder":"******789"},{"type":"EMAIL","start":172,"end":195,"placeholder":"j***@***.com"},{"type":"PHONE","start":199,"end":215,"placeholder":"+351 *** *** 678"}],"mapping":{}}},"hash":{"summary":"Hashed (pseudonymisation)","value":{"redacted":"Hello, I was charged twice for order 48213. My card is and the refund should go to . Invoice NIF: . Reach me at or .","entities":[{"type":"CREDIT_CARD","start":55,"end":74,"placeholder":""},{"type":"IBAN","start":103,"end":134,"placeholder":""},{"type":"PT_NIF","start":149,"end":158,"placeholder":""},{"type":"EMAIL","start":172,"end":195,"placeholder":""},{"type":"PHONE","start":199,"end":215,"placeholder":""}],"mapping":{}}},"filter":{"summary":"Only emails and phones, Portuguese formats","value":{"redacted":"Call or write to ","entities":[{"type":"PHONE","start":5,"end":16,"placeholder":""},{"type":"EMAIL","start":29,"end":43,"placeholder":""}],"mapping":{"":"912 345 678","":"ana@example.pt"}}}}}}},"401":{"description":"Missing or wrong credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"Unauthorized"}}}},"413":{"description":"Text, mapping or body over the limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"text is longer than 100,000 characters"}}}},"415":{"description":"Body is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"Content-Type must be application/json"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"example":{"detail":"unsupported locale 'it-IT'; use PT, ES, FR, DE, GB or US, or a tag such as pt-PT"}}}}}}},"/v1/restore":{"post":{"tags":["redact"],"summary":"Put the original values back into a text with placeholders, using the mapping from /v1/redact","operationId":"restore_text_v1_restore_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreRequest"},"examples":{"llm":{"summary":"An LLM's reply to the redacted ticket","value":{"text":"Hi, the refund to is on its way; we will confirm at .","mapping":{"":"4111 1111 1111 1111","":"PT50 0002 0123 1234 5678 9015 4","":"123456789","":"joana.silva@example.com","":"+351 912 345 678"}}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreResponse"},"examples":{"llm":{"summary":"An LLM's reply to the redacted ticket","value":{"text":"Hi, the refund to PT50 0002 0123 1234 5678 9015 4 is on its way; we will confirm at joana.silva@example.com."}}}}}},"401":{"description":"Missing or wrong credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"Unauthorized"}}}},"413":{"description":"Text, mapping or body over the limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"text is longer than 100,000 characters"}}}},"415":{"description":"Body is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"Content-Type must be application/json"}}}},"422":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"example":{"detail":"unsupported locale 'it-IT'; use PT, ES, FR, DE, GB or US, or a tag such as pt-PT"}}}}}}}},"components":{"schemas":{"Entity":{"properties":{"type":{"type":"string","enum":["EMAIL","PHONE","IBAN","CREDIT_CARD","IP","URL","PT_NIF","PT_CC","ES_DNI","IT_CF","DE_TAX_ID"],"title":"Type"},"start":{"type":"integer","title":"Start","description":"Start offset in the ORIGINAL text, as a Python str index (Unicode code points, not bytes and not UTF-16 units)"},"end":{"type":"integer","title":"End","description":"End offset (exclusive) in the original text, same unit as start"},"placeholder":{"type":"string","title":"Placeholder","description":"What replaced the value in `redacted`: the placeholder, the mask or the hash token, depending on mode"}},"type":"object","required":["type","start","end","placeholder"],"title":"Entity"},"Error":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"Error","examples":[{"detail":"text is longer than 100,000 characters"}]},"Health":{"properties":{"ok":{"type":"boolean","title":"Ok"},"version":{"type":"string","title":"Version"},"uptime_s":{"type":"integer","title":"Uptime S"}},"type":"object","required":["ok","version","uptime_s"],"title":"Health","examples":[{"ok":true,"uptime_s":42,"version":"0.1.0"}]},"RedactRequest":{"properties":{"text":{"type":"string","title":"Text","description":"The text to redact, up to 100,000 characters (413 above). Never stored or logged"},"entities":{"anyOf":[{"items":{"type":"string","enum":["EMAIL","PHONE","IBAN","CREDIT_CARD","IP","URL","PT_NIF","PT_CC","ES_DNI","IT_CF","DE_TAX_ID"]},"type":"array","maxItems":11,"minItems":1},{"type":"null"}],"title":"Entities","description":"Only look for these types (default: all). IP covers IPv4 and IPv6; PT_NIF covers NIF and NIPC; ES_DNI covers DNI and NIE"},"mode":{"type":"string","enum":["placeholder","mask","hash"],"title":"Mode","description":"placeholder: , reversible with /v1/restore and the returned mapping. mask: keeps a hint (j***@***.com, **** **** **** 1111), one-way. hash: , the first 12 hex characters of an unkeyed SHA-256 of the normalised value, the same in every request (pseudonymisation, not anonymisation), one-way","default":"placeholder"},"locale":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Locale","description":"Country for national phone formats: PT, ES, FR, DE, GB or US, or a tag such as pt-PT or en_GB. Default: all six. International numbers (+351 ..., 0044 ...) are always detected"}},"type":"object","required":["text"],"title":"RedactRequest","examples":[{"mode":"placeholder","text":"Hello, I was charged twice for order 48213. My card is 4111 1111 1111 1111 and the refund should go to PT50 0002 0123 1234 5678 9015 4. Invoice NIF: 123456789. Reach me at joana.silva@example.com or +351 912 345 678."}]},"RedactResponse":{"properties":{"redacted":{"type":"string","title":"Redacted","description":"The text with every detected value replaced. Identical to `text` when nothing was found"},"entities":{"items":{"$ref":"#/components/schemas/Entity"},"type":"array","title":"Entities","description":"Every replaced value in text order"},"mapping":{"additionalProperties":{"type":"string"},"type":"object","title":"Mapping","description":"placeholder → original value, to send to /v1/restore. The same value always gets the same placeholder within one request. Empty in mask and hash modes, which can't be restored"}},"type":"object","required":["redacted","entities","mapping"],"title":"RedactResponse","examples":[{"entities":[{"end":74,"placeholder":"","start":55,"type":"CREDIT_CARD"},{"end":134,"placeholder":"","start":103,"type":"IBAN"},{"end":158,"placeholder":"","start":149,"type":"PT_NIF"},{"end":195,"placeholder":"","start":172,"type":"EMAIL"},{"end":215,"placeholder":"","start":199,"type":"PHONE"}],"mapping":{"":"4111 1111 1111 1111","":"joana.silva@example.com","":"PT50 0002 0123 1234 5678 9015 4","":"+351 912 345 678","":"123456789"},"redacted":"Hello, I was charged twice for order 48213. My card is and the refund should go to . Invoice NIF: . Reach me at or ."}]},"RestoreRequest":{"properties":{"text":{"type":"string","title":"Text","description":"Text containing placeholders (e.g. an LLM's answer to the redacted text), up to 200,000 characters"},"mapping":{"additionalProperties":{"type":"string"},"type":"object","title":"Mapping","description":"The mapping returned by /v1/redact with mode=placeholder (up to 50,000 entries, 100,000 characters of values). Keys that aren't placeholders like are rejected with 422: mask and hash output can't be restored"}},"type":"object","required":["text","mapping"],"title":"RestoreRequest","examples":[{"mapping":{"":"joana.silva@example.com","":"PT50 0002 0123 1234 5678 9015 4"},"text":"Refund sent to ; confirmation emailed to ."}]},"RestoreResponse":{"properties":{"text":{"type":"string","title":"Text","description":"The text with every placeholder found in `mapping` replaced by its original. Placeholders not in the mapping are left as they are"}},"type":"object","required":["text"],"title":"RestoreResponse","examples":[{"text":"Refund sent to PT50 0002 0123 1234 5678 9015 4; confirmation emailed to joana.silva@example.com."}]},"ValidationError":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail","description":"A sentence for our own checks, or the list of schema violations (loc, msg, type) for malformed fields"}},"type":"object","required":["detail"],"title":"ValidationError"}}}}