Plan an integration

All plans Authenticated calls through the HTTP API and the Python SDK work on Team and Enterprise. Hosted workspaces use api.nitsor.com. A Community deployment serves the same contract at its own site URL, and anonymous discovery works there. It has no supported way to issue an agent token: tokens are created in the hosted app on Team and Enterprise, and its stack does not include the Nitsor dashboard. Service accounts and tokens describes how an owner or admin creates, replaces and revokes one. Use the client coverage and acceptance-evidence tables to test the operations your integration needs.

Map your data flow

Document the current path from source object to training or evaluation dataset. Include storage location, format, geometry conventions, label representation, taxonomy, transformations, model output, review decisions, and release destination. The table below maps the pipeline you already run onto Nitsor records. The last column names the record that would hold that stage, so you can see at once where a stage has no equivalent.

Stage	What happens there	Who controls it in your current pipeline	Nitsor record
Storage location	Source objects are held somewhere durable and are read from that location.	The team that owns the storage system and its access rules.	Storage connection; account-owned credential handle.
Format	Bytes are written and read in a specific file or container format.	Whoever chose the acquisition or export format, often a vendor.	`sourceFormat` and `viewability` at registration.
Geometry conventions	Coordinates, voxel spacing, and orientation are fixed so a position means the same thing to every tool.	Usually the acquisition system; often nobody reviews it later.	Source geometry; `GEOMETRY_INCONSISTENT`, `GEOMETRY_OUT_OF_RANGE`.
Label representation	An interpretation is stored as a mask, contour, box, key point, or structured value.	The annotation tool in use, which may not be the storage owner.	Geometry kinds: landmark, box2d, box3d, mask, stroke, polygon; fields.
Taxonomy	Label names are given a controlled set and an agreed meaning.	The domain owner who defines what each label means.	The taxonomy definition, bound per branch, hashed into commits.
Transformations	Resampling, cropping, normalization, or format conversion changes the data before use.	The engineer who wrote the processing step, often undocumented.	Not modeled. Register the derived objects as their own Source.
Model output	A model produces a proposal, a score, or a derived measurement.	The ML owner, together with whoever chose the model version.	Prelabel Jobs, Runs, proposals with model provenance.
Review decisions	A person accepts, corrects, returns, or escalates a proposal.	The reviewer, under whatever instruction is written down.	Hash-bound review verdicts.
Release destination	An approved set of data and labels leaves for training, evaluation, or an external consumer.	The team that consumes the dataset and its approver, if named.	Dataset Version, pin, leased read.

A stage with no named controller is the most useful finding here. It marks the point where provenance is already lost in your current process, independent of any tool you adopt later.

Choose a client

Read Version model for the graph vocabulary, Data boundary for what crosses into the control plane, and Model-assisted prelabeling for what a model proposal is allowed to claim. Then pick the surface: the HTTP API or the Python SDK. The Python SDK shares the HTTP contract but exposes a subset of its operations; check the supported methods before choosing it.

Surface	Best for	Distribution
HTTP API	Any language; the OpenAPI document is the source of truth.	The hosted origin `https://api.nitsor.com`, or your Community site URL; the OpenAPI document is anonymous.
Python SDK	Training and evaluation code; the `nitsor.data` reader; PyTorch and MONAI extras.	Not on PyPI. Use the HTTP API.

The Python SDK is not on PyPI. Call the HTTP API.

What each client covers

The HTTP API serves every operation. The Python SDK covers the subset below; anything else is an HTTP call. The SDK column describes the client as built. It is not on PyPI, so the HTTP API column is the one you can call.

Operation area	HTTP API	Python SDK
Session and capabilities	Yes	Yes
Service accounts and tokens	Yes, with a personal token	Yes, with a personal token
Model label outcomes	Task, proposal	Task, proposal
Model runs	Estimate, create	Estimate, create
Projects	Create, list	Create, list
Project groups and shelf	Yes	No
Blind checks	Read a plan, list plans and checks. Starting, changing the rate of and stopping a plan are not callable by an integration today	No
Storage connections	Create, get; list credential handles; connect a bucket with your own key (an owner or admin’s personal authority only)	No
Sources	Register, list, mask read presign, viewer representation status and presign	Register, list
Project Assets	Attach	Attach
Taxonomy	Read, bind	No
Pipeline (workflow definition)	Read, bind	No
Version graph (branches, commits, landmarks, merge, position, project metadata)	Yes	Create a branch
Task comments	Yes	No
Datasets	Create, revise, get, list	Create, revise, get, list
Dataset Versions	List, create, get, exclusions, labels, stats, pin, access, delete	List, create, get, pin, delete, wait; the `nitsor.data` training reader
Requests	Get, list, items, cancel	Get, list, items, cancel, wait
Executions	List, detail, work items	No
Decisions and Ledger	List	No

The Python SDK exposes a delete call for Dataset Versions. Deletion needs project admin, and a token never holds more than operate, so the server refuses the call unless a project admin has allowed the token’s service account to delete Dataset Versions in that project. The admin does this on the project’s Access page for up to 90 days at a time, and the service account’s access level stays operate. A refusal names the missing admin scope and says what would allow the delete.

Limits

