Skip to main content
All plans The six steps on this page run on Team and Enterprise, and the HTTP API is the route today. The Python SDK calls named here show the calls the SDK makes; the package is not on PyPI. A Community deployment cannot build or read a Dataset Version today: its run plane is off, so a build is refused, and its stack does not run the data-plane Workers that serve reads. Nitsor records no approval mark or signature on a Dataset Version. Nitsor has no Release object. A Dataset is a named selection over one branch of a project. A Dataset Version is that selection at one commit, frozen into a manifest with a SHA-256 digest per 16 MiB chunk. The version is the thing you cite and train on.

Lifecycle

​
The Dataset Version lifecycle

Dataset Version lifecycleSix steps: define the Dataset, revise the selection, create a Dataset Version as a Request, the version resolves or is refused, pin it from a consumer, and read it through a leased session with every chunk verified.1Define the Dataset2Revise the selection by revision3Create a Dataset Version (Request, 202)4Resolved, refused or reused5Pin it from the consumer6Read it: lease, verify, receiptdefine, resolve, pin and read a Dataset Versiona version is identified by dataset, commit, selection, holdout and layout hashes
  1. Define the Dataset
  2. Revise the selection by revision
  3. Create a Dataset Version (Request, 202)
  4. Resolved, refused or reused
  5. Pin it from the consumer
  6. Read it: lease, verify, receipt

Route names, states and limits come from the public API contract.

​
Steps, evidence, and responsibility

​
Notes on the harder steps

  • Selecting. Clause kinds are assetIds, sourceIds, seriesRoles, labelPrefix, reviewState (accepted or any), provenance (human-only or any) and holdout; each appears at most once. An empty selection is refused at admission or as a refused version, never created empty.
  • Holdout. Members you reserve out of training. The reader skips and counts them unless told otherwise; an edit that touches a holdout member raises an advisory after the save and never blocks.
  • Layout. 16 MiB chunks and eight members per shard are fixed; a shardCount override enters the layout hash and makes a different version. At most 1024 members per version.
  • Commit rule. A version pins the branch head at creation, skipping safety and handback commits, and says so in commitRule.
  • Refusal. A refused version carries a code, a message and up to 64 faults (more by reference). DATASET_BUILD_UNAVAILABLE means no run plane is configured for builds on that deployment.
  • Reading. Assignment is per member across ranks and workers; an uneven split raises locally with the numbers and the fix, or pads by at most reader-count minus one members and names each repeat. A read always carries the manifest hash; there is no “current version” fallback and no way to switch verification off.
  • Citing. Cite a version by its id plus its manifest hash, never by name; names may be reused.

​
Who owns each control point

​
Retire a Dataset Version (optional)

A Dataset Version can be tombstoned with DELETE /api/v1/dataset-versions/{id}. A fetch then answers the tombstone, lists hide it unless asked, and cleanup runs after a 30-day grace and deletes only unshared, uncited artifacts. The tombstone records who, when, graceUntil, previousState and the cleanup state. Links already issued into your own bucket are not recalled; they expire with the lease, at most an hour later. Deletion needs project admin. Public API credentials are capped at operate on every project, so the server refuses the delete 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. No dashboard screen deletes a Dataset Version.

​
What a download proves

The reader verifies each chunk against the Dataset Version manifest before returning its bytes.

​
Recorded events behind these steps

The workflow steps above map onto named records. Requests, versions, pins and tombstones are API resources; the rest are branch events. The product sends no webhooks; the contract declares one event type for a completed Request and no subscription route. Dataset Version downloads from a self-serve customer connection need a signer that Nitsor sets up with you. If a version uses separate read and write connections, each needs a signer. A version carrying masks also needs write access. An issued download link can remain valid until its lease ends, at most one hour; ordinary viewer links expire within 900 seconds.

​
Next step

Use Plan an integration to test one representative Dataset Version. The reader’s API is on the Public HTTP API page and in the Python SDK.
PlansAll plans
Last verified2026-09-30