Redact

Mask or de-identify PII in a document. Returns redacted page images, an updated text block, and a summary of masked entities.

Cost$0.05/page

Latency~3s

HyperLM

Step 1: Upload your document — call POST /v1/documents/upload to get a document_key

Request

Headers

Name	Type	Required	Allowed values	Description
`X-API-Key`	`string`	required	—	Your HyperAPI key (hk_live_* or hk_test_*).
`X-Async`	`string`	optional	`truefalse`	Set to "true" to process asynchronously and receive a job ID.

Body

Name	Type	Required	Description
`document_key`	`string`	required	S3 document key obtained from the presigned upload endpoint (/v1/documents/upload).
`pii_config`	`string`	optional	Optional JSON object configuring which PII types are detected, sent as a single JSON-encoded string. Invalid JSON returns HTTP 400. Shape: `{"mode": "extend" \| "replace", "types": [{"name": string, "description": string, "has_synthetic_replacement": bool}]}`. `mode=extend` (default) adds the supplied types to the built-in default set (deduplicated by name); `mode=replace` uses only the supplied types and requires at least one. Each type's `name` labels the entity, `description` guides detection, and `has_synthetic_replacement` controls whether `deidentify` substitutes synthetic text for that type.

Query Parameters

Name	Type	Default	Allowed values	Description
`mode`	`string`	`redact`	`redactdeidentify`	`redact` overlays black boxes over detected PII; `deidentify` substitutes synthetic replacement text. Defaults to `redact`.
`include_logos`	`string`	`false`	`truefalse`	When `true`, detected logos are included in the redaction/de-identification pass. Defaults to `false`.

Code examples

# Get a document_key first: see POST /v1/documents/upload
curl -X POST "https://apis.hyperbots.com/v1/redact?mode=redact" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000"

# Get a document_key first: see POST /v1/documents/upload
curl -X POST "https://apis.hyperbots.com/v1/redact?mode=redact" \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "document_key=550e8400-e29b-41d4-a716-446655440000"

Response

200 OK

application/json

JSON

{
  "status": "success",
  "request_id": "req_01jb2...",
  "task": "redact",
  "model_used": "HyperLM",
  "result": {
    "images": [
      { "page_number": 1, "image_url": "https://files.hyperbots.com/redacted/...page-1.png?sig=..." }
    ],
    "updated_text_block": "Invoice\n\nBill To: [REDACTED]\nContact: [REDACTED]\n...",
    "summary": {
      "PERSON_NAME": 2,
      "EMAIL": 1,
      "ADDRESS": 1
    }
  },
  "duration_ms": 2640,
  "metadata": { "pages": 1, "mode": "redact" }
}

{
  "status": "success",
  "request_id": "req_01jb2...",
  "task": "redact",
  "model_used": "HyperLM",
  "result": {
    "images": [
      { "page_number": 1, "image_url": "https://files.hyperbots.com/redacted/...page-1.png?sig=..." }
    ],
    "updated_text_block": "Invoice\n\nBill To: [REDACTED]\nContact: [REDACTED]\n...",
    "summary": {
      "PERSON_NAME": 2,
      "EMAIL": 1,
      "ADDRESS": 1
    }
  },
  "duration_ms": 2640,
  "metadata": { "pages": 1, "mode": "redact" }
}