Name: Hush PII Redaction API for LLM prompts and logs
Brand: hybrid-forge-lab
SKU: api-hybrid-forge-lab-hush
Availability: InStock
Author: API Market

# Hush PII Redaction API

## Overview

The Hush API finds personal data in any text and replaces it with placeholders like `<EMAIL_1>`, masks or hashes. Your LLM, logs or helpdesk get the redacted text, and you keep the mapping to restore the originals in one call.

Detection uses patterns plus check digits, so the same input always gives the same output. The service is stateless: nothing is stored and request content is never logged.

## Features

*   **11 entity types**: listed below, filtered per request with `entities`.
    *   `EMAIL`, `PHONE`, `IBAN`, `CREDIT_CARD`, `IP` and `URL`.
    *   `PT_NIF` (NIF and NIPC) and `PT_CC` (Cartão de Cidadão).
    *   `ES_DNI` (DNI and NIE), `IT_CF` (codice fiscale) and `DE_TAX_ID` (Steuer-IdNr).
*   **Check digits, not guesses**: IBANs pass MOD 97 with the right length for their country, and cards pass Luhn with a real issuer prefix. NIF, DNI, codice fiscale and Steuer-IdNr pass their official check, and a number that fails is left alone.
*   **Three modes**: `placeholder` (reversible), `mask` (a hint for humans, such as `j***@***.com`) and `hash` (a stable SHA-256 token per value).
*   **Round trip**: `POST /v1/restore` puts the original values back into any text that contains the placeholders, such as an LLM reply.
*   **Exact offsets**: every entity comes with its type and `start`/`end` in the original text, in Unicode code points.
*   **Phone formats**: international numbers are always found, and `locale` narrows national formats to PT, ES, FR, DE, GB or US.

## Use Cases

*   **LLM prompts and RAG**: strip support tickets, emails and chat transcripts before they go to a model provider, then restore the draft reply.
*   **Logs and analytics**: hash emails and IPs in log lines, so the same user is still the same token but the raw value never lands in your log store.
*   **Helpdesk and CRM**: mask cards and IBANs that customers paste into forms, so agents see a hint and the full number isn't copied into every system.
*   **Test data and exports**: turn production text into shareable fixtures, or check a document for personal data before it's published.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/hybrid-forge-lab/hush
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Health check

Returns `ok`, the service version and its uptime in seconds.

**Method:** `GET`

**Endpoint:** `/v1/health`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/hush/v1/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "version": "0.2.0",
  "uptime_s": 0
}
```

#### 2. Redact a text

Finds personal data in `text` and replaces each value with a placeholder, a mask or a hash token. In `placeholder` mode the response includes the `mapping` you need for `POST /v1/restore`.

**Method:** `POST`

**Endpoint:** `/v1/redact`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `text` | body | The text to redact. It is never stored or logged. | string | Yes | - | 100,000 characters |
| `entities` | body | Only look for these types, for example `["EMAIL", "PHONE"]`. Unknown types return `422`. | array of strings | No | all 11 types | 11 items |
| `mode` | body | `placeholder` (reversible), `mask` (one-way hint) or `hash` (one-way token). | string | No | `placeholder` | - |
| `locale` | body | `PT`, `ES`, `FR`, `DE`, `GB` or `US`, or a tag such as `pt-PT` or `en_GB`, for national phone formats. Other values return `422`. | string | No | all six | 10 characters |

**Example Request:**

The sample is a support ticket with a test card number and made-up personal data.

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/hush/v1/redact' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"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."}'
```

**Example Response (200 OK):**

```json
{
  "redacted": "Hello, I was charged twice for order 48213. My card is <CREDIT_CARD_1> and the refund should go to <IBAN_1>. Invoice NIF: <PT_NIF_1>. Reach me at <EMAIL_1> or <PHONE_1>.",
  "entities": [
    {
      "type": "CREDIT_CARD",
      "start": 55,
      "end": 74,
      "placeholder": "<CREDIT_CARD_1>"
    },
    {
      "type": "IBAN",
      "start": 103,
      "end": 134,
      "placeholder": "<IBAN_1>"
    },
    {
      "type": "PT_NIF",
      "start": 149,
      "end": 158,
      "placeholder": "<PT_NIF_1>"
    },
    {
      "type": "EMAIL",
      "start": 172,
      "end": 195,
      "placeholder": "<EMAIL_1>"
    },
    {
      "type": "PHONE",
      "start": 199,
      "end": 215,
      "placeholder": "<PHONE_1>"
    }
  ],
  "mapping": {
    "<CREDIT_CARD_1>": "4111 1111 1111 1111",
    "<IBAN_1>": "PT50 0002 0123 1234 5678 9015 4",
    "<PT_NIF_1>": "123456789",
    "<EMAIL_1>": "joana.silva@example.com",
    "<PHONE_1>": "+351 912 345 678"
  }
}
```

