Permanently redact personal information
Destructively removes personal information from a document or an audio file and returns a new file.
The removal is real, not cosmetic: text is stripped out of the PDF content stream rather than covered with a black box, and audio is beeped or silenced with its transcript rewritten to match.
Routing is by the input’s media type, and the parameters are not interchangeable:
- Documents —
mode:targeted(default, per-entity boxes) orlines(whole lines). - Audio and video —
style:beeporsilence.
Sending the other medium’s parameter is a 400.
Choosing what to remove. categories lists what counts as sensitive. A list you send replaces the defaults; it never adds to them, so narrowing the list leaves everything else in the file. instructions adds free-form guidance on top.
Reading the result. output.entities counts what was removed, per category. Its keys are open, not a closed set: a finding your categories do not cover reports under its own label, such as Passport number or MRN. Iterate the map; never switch on a fixed set of keys. output.skipped counts the inputs that held nothing to redact. A skipped input produces no new file, so there is nothing to download for it.
One file per call. file is singular, and { "files": […] } is a 400. To redact a set in one call, send a pipeline with a single { "redact": … } step.
Waiting for the result
Sync by default: the call holds open until the run finishes, up to ?wait= seconds (default 60, max 120, 0 returns immediately).
Learn more: Redaction guide
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Query parameters
How many seconds to hold the request open waiting for the run to finish.
Finishing inside the window returns 200 with the full run; running past it returns 202 with a statusUrl to poll. Send 0 to skip waiting entirely and always get the 202.
Request
An input file, given one of two ways.
{ "url": "…", "name"?: "…", "processing"?: "…" }— fetched over http(s) for this run and purged with it.{ "id": "…" }— a file you already registered withPOST /v1/files, reusable across runs and never re-parsed.{ "id": "…", "ephemeral": true }— a file you uploaded only for this run, purged with it. Use it only on a file no other run uses.
What counts as sensitive, as free text, not an enum. Each hit reports back under the label you asked for, copied exactly.
This list replaces the defaults; it does not extend them. Sending a shorter list leaves everything outside it in the file. To keep the defaults and add to them, repeat the defaults next to your own entries.
Arbitrary JSON you attach to the run and get back on every read of it.
Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.
Where to deliver this run’s events, given one of two ways.
{ "url": "…" }— a one-off https endpoint for this run only.{ "id": "whe_…" }— a saved endpoint fromPOST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.
Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.
How long, in seconds, to keep this run and its files before purging them automatically.
The maximum is 604800 (7 days). The deadline comes back as expiresAt on every read of the run. Call POST /v1/runs/{id}/keep before then to clear the TTL and move the results into a space permanently.
E-signature runs are exempt — an envelope waits for its signers however long that takes.
Response
Where the run is in its life.
The last four are terminal.
Why the run failed. Present whenever status is failed, and only then.
code is the stable, snake_case reason (input_unavailable, parse_failed, …); message is the human-readable detail. Per-file and per-step failures are also reported in files[].error and, for a pipeline, steps[].error.
The redacted files. Present once status is processed.
files[] holds the new documents — file is an alias of the first for single-file runs — each with a signed download link. A /v1/redact call takes one input, so it returns at most one file; a redact pipeline step over many files returns one per input that had a match.
entities tallies what was removed per category. Its keys are open, not a closed set: a finding the categories list does not cover reports under its own label. skipped counts documents that contained nothing to redact and so produced no new file.