Quick Start

Installation

Install the Nvisy SDK from npm:

npm install @nvisy/sdk

yarn add @nvisy/sdk

pnpm add @nvisy/sdk

NPM Package

View the package on npm

Requirements

Node.js 24 or later (or any ES2022+ runtime with fetch and a global File)
An API token — create one under API Tokens in your account settings

Uploads construct a File, which Node.js exposes globally. On a runtime without it, import it explicitly with import { File } from "node:buffer".

Your First Request

Construct a client with your API token and read your account:

import { Nvisy } from "@nvisy/sdk";

const client = new Nvisy({ apiToken: process.env.NVISY_API_TOKEN! });

const account = await client.account.getAccount();
const workspaces = await client.workspaces.listWorkspaces();

console.log(account.username, workspaces.items.length);

Everything except authentication and account management is scoped to a workspace, identified by its id. List your workspaces first to find it.

Configuration

The constructor accepts additional options:

const client = new Nvisy({
  apiToken: "your-api-token",       // Required (unless `session: true`)
  baseUrl: "https://api.nvisy.com", // Optional
  userAgent: "MyApp/1.0.0",         // Optional
  withLogging: true,                // Optional — debug logging
  headers: {                        // Optional
    "X-Custom-Header": "value",
  },
  fetch: customFetch,               // Optional — defaults to the global fetch
});

Option	Type	Required	Default
`apiToken`	`string`	One of `apiToken` / `session`	—
`session`	`true`	One of `apiToken` / `session`	—
`baseUrl`	`string`	No	`https://api.nvisy.com`
`userAgent`	`string`	No	`@nvisy/sdk v.<version>`
`withLogging`	`boolean`	No	`false`
`headers`	`Record<string, string>`	No	—
`credentials`	`RequestCredentials`	No	—
`fetch`	`typeof fetch`	No	global `fetch`

apiToken and session are mutually exclusive in the type. Use apiToken for server-side and CI use; use session: true in a browser app after the guest client has logged in, which sends the session cookies instead.

Signing In From a Browser

Login, signup, OIDC sign-in start, the deployment’s auth capabilities, and the health probes work without a token, so they live on a separate pre-auth client:

import { NvisyGuest } from "@nvisy/sdk/guest";
import { Nvisy } from "@nvisy/sdk";

const guest = new NvisyGuest({ baseUrl: "https://api.nvisy.com" });

// Which sign-in methods does this deployment offer?
const methods = await guest.capabilities.getAuthCapabilities();

// Password login sets the session cookies and returns no body.
await guest.auth.loginAccount({
  identifier: "[email protected]",
  password: process.env.PASSWORD!,
});

// From here, use the authenticated client backed by that cookie session.
const client = new Nvisy({ session: true });

The Redaction Workflow

Redaction is a two-phase process: a detection first analyzes a document, then you create a redaction from it after reviewing the findings.

Upload a document

const [document] = await client.documents.uploadDocuments(workspaceId, blob);

Start a detection against a pipeline

Creation returns immediately; analysis continues in the background.

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

Wait for analysis to finish

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

let status = detection.status;

for await (const event of client.detections.streamEvents(
  workspaceId,
  detection.id,
)) {
  status = event.status;
}

if (status !== "complete") {
  throw new Error(`Detection ${detection.id} ended as ${status}`);
}

Review the analysis

const audit = await client.detections.getAnalysis(workspaceId, detection.id);

Create a redaction

const redaction = await client.detections.createRedaction(
  workspaceId,
  detection.id,
  {},
);

A pipeline defines how a document is analyzed, and a policy defines what is considered sensitive. Create them once, then reuse across detections. To analyze a document against policies directly, without a saved pipeline, use detections.createAdhocDetection(workspaceId, { documentId, policyIds }).

A detection moves through pending → executing → complete or failed. Redaction is a separate, repeatable action over a complete detection and does not change that status — each createRedaction call produces a new redaction.

The detection row in Postgres is the source of truth, so a missed broadcast is recoverable — re-read the detection with getDetection if a connection drops. Note that the native EventSource cannot send an Authorization header, which is why the SDK streams over fetch.

TypeScript

Python

Rust

Installation

NPM Package

Requirements

Your First Request

Configuration

Signing In From a Browser

The Redaction Workflow

Next Steps

API Reference

Examples

​Installation

NPM Package

​Requirements

​Your First Request

​Configuration

​Signing In From a Browser

​The Redaction Workflow

​Next Steps

API Reference

Examples

Installation

Requirements

Your First Request

Configuration

Signing In From a Browser

The Redaction Workflow

Next Steps