The order number `48213` is left alone because it matches no entity type. In `mask` and `hash` modes `mapping` is empty, because those outputs can't be restored.

#### 3. Restore a text

Puts the original values back into a text that contains placeholders, using the `mapping` from `POST /v1/redact`. Placeholders that are not in the mapping are left as they are.

**Method:** `POST`

**Endpoint:** `/v1/restore`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `text` | body | The text with placeholders, for example an LLM reply to the redacted ticket. | string | Yes | - | 200,000 characters |
| `mapping` | body | The `mapping` returned by a `placeholder` redaction. Keys that aren't placeholders like `<EMAIL_1>` return `422`. | object | Yes | - | 50,000 entries, 100,000 characters of values |

**Example Request:**

The `mapping` is the one returned by the redact example above.

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/hush/v1/restore' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hi, the refund to <IBAN_1> is on its way; we will confirm at <EMAIL_1>.", "mapping": {"<CREDIT_CARD_1>": "4111 1111 1111 1111", "<IBAN_1>": "PT50 0002 0123 1234 5678 9015 4", "<PT_NIF_1>": "123456789", "<EMAIL_1>": "joana.silva@example.com", "<PHONE_1>": "+351 912 345 678"}}'
```

**Example Response (200 OK):**

```json
{
  "text": "Hi, the refund to PT50 0002 0123 1234 5678 9015 4 is on its way; we will confirm at joana.silva@example.com."
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The text was processed. A text with no personal data is still a 200, with `redacted` equal to the input. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key has no active subscription to this API, your plan quota is used up, or the endpoint is not part of your plan. |
| 413 | Payload Too Large | `text` is over 100,000 characters (redact) or 200,000 (restore), `mapping` is over its limits, the restored text is over 1,000,000 characters, or the body is over 4 MB. |
| 415 | Unsupported Media Type | The body isn't sent as `application/json`. |
| 422 | Unprocessable Entity | A field is missing or malformed, an entity type or mode is unknown, the locale is unsupported, or a restore `mapping` has keys that aren't placeholders. |
| 429 | Too Many Requests | You sent more requests per second than your plan allows. Wait and try again. |

## Rate Limits

Each request counts as one call. Calls stop when the quota runs out until the next month.

*   **Free**: 15 requests, a 7-day free trial, once per customer, 2 requests per second.
*   **Pro**: 10,000 requests per month, 10 requests per second.
*   **Ultra**: 60,000 requests per month, 20 requests per second.
*   **Mega**: 300,000 requests per month, 50 requests per second.

Going over your plan's requests per second returns `429 Too Many Requests`. Back off and retry after a short pause.

## FAQ

*   **Does it find names and addresses?**

    No. Hush detects structured data with patterns and check digits, so results stay predictable and explainable.

*   **Can mask or hash output be restored?**

    No. Only `placeholder` mode is reversible, and in the other modes `mapping` is empty.

*   **Is hash mode anonymisation?**

    No, it's pseudonymisation. The token is the start of an unkeyed SHA-256 of the normalised value, so treat the output as personal data under the GDPR.

*   **What about false positives?**

    Numbers with a check digit are only redacted when the check passes, so an invalid card, IBAN or NIF stays as it is. Phone numbers have no check digit, so national formats need their usual grouping.

*   **How do offsets work with emoji?**

    `start` and `end` count Unicode code points in the original text, like Python strings. In JavaScript, use `Array.from(text)` before slicing.

*   **Is my text stored?**

    No. Text is processed in memory and discarded, and request and response content is never logged.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Redact emails, phones, IBANs, cards, IPs and EU tax IDs with check digits, send the text to your LLM, then restore the originals in one call.

Hush PII Redaction API for LLM prompts and logs

Hush PII Redaction and Restore