Area	Limit
Identity and permissions	Source registration uses an agent token. Customer key setup uses an owner or admin’s dashboard session or personal authority; a token cannot add or change keys or enable writing. A token expires 90 days after it is created unless another time is chosen, at most 365 days, carries its service account’s permissions or a narrower list, and reaches only the projects a project admin has given the service account access to, at `operate` at most. Managing service accounts through the API needs a personal token, which Nitsor does not issue today, so it is done in the dashboard. People sign into the dashboard.
Review	The public API has no route that records a review verdict; people record verdicts in the dashboard.
Dataset approval	Nitsor records no approval mark or signature on a Dataset Version.
Storage	Existing scans register where they live. Uploads use a writable customer or Nitsor-managed destination. New customer connections are read-only. Dataset Version downloads over self-serve customer connections need operator-assisted signer setup. See Data boundary.
Data-boundary evidence	The docs describe topology and bounds. They do not publish deployed network traces, encryption records or retention records.
Data format and spatial accuracy	The contract names recognized formats, geometry checks and raw slice encodings. These docs publish no round-trip tolerance or representative-volume result.
Failure, retry and conflicts	Most writes take idempotency keys with 24-hour retention. Dataset Version pin and read-session access routes take none; cancel and delete have no body. See Request conventions for retries and the issue-code vocabulary for the refusal classes.
Webhooks and MCP	The product sends no webhooks. The contract declares one event type but has no subscription route. Nitsor has no product MCP server or agent action surface.
Community operations	Community runs on one node. It has no Helm, Kubernetes, high-availability or multi-node configuration, and no backup or restore command. Back up the data volume and `.env` yourself.
Observability and support	The contract exposes no product logs, provider usage or aggregate metrics. Enterprise support terms are agreed with sales.
Export and reconstruction	Dataset Versions have per-chunk digests and a verified reader. Nitsor has no re-import path, and these docs publish no customer-facing reconstruction result.

Evidence required before integration

This is the canonical pre-integration acceptance gate for these docs. Integrations and public interfaces links here rather than keeping its own list. The third column says how to run each test against your deployment.

Evidence item	Why it matters	How to test it
A versioned released package or service	Record the version so you can repeat the test against the same contract.	`GET /api/v1/capabilities` names `productVersion`; record the installed SDK version.
Accepted formats and geometry preservation	Volumetric data is unusable if coordinates, spacing, or orientation change silently.	Register a representative series and compare the answered geometry with your own reading of the headers.
Source registration and read permissions	Integration depends on what the system may read and how that access is scoped.	Create a token with `storage:write` only and observe which routes refuse with `AUTHORIZATION_DENIED`; `POST /api/v1/sources` is one, because registering a Source needs `sources:register`, and `GET /api/v1/sources` is another, because listing Sources needs `sources:browse`.
Identity and authorization boundaries	Who can call what determines your security review, not the endpoint list.	Send a valid `POST /api/v1/projects` from a credential without `projects:write` and read its `decisionId` back from `GET /api/v1/decisions`; a denied read, and a denied pin, carry none.
Repeat and retry behavior, rate and error limits	Real clients retry; a duplicate that creates two records corrupts the history.	Send the same write twice with one `idempotencyKey` and compare; send it with a changed body and expect `IDEMPOTENCY_CONFLICT`.
Event ordering and conflict behavior	Concurrent writers are the normal case for annotation work.	Commit overlapping edits on two branches and merge; read the typed conflicts.
Schema and compatibility policy	Breaking changes without a policy turn every upgrade into an incident.	Read the per-method minimums in `capabilities.minimumVersions` and the skew policy in the Public HTTP API.
Examples tested against the release	An example proven against a mock proves the mock.	Run the Quickstart journey against your own workspace with the released SDK and compare each answer with the reference pages.
Export completeness and migration	Data you cannot take out is data you have lost control of.	Create a Dataset Version, read it with the Python reader, and rebuild your training input from the manifest alone.
Performance limits and failure recovery	Volumetric workloads find limits quickly; recovery behavior decides the blast radius.	Read `capabilities.limits`; Nitsor does not publish recovery times; Enterprise recovery terms are agreed with sales.
Logs, metrics, and support boundaries	Operating a dependency requires seeing into it and knowing who owns which failure.	The contract exposes no logs or usage metrics. Agree on support terms with sales for Enterprise.
Deployment and upgrade procedure	An integration you cannot upgrade safely will pin you to a vulnerable version.	The client policy is published (two stable minors and six months); the server upgrade policy is not.

Documentation, type definitions, and mock examples are useful evidence, but they do not replace a test against a released package or service. The SDK is not on PyPI, so run each test above against the HTTP API; the SDK steps in it show the calls the SDK makes.

Examples in these docs

The Public HTTP API and Data model and contracts pages carry request shapes taken from the contract, and the Python snippets in these guides use the same shapes. They are runnable against a workspace with an agent token; they are not runnable from this site. See Self-host for Community installation.

Next step

Read Integrations and public interfaces for the current list of surfaces and their boundaries, then turn your proposed dependency into a short acceptance test and run it against your workspace.

Plans	All plans
Last verified	2026-09-30

Get started

Concepts

Guides

Reference

Map your data flow

Choose a client

What each client covers

Limits

Evidence required before integration

Examples in these docs

Next step

​Map your data flow

​Choose a client

​What each client covers

​Limits

​Evidence required before integration

​Examples in these docs

​Next step

Map your data flow

Choose a client

What each client covers

Limits

Evidence required before integration

Examples in these docs

Next step