waafir-redact reference

The waafir-redact server exposes Waafir's redaction to a connected AI client, in two shapes:

• redact_text — a block of text, redacted inline and returned immediately.
• redact_file / redact_file_status — a whole document in a data room, analysed for PII and prepared for human review.

Applying a redaction to a document is deliberately not available over MCP. Applying changes what every other party sees when they open the file, so a person must approve it in the AI Redaction review screen. No tool on this server changes what any reader sees.

Connection: https://app.waafir.io/api/mcp/waafir-redact — see Setup. redact_text needs only a read-scope (or higher) PAT — it touches no data room, so there is no per-file or per-room check to clear.

Both document tools are deal-team only. redact_file needs write scope and deal-team membership of the data room — and so does redact_file_status, even though it only reads: a read-scope PAT is necessary but not sufficient, because the existence of a redaction job is itself a fact about the document. A caller outside the deal team gets FORBIDDEN, whatever scope the token carries. Token scope is the token's ceiling; deal-team membership is the person's — both must clear.

redact_text

Redact PII from a block of text. The text is processed by your organization's redaction agent, and the tool returns the redacted text together with the list of entities it identified. Optionally narrow the result to specific entity types.

Inputs

Output

{ redacted_text, entities, truncated, processed_chars, total_chars, max_chars,
  filtered_out_count, unclassified_redacted_count, unclassified_types,
  filter_exact }

• redacted_text — the analysed text with sensitive spans blacked out.
• entities — the PII that was removed. type is the label the redaction model used; canonical_type is the standard type it maps to, or null if it could not be classified.
• truncated / processed_chars / total_chars / max_chars — see Size limit.
• filtered_out_count / unclassified_redacted_count / unclassified_types / filter_exact — see Filtering by type.

The redaction runs against your organization's own redaction configuration, so results reflect the same agent the product uses. As with everything on this surface, the call acts as the token's owner and is scoped to that organization.

Size limit

Only the first 80,000 characters are analysed. This has always been the case; the result now tells you. When truncated is true, the text beyond processed_chars was never examined — do not treat the response as a redaction of the whole input. Send the remainder in a follow-up call.

Filtering by type

types accepts only these values:

name, email, phone, ssn, account, address, financial, confidential, url, username

⚠️ Breaking change (August 2026). types previously accepted any string. It now accepts only the values above, and anything else — "emails", "PII", "credit-card", or a different capitalisation like "EMAIL" — returns a validation error.

This replaces a silent failure with a loud one. An unrecognised value used to match nothing, so the tool redacted nothing and returned your original text as redacted_text inside a successful response. If you pass types, map your values onto the list above. Calls that omit types are unaffected.

One entity type is redacted even when you did not ask for it. If the redaction model labels something with a type we cannot recognise, that entity is redacted anyway rather than dropped — we cannot prove it falls outside what you asked for, and leaving PII in the text is the worse mistake. When this happens:

• filter_exact is false (it is true whenever the filter applied exactly),
• unclassified_redacted_count says how many entities that affected, and
• unclassified_types lists the labels involved.

Entities you deliberately filtered out are counted separately, in filtered_out_count.

redact_file

Analyse a whole document in a data room for PII. This analyses only — the document is not changed, and nobody's view of it changes. Analysis is asynchronous; poll redact_file_status.

Inputs

Output

{ file_id, job_id, status: "analysis_started", applied: false,
  review_required: true, review_with, apply_via }

There is no auto_apply option, by design — see the note at the top of this page. Image files are not supported.

Requirements: a write-scope PAT, deal-team membership of the data room, and your organization's AI features enabled.

redact_file_status

Check a document redaction analysis.

Inputs

Output

{ file_id, status, entity_count?, applied: false, apply_via }

• status — one of idle, analyzing, applying, review_ready, completed, failed, error. applying and completed describe a redaction being applied in the Waafir UI by a person — you cannot reach them from MCP, but you will see them if someone approves the review while you are polling.
• entity_count — how many PII entities the analysis proposed, once the review is ready.
• applied is always false: approving and applying the redaction happens in the Waafir UI.

Treat an unrecognised status as "keep polling", not as an error. The terminal states are held only briefly before the job marker is cleaned up, so a poller that arrives late sees idle (or a reconstructed review_ready) rather than the state it was waiting for — and idle means "no job in flight", not "nothing ever happened". Poll for the state you want, with a deadline, rather than asserting the value is one of a fixed list.