Skip to main content
The Nvisy API is a REST API over HTTPS. It accepts and returns JSON, except where document content is uploaded or downloaded.
The endpoint reference in this section is generated directly from the server’s OpenAPI specification, so it always reflects the deployed API.

​
Base URL

Self-hosted deployments serve the same API from their own host. A local development server defaults to http://127.0.0.1:8080.

​
Authentication

All requests authenticate with a bearer token:
Create tokens under API Tokens in your account settings, or through the /api-tokens endpoints.
A token’s secret is returned only once, at creation, in the POST /api-tokens response. Store it securely — it cannot be retrieved afterwards.
Browser clients may authenticate with the cookie session established by POST /auth/login or POST /auth/signup instead. A desktop app exchanges an existing session for a token with POST /auth/desktop/token. Where a deployment offers OIDC providers, sign-in starts at GET /auth/{provider}/start — ask GET /capabilities/auth which methods this deployment actually offers.

​
Workspaces

Nearly every resource lives inside a workspace, addressed by its id:
Workspaces are the tenancy and access-control boundary. List yours with GET /workspaces. Each workspace also carries a handle — a URL-safe display-only name. Address resources by id, not by handle.

​
The Redaction Workflow

Redaction happens in two phases, so findings can be reviewed before anything is modified.
1

Upload a document

POST /workspaces/{workspaceId}/documents — multipart upload, returns the document metadata including the document ID.
2

Start a detection

POST /workspaces/{workspaceId}/pipelines/{pipelineId}/detections with a documentId. The detection analyzes the document against the pipeline’s configuration and returns 202 with a pending detection.To analyze against an explicit list of policies with no saved pipeline, POST /workspaces/{workspaceId}/detections with a documentId and policyIds.
3

Review the analysis

GET /workspaces/{workspaceId}/detections/{detectionId}/analysis returns the audit of what was found.
4

Apply redactions

POST /workspaces/{workspaceId}/detections/{detectionId}/redactions produces a redaction, which owns the redacted output document. Pass edits to layer reviewer changes over the analysis first, or omit it to redact exactly as detected.
Redaction is repeatable: each request produces a new redaction over the same detection, and does not change the detection’s status.

​
Detection Status

Subscribe to GET /workspaces/{workspaceId}/detections/{detectionId}/events for a server-sent events stream. It emits the current status immediately, then each transition, and ends once the detection settles (complete or failed). Each event is named status and its data is a DetectionStatusEvent.
Authenticate the stream with a bearer token using a fetch-based client — the native EventSource cannot send an Authorization header.The detection row is the source of truth, so a missed broadcast is recoverable: re-read GET /workspaces/{workspaceId}/detections/{detectionId} if a connection drops.

​
Pipelines and Policies

A policy defines what counts as sensitive. A pipeline defines how a document is processed and which policies apply. Both are workspace resources and are reused across detections. Browse what the deployment supports through GET /capabilities/labels, GET /capabilities/recognizers, and GET /capabilities/connectors.

​
Pagination

List endpoints are cursor-paginated: Responses contain items, and nextCursor when more items exist. Continue while nextCursor is present. total is returned only when you ask for it with includeCount=true, since counting costs an extra query.

​
Errors

Errors return a JSON body alongside the HTTP status code:
name is the error type identifier; message is a human-readable message safe to display.
Only retry automatically when the request is idempotent or the endpoint documents an idempotency guarantee. A POST that uploads a document, starts a detection, or applies redactions may have succeeded before the response failed, so a blind retry can duplicate work. Starting a detection accepts an Idempotency-Key header — reuse one stable key across every attempt of the same logical detection, and a repeat returns the existing detection.

​
Audit Export

Every detection’s audit can be downloaded for long-term archiving:
csv is the default and returns a zip of entities.csv, provenance.csv, and reviews.csv. json returns a pretty-printed JSON file. A redaction’s own review audit — the analysis with reviewer edits applied and the per-entity outcome recorded — is at GET /workspaces/{workspaceId}/redactions/{redactionId}/review.

​
Health

GET /health/live is a liveness probe that touches no dependencies. GET /health/ready reports the server and its dependencies from a short-lived cache and is safe to poll. Both return 200 when healthy or degraded and 503 when unhealthy.

​
Webhooks

Register endpoints under /workspaces/{workspaceId}/webhooks to receive events as detections and syncs progress. Use POST /workspaces/{workspaceId}/webhooks/{webhookId}/test to verify delivery before relying on it.

​
SDKs

TypeScript

Full API coverage

Python

HTTP client

Rust

HTTP client