Redaction Workflow

Redaction in Nvisy is deliberately two-phase. A detection first analyzes a document and records what it found; nothing is modified until you create a redaction. That separation is what makes the process reviewable and auditable.

The Phases

Upload

Add a document to a workspace. It is stored with its metadata and hashed.

Detect

Start a detection against a pipeline. Recognition produces entities, each with a label, confidence, and location.

Review

Inspect the detection’s analysis. Accept the policy’s decisions, or layer reviewer edits over them.

Redact

Create a redaction. The engine writes a new output document and records a review audit of what was redacted and why.

Detection Status

A detection’s status tells you which phase it is in:

Status	Meaning
`pending`	Enqueued for detection; no worker has picked it up yet
`executing`	A worker is actively analyzing the document
`complete`	Analysis done; the detection is ready to redact
`failed`	Detection failed — see the detection’s `error` field

A detection settles at complete and stays there. Redaction is a separate, repeatable action over a complete detection and does not change this status, so an unreviewed document is never silently modified.

Poll the detection, or subscribe to its event stream for live progress:

GET /workspaces/{workspaceId}/detections/{detectionId}
GET /workspaces/{workspaceId}/detections/{detectionId}/events

for await (const event of client.detections.streamEvents(
  workspaceId,
  detectionId,
)) {
  console.log(event.status);
  if (event.status === "complete") break;
}

The stream yields the current status immediately, then each transition, and ends once the detection settles.

Pipelines, Policies, and Ad-hoc Detections

A pipeline carries the detection and governance intent: its definition holds an optional defaultScope and the policyIds to apply. A policy defines how recognized entities are treated. Both are workspace resources, created once and reused.

POST /workspaces/{workspaceId}/pipelines/{pipelineId}/detections

const detection = await client.detections.createDetection(
  workspaceId,
  pipelineId,
  { documentId },
);

You can also skip the pipeline and name the policies directly:

POST /workspaces/{workspaceId}/detections

const detection = await client.detections.createAdhocDetection(workspaceId, {
  documentId,
  policyIds: [policyId],
});

Recognition itself is server-wide — the built-in pattern set plus whatever recognizers the engine has registered. Ask the deployment what it offers:

GET /capabilities/labels
GET /capabilities/recognizers

The Analysis

GET /workspaces/{workspaceId}/detections/{detectionId}/analysis returns the detection’s audit — what analysis found in one document:

Field	Description
`report`	The detections themselves: `parts`, each tagged by modality, each holding entities
`context`	What the caller asserted: languages, jurisdictions, document metadata
`codec`	How the document was decoded, so redaction decodes identically
`recognition`	Custom labels this request introduced, and how they are matched

The report’s parts is a list, not a map. Each part carries a modality (text, image, audio, tabular), its entities, and an id — a path of one or more segments naming where it sits in the document. Container formats expose their internal parts this way, so an image embedded in a DOCX is analyzed in its own right.

Reviewer edits are not in the audit. They are your own input, applied to the report before redaction, so an audit carries what analysis found as amended rather than the amendments themselves.

Entities

Each entity holds records with a consistent shape:

Field	Description
`id`	Stable identity for this entity
`label`	What was recognized, resolved through the label catalog
`confidence`	Effective confidence, `0.0` to `1.0`
`location`	Where it sits, in modality-native coordinates
`language`	Detected language, where applicable
`coref`	Coreference link to other mentions of the same subject
`audit`	Tamper-evident provenance trail for this entity

Intermediates

When the analysis ran an enricher, its extracted content is available separately — an image’s OCR layout, an audio clip’s transcript, or tokenized text:

GET /workspaces/{workspaceId}/detections/{detectionId}/intermediates

Intermediates let a client search the extracted content and add entities the analysis missed. A detection whose analysis ran no enricher has none and returns 404.

Redaction Operators

What actually happens to an entity depends on its modality. A single policy rule can name an operator per modality:

Text
Image
Audio
Tabular

erase, keep, mask, replace, hash, hmac_hash, fake, pseudonymize, encrypt, truncate, clamp, generalize_date

