Redact

Permanently remove personal information from a document or a recording.
View as Markdown

POST /v1/redact takes a file. It returns a new file without the personal information. In a PDF, CloudRaker strips the text out of the content stream. It does not cover the text with a rectangle. Copy-paste and text search find nothing, because the text is gone. In audio, CloudRaker beeps or silences the words and rewrites the transcript.

How it works

  1. You send a file (a URL or a file id you already have) and, optionally, the categories that count as sensitive.
  2. CloudRaker parses the document, locates every match, and rewrites the file destructively.
  3. Routing follows the input’s MIME type. Audio and video go to audio redaction (style). All other files go to document redaction (mode). If you send the parameter for the other medium, the API returns a 400.
  4. The call holds until the run finishes, up to ?wait= seconds (default 60, max 120). At the cap, the call returns 202 with a run id instead of an error.
  5. The run, its input, and the redacted output expire after the ttl (default 24 hours). To retain them, keep them.

Redaction is destructive by design. The output is a new file. The original stays untouched. To remove the original, call DELETE /v1/files/:id, or let the run’s ttl purge both files.

Quickstart

The sample uses a blank IRS Form W-9, so the call works with no local files.

$curl -X POST https://api.cloudraker.com/v1/redact \
>  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "name": "w9.pdf" },
>    "categories": ["ssn", "ein"],
>    "mode": "targeted"
>  }'

The TypeScript and Python samples use plain HTTP, so they run with no installed packages. This endpoint is also a top-level method on both SDKs as of 0.3.0: client.redact(…). That page has a full worked example.

Example response

1{
2  "object": "redact_run",
3  "id": "rdr_01KYD72106R2BXBJRF537T1JSH",
4  "status": "processed",
5  "expiresAt": "2026-07-26T18:02:06.093Z",
6  "statusUrl": "/v1/runs/rdr_01KYD72106R2BXBJRF537T1JSH",
7  "files": [
8    { "id": "a04d6597-4e34-4a99-94ea-964c289a4c68", "name": "w9.pdf", "status": "processed" }
9  ],
10  "file": { "id": "a04d6597-4e34-4a99-94ea-964c289a4c68", "name": "w9.pdf", "status": "processed" },
11  "output": {
12    "file": {
13      "id": "c8c8437a-0dfd-4924-9358-c638fb0002e4",
14      "name": "w9 (redacted).pdf",
15      "url": "https://cdn.cloudraker.com/…/latest?token=…"
16    },
17    "files": [
18      { "id": "c8c8437a-0dfd-4924-9358-c638fb0002e4", "name": "w9 (redacted).pdf", "url": "https://cdn.cloudraker.com/…/latest?token=…" }
19    ],
20    "entities": { "ein": 5, "ssn": 10 },
21    "skipped": 0
22  }
23}

Key fields

FieldWhat it is
objectAlways redact_run.
idThe run id (rdr_…).
statusqueued, processing, processed, failed, cancelled, or expired.
files[]The inputs, with per-file status and error. file is an alias for files[0].
output.files[]One redacted file per input: {id, name, url}. output.file is an alias for the first.
output.file.urlSigned, time-limited download URL. GET /v1/runs/:id/output/:name is the stable alias for the same bytes.
output.entitiesThe count of redacted items per category, for example {"ssn": 10, "ein": 5}.
output.skippedThe count of detections that CloudRaker could not remove. If the count is not zero, review the output.

CloudRaker registers the output file’s bytes a moment after the run reports processed. In that window, output.file can arrive without its url, and the /output/ alias can answer 404. Re-fetch GET /v1/runs/:id to get the URL.

Configuration

Every field is optional except file.

FieldTypeWhat it does
file{url, name?, processing?} or {id}Required. The document or recording to redact.
categoriesarray of strings, 1–50What counts as sensitive. Defaults cover names, government ids, addresses, phone, email, and date of birth.
instructionsstring, ≤ 4000 charsFree-text additions (“also redact internal project codenames”).
modetargeted | linesDocuments only. targeted removes the matched span; lines removes the whole line containing it.
stylebeep | silenceAudio only. How the removed speech sounds in the output.
actionstringThe id or slug of a saved config. The API merges inline fields over the saved config.
metadataobjectYour own key/values. The API echoes them back on the run body, not on webhook deliveries. Max 10 KB.
webhook{url} or {id}Where to deliver terminal events. See Webhooks.
ttlinteger seconds, 1–604800How long the run and its files live. Default 24 hours, max 7 days.

If you send style on a PDF, or mode on audio, the API returns 400 invalid_request. The error names the parameter that does not apply.

Sync vs async

The behavior matches extract. Calls are synchronous by default. ?wait= accepts 0 to 120 seconds. At the cap, the API returns a 202 handle instead of a timeout error.

1{
2  "object": "redact_run",
3  "id": "rdr_01KYD72106R2BXBJRF537T1JSH",
4  "status": "processing",
5  "statusUrl": "/v1/runs/rdr_01KYD72106R2BXBJRF537T1JSH"
6}

Long recordings and large scans normally land here. Pass ?wait=0 and poll, or use a webhook.

Save it as a config

Redaction policy is usually organization-wide, not per call. Save the categories, instructions, and mode once in the redact config library. Then every call shrinks to {"file": …, "action": "hr-offboarding"}:

$curl -X POST https://api.cloudraker.com/v1/redact/configs \
>  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "HR offboarding",
>    "mimeType": "application/pdf",
>    "config": { "categories": ["ssn", "email", "phone"], "mode": "lines" }
>  }'

mimeType picks the variant (document or audio) at save time. Only this library accepts it. GET, PATCH and DELETE /v1/redact/configs/{idOrSlug} do the rest. The flat /v1/actions routes remain as a deprecated alias. See Saved configs.

Next steps

Saved configs

Save a redaction policy once and reference it by slug.

Pipelines

Extract and redact the same file set in one call.

Runs

Statuses, downloading outputs, TTL, and keeping a result.

Errors

The error envelope and which failures are worth retrying.