Nvisy
The client class. All services are exposed as lazily-constructed properties.NvisyOptions object.
NvisyOptions
apiToken and session are mutually exclusive in the type. DEFAULTS and
VERSION are exported for reference.
Instance members
withApiToken returns a new instance and leaves the original untouched; all
other configuration is preserved.
Services
Most methods take
workspaceId as their first argument. Workspaces are the
top-level tenancy boundary.NvisyGuest
The pre-auth client, for the endpoints that work without a token: sign-in, the deployment’s auth capabilities, and health checks.NvisyGuestOptions — the same transport options as NvisyOptions
minus the two authentication fields — and exposes three services:
loginAccount and signupAccount set HttpOnly session and CSRF cookies and
return no body. Construct new Nvisy({ session: true }) afterwards to use the
authenticated surface with that session.Workspaces
Workspace carries id, handle, displayName, memberRole, settings,
createdBy, and timestamps. CreateWorkspace requires displayName; handle,
description, and settings are optional.
Documents
uploadDocuments accepts a single Blob or an array, and sends them as
multipart/form-data. downloadDocument returns the raw Response so you can
stream the body.
object
ListWorkspaceDocuments filters by search (case-insensitive partial name),
formats, modality, and hash — the last lets you check whether identical
content already exists before uploading it.
deleteDocuments is idempotent: it returns deleted for the ids that were
removed and skipped for ids that were unknown, already deleted, in another
workspace, or held by an in-progress detection.
Pipelines
CreateWorkspacePipeline requires displayName; definition, description,
retention, and status are optional. A PipelineStatus is draft,
enabled, or disabled.
Policies
CreateWorkspacePolicy is a tagged union on source: seed from a built-in
template, or supply an inline definition. displayName and description
override the body’s own values. WorkspacePoliciesQuery filters by kind.
Detections
A detection is one analysis pass of a document. It produces findings for review; applying them is a separate, repeatable step that creates a redaction.createDetection starts analysis over a single document:
string
required
The document to analyze.
DocumentContext
Per-document languages, jurisdictions, and document labels. Overrides the
pipeline’s
defaultScope when present.createAdhocDetection names policies directly instead of going through a
pipeline; it requires documentId and a non-empty policyIds array, and also
accepts scope and retentionOverride.
Detection status
A
WorkspaceDetection carries id, inputDocumentId, inputDocumentName,
pipelineId (absent for an ad-hoc detection), status, triggerType,
triggeredBy, metadata, startedAt, completedAt, and error (present
only when status is failed).
Redaction does not change a detection’s status. Each
createRedaction call
produces a new WorkspaceRedactionResult, whose outputDocumentId points at
the redacted document.Streaming status
streamEvents parses the server-sent event stream into typed
DetectionStatusEvent values ({ detectionId, status }). It yields the current
status immediately, then each transition, and ends once the detection settles.
Break out of the loop to close the stream early.
events returns the raw Response if you would rather handle the
text/event-stream body yourself.
Audit and intermediates
getAnalysis returns the Audit — report, context, codec, usage, and
an optional recognition. downloadAudit returns it as a file: csv by
default (a zip of entities.csv, provenance.csv, and reviews.csv), or
json with { format: "json" }.
getIntermediates returns an ArtifactSet of modality-tagged parts — an
image’s OCR layout, an audio clip’s transcript, or tokenized text. A detection
whose analysis ran no enricher has none and responds 404.
Redactions
Reviews
A review is a human review thread opened on a document, with assignees, comments, and a lifecycle.WorkspaceReview carries id, documentId, displayName, author,
assignees, reviewStatus, and timestamps. reviewStatus is needs_review,
in_review, or resolved. CreateWorkspaceReview takes displayName;
CreateWorkspaceComment takes body.
WorkspaceReviewsQuery filters by documentId, author, assignee, and
reviewStatus. assignReviewer, linkDetection, and linkRedaction are
idempotent. getTimeline interleaves comments with lifecycle events;
getEvents returns the lifecycle events alone.
Providers
Inference providers configured per workspace.CreateWorkspaceProvider requires displayName and a config
(ProviderConfig), and accepts isActive. verifyProvider returns
{ reachable, error? }.
Connections
startFileServiceOAuth returns an authorizeUrl to send the user to; on
consent the callback completes the connection. importFiles takes the files
the user chose in the provider’s picker and exportFiles writes redacted
outputs back — both return a WorkspaceConnectionSync. getPickerToken mints a
short-lived provider access token for a browser file picker.
Syncs
startSync runs an object-store connection’s configured direction.
Webhooks
CreateWorkspaceWebhook requires displayName, description, url, and
events, and accepts headers and status.
Verifying deliveries
The@nvisy/sdk/webhooks entry point verifies an incoming delivery and parses
it into a typed event, using Web Crypto so it runs in Node, browsers, edge
runtimes, and workers.
Request, constructEvent takes the raw body and
headers directly; WEBHOOK_HEADERS names the four headers a delivery carries
(X-Webhook-Signature, X-Webhook-Timestamp, X-Webhook-Event,
X-Webhook-Request-Id). Verification failures throw WebhookSignatureError.
Members and Invites
memberRole is owner, admin, editor, or reviewer.
UpdateWorkspaceMember takes role; CreateWorkspaceInvite requires
inviteeEmail, invitedRole, and expiresIn.
Account
Account carries id, username, emailAddress, displayName,
avatarUrl, isActivated, isSuspended, and timestamps.
listIdentities reports the account’s sign-in methods — its password and any
linked OIDC providers. linkIdentity and reauth return the provider
authorize URL to redirect the user to.
Removing a password or unlinking a provider is refused when it is the
account’s only remaining sign-in method.
linkIdentity requires a step-up
reauthProof obtained from reauth.Authentication
Post-login operations live onclient.auth; sign-in itself is on
NvisyGuest.
mintDesktopToken mints a long-lived native-app token from an active browser
session. It takes { redirectUri } and returns { apiToken, redirectUri }.
API Tokens
CreateAccountApiToken requires displayName and expiresIn, one of never,
in7Days, in30Days, in90Days, or in1Year.
Capabilities
What this deployment supports. Replaces the former catalog endpoints.listLabels returns the built-in taxonomy as a LabelCatalog — a map of label
id to its definition. listRecognizers returns the engine’s registered
recognizers grouped into ner and llm. listConnectors returns
{ fileServices, objectStores, inference }
— an OAuth file-service provider is offered only when its app is configured.
getAuthCapabilities is also available pre-auth on NvisyGuest.
Analytics and Activities
WorkspaceAnalytics aggregates storage, detections, and usage.
WorkspaceActivityFilterQuery filters by actor and type.
Notifications
streamEvents yields the current unread count immediately, then each change.
Status
Health carries status, a checks array of per-dependency health, and a
timestamp. checkLiveness probes no dependencies and has no body, so it
returns the raw Response; a non-2xx status throws.
Date Windows
Methods taking aDateWindow accept an inclusive from/to day range as
YYYY-MM-DD strings. Both are optional: to defaults to today (UTC), and
from defaults to a fixed window back from to.
Pagination
List methods are cursor-paginated and acceptCursorPagination:
Every page has
items, an optional nextCursor, and an optional total.
Errors
NvisyError is the base class, thrown for SDK-level problems such as an
invalid API token. NvisyApiError extends it for API responses:
Helpers:
isClientError() (4xx), isServerError() (5xx), isRetryable()
(5xx, 408, or 429), and toJSON().