erase, keep, blur, pixelate, blackbox

erase, keep, silence, beep

cell, drop_row, drop_column

keep is an operator like any other — it records that an entity was recognized and deliberately left intact, which is often exactly what an auditor needs to see.

Modalities a rule does not cover fall through to the policy’s fallback, and entities with no operator from either source are skipped.

Applying Redaction

POST /workspaces/{workspaceId}/detections/{detectionId}/redactions

Omit edits to redact with the policy decisions exactly as detected, or pass them to suppress a false positive, retag a detection, or add one the analysis missed. Edits are grouped by modality:

const redaction = await client.detections.createRedaction(
  workspaceId,
  detectionId,
  { edits: { text: [/* reviewer edits */] } },
);

Each request produces a new redaction, so the same detection can be redacted several times with different edits — one document, several outputs. A redaction carries its outputDocumentId (downloadable through the normal document endpoints) and a review audit recording what was redacted and why:

GET /workspaces/{workspaceId}/detections/{detectionId}/redactions
GET /workspaces/{workspaceId}/redactions/{redactionId}/review

Scope

A detection’s scope carries what the caller asserts about the document — languages, jurisdictions, and free-form metadata. Pipelines supply a defaultScope; a detection can override it:

{
  "documentId": "...",
  "scope": {
    "languages": ["en"],
    "countries": ["US"],
    "metadata": { "purpose": "fraud_detection", "audience": ["auditor"] }
  }
}

Everything in a scope defaults to empty. Assert nothing and the recognizers use their own defaults — the language-detection enricher fills the gap when languages is empty.

How pages are rendered for OCR is a codec concern rather than a scope one; see Supported Formats.

Reviews

A review is a named discussion on a document with a manual sign-off lifecycle. It is opened explicitly, and a document may have several:

POST /workspaces/{workspaceId}/documents/{documentId}/reviews
GET  /workspaces/{workspaceId}/reviews
POST /workspaces/{workspaceId}/reviews/{reviewId}/verify
POST /workspaces/{workspaceId}/reviews/{reviewId}/reopen

Its reviewStatus is derived from its events, never set directly: a linked detection makes it needs_review, a linked redaction in_review, and verification resolved.

const review = await client.reviews.createForDocument(workspaceId, documentId, {
  displayName: "Q3 contract sign-off",
});

await client.reviews.linkDetection(workspaceId, review.id, detectionId);
await client.reviews.assignReviewer(workspaceId, review.id, accountId);
await client.reviews.verifyReview(workspaceId, review.id);

Comments and lifecycle events interleave into one timeline, at /workspaces/{workspaceId}/reviews/{reviewId}/timeline.

Exporting the Audit

Once a detection completes, export its audit for archiving:

GET /workspaces/{workspaceId}/detections/{detectionId}/audit

format defaults to csv — a zip of entities.csv, provenance.csv, and reviews.csv — or pass json for a pretty-printed JSON file.

Next Steps

Quickstart

Run the workflow end to end

Audit Trails

What the audit records

API Reference

Every endpoint

TypeScript SDK

Full API coverage

Overview

Features

Cloud

On-Premise

Redaction Workflow

The Phases

Detection Status

Pipelines, Policies, and Ad-hoc Detections

The Analysis

Entities

Intermediates

Redaction Operators

Applying Redaction

Scope

Reviews

Exporting the Audit

Next Steps

Quickstart

Audit Trails

API Reference

TypeScript SDK

​The Phases

​Detection Status

​Pipelines, Policies, and Ad-hoc Detections

​The Analysis

​Entities

​Intermediates

​Redaction Operators

​Applying Redaction

​Scope

​Reviews

​Exporting the Audit

​Next Steps

Quickstart

Audit Trails

API Reference

TypeScript SDK

The Phases

Detection Status

Pipelines, Policies, and Ad-hoc Detections

The Analysis

Entities

Intermediates

Redaction Operators

Applying Redaction

Scope

Reviews

Exporting the Audit

Next Steps