# Redactly API reference

> The Redactly API detects and redacts personally identifiable information in text, JSON, and CSV. Every request is authenticated with an API key and returns the redacted output together with the entities that were found.

Canonical: https://bitbanger.in/docs
Last updated: 2026-10-26

## Base URL

```
https://api.bitbanger.in
```

## Authentication

Every redaction endpoint requires an API key in the `X-API-Key` header. Keys start with `rdct_`. They are shown once at creation and only a SHA-256 hash is stored server-side, so a lost key has to be replaced rather than recovered.

```
X-API-Key: rdct_your_key_here
```

A missing, invalid, or revoked key returns `401`.

## POST /v1/redact

Redacts PII from a string. The response contains the original text, the redacted text, the entity list with character spans and confidence scores, and a count.

### Request body

| Field | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `text` | string | yes | — | Text to redact. Must not be empty. |
| `style` | string | no | `replace` | One of `replace`, `mask`, or `remove`. |
| `threshold` | number | no | `0.5` | Minimum confidence between 0 and 1. |
| `entities` | string[] | no | all types | Restrict detection to specific labels, for example `["PERSON","EMAIL"]`. |
| `webhook_url` | URL | no | — | If set, the result is also POSTed to this URL after redaction. |

### Example request

```bash
curl -X POST https://api.bitbanger.in/v1/redact \
  -H "X-API-Key: rdct_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Call John Smith at 555-867-5309 or john@acme.com",
    "style": "replace",
    "threshold": 0.5
  }'
```

### Response

```json
{
  "original": "Call John Smith at 555-867-5309 or john@acme.com",
  "redacted": "Call [PERSON] at [PHONE] or [EMAIL]",
  "entities": [
    {
      "entity": "PERSON",
      "text": "John Smith",
      "start": 5,
      "end": 15,
      "score": 0.998
    }
  ],
  "entity_count": 3
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `original` | string | The input text, unchanged. |
| `redacted` | string | The same text with detected spans transformed by the chosen style. |
| `entities` | array | One object per hit: `entity`, `text`, `start`, `end`, `score`. |
| `entity_count` | integer | Number of entities redacted. |

## POST /v1/redact/file

Redacts a `.json` or `.csv` upload and returns a redacted file. JSON is walked recursively so every string value at any depth is redacted; CSV is redacted cell by cell with the structure preserved.

### Form fields

| Field | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `file` | file | yes | — | A `.json` or `.csv` file. Other extensions return `422`. |
| `style` | string | no | `replace` | `replace`, `mask`, or `remove`. |
| `threshold` | number | no | `0.5` | Minimum confidence between 0 and 1. |

### Example request

```bash
curl -X POST https://api.bitbanger.in/v1/redact/file \
  -H "X-API-Key: rdct_your_key_here" \
  -F "file=@customers.csv" \
  -F "style=mask" \
  -F "threshold=0.6" \
  --output customers_redacted.csv
```

JSON input returns `application/json` with the filename suffix `_redacted.json`. CSV input returns `text/csv`.

## GET /health

Returns service status and the identifier of the detector build currently loaded. The identifier is opaque and changes when the detector is upgraded; treat it as a version string rather than a product name.

```bash
curl https://api.bitbanger.in/health
```

```json
{"status":"ok","model":"redactly-pii-encoder-v1"}
```

## Redaction styles

| Style | Output | Use when |
| :--- | :--- | :--- |
| `replace` | `John Smith` becomes `[PERSON]` | You need the document to stay readable for a human reviewer. |
| `mask` | Block characters matching the original length | You want to preserve layout and character counts. |
| `remove` | Deleted entirely | You want no trace of the value in the output. |

## Entity types

Redactly detects 30+ entity types out of the box, grouped into personal identifiers (names, usernames, dates of birth), contact details (emails, phone numbers, addresses), financial data (card numbers, IBANs, bank accounts), government identifiers (SSNs, passport and driver's licence numbers), digital identifiers (IP and MAC addresses), and medical data (record and health plan numbers).

Use the `entities` field on `/v1/redact` to restrict a request to specific labels.

## Errors

| Status | Cause |
| :--- | :--- |
| `401` | Missing, invalid, or revoked API key. |
| `422` | Empty `text`, an unsupported file extension, or malformed JSON or CSV. |
| `503` | The model is still loading. Retry shortly. |

## Related

- [Home](https://bitbanger.in/) — product overview, comparison, pricing, FAQ
- [Security and data handling](https://bitbanger.in/security)
- [llms.txt](https://bitbanger.in/llms.txt) — compact index for language models
- [llms-full.txt](https://bitbanger.in/llms-full.txt) — every page concatenated