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.
`Cache-Control`	`string`	optional	—	Send `no-cache` (or `no-store`) as an alternative to `force_refresh=true`; both have the same effect. Other directives, including `max-age=0` and `public`, do not bypass the cache.

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`.
`force_refresh`	`boolean`	`false`	—	When `true`, reprocess the document instead of returning the cached result. Results are cached per (document + parameters) for 24 hours, so re-submitting an unchanged request normally returns the stored output — this is how to force a genuinely fresh run after a bad result. A forced run is billed at the normal page rate, where a cached one is not charged. Defaults to `false`.

Code examples

# Get a document_key first: see POST /v1/documents/upload
# output=urls returns masked pages as short-lived presigned links (up to 60
# pages); omit it for inline base64 images (up to 36 pages).
curl -X POST "https://apis.hyperbots.com/v1/redact?mode=redact&output=urls" \
  -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
# output=urls returns masked pages as short-lived presigned links (up to 60
# pages); omit it for inline base64 images (up to 36 pages).
curl -X POST "https://apis.hyperbots.com/v1/redact?mode=redact&output=urls" \
  -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": {
    "output": "urls",
    "pages": [
      { "page_number": 1, "image_url": "https://files.hyperbots.com/...redacted/0.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": {
    "output": "urls",
    "pages": [
      { "page_number": 1, "image_url": "https://files.hyperbots.com/...redacted/0.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" }
}

Page images and figure crops are returned as short-lived signed storage links; the response's assets_expire_at gives the exact deadline. The text is yours to keep; the links are not. Store the request_id and read the result back with fresh links whenever you need it — Retrieving Results.