skills / rules

---
description: "DeepRead PII Removal API. Upload documents, automatically detect and redact personal information (SSN, credit cards, names, etc.), download redacted files. Endpoints, auth, and code examples."
alwaysApply: false
---

# DeepRead PII Removal API Reference

You are helping a developer redact PII from documents using DeepRead's API. You know the full API and can write working integration code in any language.

**Base URL:** `https://api.deepread.tech`
**Auth:** `X-API-Key` header with key from `https://www.deepread.tech/dashboard` or via the device authorization flow (see deepread-setup rule)

---

## What It Does

Upload a document (PDF, text, image). AI detects 14 types of PII automatically, redacts them using your chosen style, and returns a clean document with a detection report.

**PII types:** SSN, credit cards, emails, phone numbers, names, addresses, dates of birth, passport numbers, driver's licenses, bank accounts, IBANs, IP addresses, URLs, medical record numbers.

**Redaction styles:**
- `black_bar` — black rectangles over PII (default)
- `placeholder` — replace with labels like `[NAME]`, `[SSN]`
- `partial` — partial reveal like `***-**-6789`

---

## POST /v1/pii/redact — Submit for Redaction

**Auth:** `X-API-Key`. Content-Type: `multipart/form-data`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `file` | File | Yes | — | PDF, TXT, PNG, or JPEG |
| `redaction_style` | string | No | `"black_bar"` | `"black_bar"`, `"placeholder"`, or `"partial"` |
| `webhook_url` | string | No | — | HTTPS completion callback |
| `language` | string | No | `"en"` | `en`, `zh`, `es`, `hi`, `ar` |

**Response (200 OK):**
```json
{
  "id": "<job_id>",
  "status": "queued"
}
```

Processing is **asynchronous** — poll the GET endpoint or use a webhook.

**Errors:**
| Status | Meaning |
|--------|---------|
| 400 | Unsupported format, empty file, invalid params, non-HTTPS webhook |
| 401 | Invalid or missing API key |
| 402 | PII redaction is not on your plan (Enterprise), or the credits do not cover the job — the body names what is needed |
| 413 | Over the hard maximum: 2,000 pages or 500 MB |
| 429 | Requests per minute or pages in flight exceeded — `Retry-After` says when to retry |

---

## GET /v1/pii/{job_id} — Get Job Status & Results

**Auth:** `X-API-Key`

Poll every 5-10 seconds until `status` is `completed` or `failed`.

**Status values:** `queued` -> `processing` -> `completed` | `failed`

**Response (completed):**
```json
{
  "id": "<job_id>",
  "status": "completed",
  "progress_percent": 100,
  "redacted_file_url": "https://storage.deepread.tech/pii/.../redacted.pdf",
  "report": {
    "id": "<job_id>",
    "page_count": 3,
    "processing_time_ms": 4200,
    "pii_detected": {
      "SSN": {"count": 2, "pages": [1, 2], "confidence_avg": 0.97},
      "EMAIL": {"count": 3, "pages": [1], "confidence_avg": 0.99},
      "NAME": {"count": 5, "pages": [1, 2, 3], "confidence_avg": 0.92}
    },
    "total_redactions": 10,
    "redaction_policy": "black_bar",
    "confidence_threshold_used": 0.85
  },
  "error": null
}
```

**Response (failed):**
```json
{
  "id": "<job_id>",
  "status": "failed",
  "error": {"code": "DOCUMENT_CORRUPTED", "message": "Failed to parse the uploaded document"}
}
```

---

## Webhook Notification

If you provide `webhook_url`, DeepRead POSTs results when the job finishes:

**Completed:**
```json
{
  "job_id": "<job_id>",
  "status": "completed",
  "redacted_file_url": "<signed URL>",
  "report": {
    "page_count": 3,
    "processing_time_ms": 4200,
    "pii_detected": { ... },
    "total_redactions": 10
  }
}
```

**Failed:**
```json
{
  "job_id": "<job_id>",
  "status": "failed",
  "error": {"code": "DOCUMENT_CORRUPTED", "message": "..."}
}
```

**Signature — verify every delivery.** Each POST carries `X-DeepRead-Signature: t=<unix seconds>,v1=<hex>`: HMAC-SHA256 over `"<t>.<raw request body>"` keyed by your account's signing secret (`GET /dashboard/v1/webhooks/secret`, created on first read; rotate with `POST /dashboard/v1/webhooks/secret/rotate`). Verify over the exact bytes you received, compare in constant time, and reject a `t` older than five minutes:

```python
import hmac, hashlib, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts["t"])
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])
```

**Important:**
- Verify the signature before trusting a payload; `GET /v1/pii/{job_id}` stays the canonical result if you ever need to re-fetch
- Must be HTTPS (HTTP and private IPs rejected)
- Return 2xx to confirm delivery
- Design your endpoint for idempotency (may receive duplicates)

---

## Detection Report

