Skip to main content
The Nvisy API is a REST API over HTTPS. It accepts and returns JSON, except where file 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. Store it securely — it cannot be retrieved afterwards.

​
Workspaces

Nearly every resource lives inside a workspace, addressed by its slug:
Workspaces are the tenancy and access-control boundary. List yours with GET /workspaces/.

​
The Redaction Workflow

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

Upload a file

POST /workspaces/{workspaceSlug}/files/ — multipart upload, returns file metadata including the file ID.
2

Start a run

POST /workspaces/{workspaceSlug}/pipelines/{pipelineSlug}/runs/ with a fileId. The run analyzes the document against the pipeline’s policy.
3

Review detections

GET /workspaces/{workspaceSlug}/runs/{runId}/detections/ returns the audit of what was found.
4

Apply redactions

POST /workspaces/{workspaceSlug}/runs/{runId}/redactions/ produces the redacted output file.

​
Run Status

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

​
Pipelines and Policies

A policy defines what counts as sensitive. A pipeline defines how a document is processed and which policy applies. Both are workspace resources and are reused across runs. Browse the available detection labels and recognizers through GET /catalog/labels/ and GET /catalog/recognizers/.

​
Pagination

List endpoints are cursor-paginated: Responses contain items, nextCursor, and total. Continue while nextCursor is present.

​
Errors

Errors return a JSON body alongside the HTTP status code:
Only retry automatically when the request is idempotent or the endpoint documents an idempotency guarantee. A POST that uploads a file, creates a run, or applies redactions may have succeeded before the response failed, so a blind retry can duplicate work. Run creation accepts an Idempotency-Key header — reuse one stable key across every attempt of the same logical run.

​
Audit Export

Every run’s audit can be exported for long-term archiving:

​
Webhooks

Register endpoints under /workspaces/{workspaceSlug}/webhooks/ to receive events as runs progress. Use the test endpoint to verify delivery before relying on it.

​
SDKs

TypeScript

Full API coverage

Python

HTTP client

Rust

HTTP client