| Field | Description |
|-------|-------------|
| `page_count` | Pages processed |
| `processing_time_ms` | Processing time in ms |
| `pii_detected` | Detections grouped by type: `{count, pages, confidence_avg}` |
| `total_redactions` | Total redactions applied |
| `redaction_policy` | Style used (black_bar/placeholder/partial) |
| `confidence_threshold_used` | Confidence threshold (default 0.85) |

---

## Error Codes

`INVALID_REQUEST` | `UNSUPPORTED_FORMAT` | `DOCUMENT_CORRUPTED` | `PASSWORD_PROTECTED` | `EMPTY_DOCUMENT` | `FILE_TOO_LARGE` | `RATE_LIMITED` | `INTERNAL_ERROR`

---

## Code Examples

### Python

```python
import requests
import time

API_KEY = "sk_live_YOUR_KEY"
BASE = "https://api.deepread.tech"

# Submit document for PII redaction
with open("contract.pdf", "rb") as f:
    resp = requests.post(
        f"{BASE}/v1/pii/redact",
        headers={"X-API-Key": API_KEY},
        files={"file": f},
        data={"redaction_style": "black_bar"}
    )
job_id = resp.json()["id"]

# Poll with backoff
delay = 5
while True:
    time.sleep(delay)
    result = requests.get(
        f"{BASE}/v1/pii/{job_id}",
        headers={"X-API-Key": API_KEY}
    ).json()

    if result["status"] in ("completed", "failed"):
        break
    delay = min(delay * 1.5, 30)

# Use results
if result["status"] == "completed":
    print(f"Download: {result['redacted_file_url']}")
    report = result["report"]
    print(f"Redactions: {report['total_redactions']}")
    for pii_type, info in report["pii_detected"].items():
        print(f"  {pii_type}: {info['count']} found")
```

### JavaScript / Node.js

```javascript
import fs from "fs";

const API_KEY = "sk_live_YOUR_KEY";
const BASE = "https://api.deepread.tech";

const form = new FormData();
form.append("file", fs.createReadStream("contract.pdf"));
form.append("redaction_style", "black_bar");

const { id: jobId } = await fetch(`${BASE}/v1/pii/redact`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY },
  body: form
}).then(r => r.json());

let delay = 5000, result;
do {
  await new Promise(r => setTimeout(r, delay));
  result = await fetch(`${BASE}/v1/pii/${jobId}`, {
    headers: { "X-API-Key": API_KEY }
  }).then(r => r.json());
  delay = Math.min(delay * 1.5, 30000);
} while (!["completed", "failed"].includes(result.status));

if (result.status === "completed") {
  console.log("Download:", result.redacted_file_url);
  console.log("Redactions:", result.report.total_redactions);
}
```

### cURL

```bash
# Submit for redaction
curl -X POST https://api.deepread.tech/v1/pii/redact \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@contract.pdf" \
  -F "redaction_style=black_bar"

# Get results
curl https://api.deepread.tech/v1/pii/JOB_ID \
  -H "X-API-Key: YOUR_KEY"
```

---

## Rate Limits & Plans

PII redaction is an **Enterprise** feature; other plans receive `402` with the plan named.

| Plan | Pages | Price |
|------|-------|-------|
| Free | 2,000 a month (resets on your signup day); no pii redaction | $0 (no credit card) |
| Standard | No page limits; no pii redaction | Prepaid credits from $10 per 1,000 pages (Parse $10, Extract $20, Deep Extract $40) |
| Enterprise | Custom — includes form fill, PII redaction, searchable PDF, retention, incognito, BYOK | Custom |

Submits per minute: 10 Free, 100 Standard, 500 Enterprise (`429` + `Retry-After` past the limit). Pages in flight (queued + processing jobs; a form-fill job counts as one page): 16 / 200 / 500. Hard maximum for everyone: 2,000 pages or 500 MB (`413`).

Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used`, `X-RateLimit-Reset`

---

## Troubleshooting

- **400 "Unsupported file format"** — Use PDF, TXT, PNG, or JPEG
- **400 "Webhook URL must use HTTPS"** — Change `http://` to `https://`
- **400 "Synthetic redaction style is not available"** — Use `black_bar`, `placeholder`, or `partial`
- **402 not on plan** — PII redaction is an Enterprise feature; upgrade the plan
- **429 with `Retry-After`** — Too many submits this minute or too many pages in flight; wait and retry
- **Status "failed"** — Check `error.code` and `error.message` in response

---

## Help the Developer

- **No API key yet** -> use the device authorization flow (see deepread-setup rule) or sign up at https://www.deepread.tech/dashboard
- **Redact a document** -> POST /v1/pii/redact with `file`, show code in their language
- **Check results** -> GET /v1/pii/{job_id}, explain the detection report
- **Download redacted doc** -> use `redacted_file_url` from completed response
- **Different styles** -> explain black_bar vs placeholder vs partial
- **Non-English docs** -> use `language` parameter (zh, es, hi, ar)
- **Real-time updates** -> set up `webhook_url`, build receiver endpoint
- **Hitting errors** -> check API key, plan limits, file format