Public HTTP API

All plans Every route on this page is served by the hosted deployments and described by the OpenAPI document. Two routes answer anonymously: the OpenAPI document and the capabilities endpoint. Every other route needs an agent credential issued by a workspace. The HTTP API is the current route for every client: the Python SDK described on this site is not on PyPI.

The OpenAPI document

The OpenAPI document defines request and response schemas. It is generated from the same contract the server and the Python SDK are built from, and the production copy is served anonymously at https://api.nitsor.com/api/v1/openapi.json. Every other operation needs an agent credential from a workspace. The document describes the contract, not your access.

Origin	Base	Document
Production	`https://api.nitsor.com/api/v1`	`GET /api/v1/openapi.json`

Community deployments serve the same contract at their own site URL, NITSOR_CONVEX_SITE_URL in .env, under /api/v1. The document’s info.version is v1; the served product version is in x-nitsor-product-version and in the capabilities answer. Each operation carries x-nitsor-scope (the permission or rung it needs), x-nitsor-minimum-version and, for lists, x-nitsor-cursor-kind.

Authentication

Every non-anonymous request carries Authorization: Bearer <token>, a token of a service account, which the guides call an agent token and the API calls an agent credential (Service accounts and tokens covers creating, replacing and revoking one). A malformed token is rejected before lookup, with the same 401 an unknown token gets. The server stores only the SHA-256 of the token and derives the account and the acting principal from the matching credential record. No request carries an account identifier or caller-declared principal, so a caller cannot claim an identity it cannot prove.

Fact	Value
Who issues a credential	An owner or admin, on Team settings, then Service accounts. The service-account routes do the same for a personal token that holds `service-accounts:manage`, which Nitsor does not issue today. A service account’s own token never can.
What it carries	The account permissions of its service account, or a narrower list the token was given when it was made, and an expiry: 90 days after creation by default and 365 at most. The API never honors `members:write`, `billing:write`, `clearance:write` or `service-accounts:manage` on a service account’s token, even if it lists one. A token reaches every project its service account is granted, unless it was narrowed to a list of projects when it was made.
Project authority	None until a project admin grants the token’s service account a rung on a project’s Access page (project Settings, then Access); at most `operate` on any project.
Rejection	`AUTH_REQUIRED` (401) with no token; `AUTH_INVALID_TOKEN` (401) for a token that is unknown or malformed, and for one that is expired or revoked or belongs to a disabled or retired service account, which carries a `reason` (Refused tokens); `AUTHORIZATION_DENIED` (403) with `missingScope` when the token is live but lacks authority; a `decisionId` is present only when the denial reached guarded write authorization, so a scope-denied read or a scope-denied write with a malformed body carries none.
Session	`GET /api/v1/session` answers the account and the principal (`type: "agent"`) behind the token, and which service account and token it is. See Session and expiry.

A person signs into the dashboard. Nitsor does not issue personal tokens today, so a person has no credential for the API.

Refused tokens

A refused token always gets 401 with the code AUTH_INVALID_TOKEN and retryable: false. When the token matches one Nitsor stored, the answer also carries a reason, a fixed message and remediation for that reason and, beside token_expired, an expiredAt. The words name nothing the caller did not send.

`reason`	`message`	When
`service_account_retired`	This token’s service account is retired	The service account is retired. Its tokens never work again.
`token_revoked`	This token was revoked	The token was revoked.
`token_expired`	This token has expired	The token’s expiry has passed. That includes a replaced token past its overlap and a shortened token past its new cutoff. `expiredAt` is the instant it stopped working, RFC 3339 in UTC, and is absent when the token never had an expiry recorded.
`service_account_disabled`	This token’s service account is disabled	The service account is disabled and the token is otherwise live. The token works again if an admin enables it.

When more than one holds, the first row wins. So service_account_disabled, the one reason that says wait, is given only when an enable would bring the token back. Only the holder of the whole token can learn a reason. A token Nitsor never stored, a malformed one and one that is not a service account’s get the same 401 with neither field, and so does a server that predates reasons. Treat reason as an open string: a client that meets one it does not know still has a refusal and the server’s message and remediation. When a token is refused says what an agent does with each. The Python SDK raises AuthRejectedError with reason, expired_at and the server’s remediation, and never retries it.

Discovery and versioning

GET /api/v1/capabilities is anonymous and answers:

Field	What it holds
`productVersion`	The server’s version, SemVer.
`apiVersion`	`v1`.
`deployment`	`bulkData: customer-object-storage`, `controlPlane: convex`, `transfer: presigned-url`.
`formats`	The recognized `sourceFormats` and `rawSliceEncodings`.
`limits`	The numeric limits, from `maxRequestBodyBytes` (1 MiB) and `maxPageSize` (100) to `datasetLeaseSeconds` (3600).
`minimumVersions`	For each operation, the oldest product version that serves it.

A client checks each method it is about to call against these minimums and refuses by name, as SERVER_VERSION_INCOMPATIBLE, before sending anything. The skew policy is that a client may use a method against any server whose apiVersion equals the method’s and whose productVersion is at or above that method’s floor; a server below one floor still serves every other method; there is no upper bound. Deprecations are announced through the language’s mechanism and kept for at least two stable minors and six months.

Request conventions

Convention	Rule
Bodies	JSON; at most 1 MiB. Most request schemas refuse an unknown property; a few, among them source registration and branch creation, drop it instead. Read the schema before relying on either.
Idempotency	Most writes with a body carry an `idempotencyKey` in it (up to 200 characters; task-comment writes allow 256). The same key with the same body replays the first answer for 24 hours; a different body answers `IDEMPOTENCY_CONFLICT`. The `asset-commit:` and `safety-checkpoint:` namespaces are reserved by the server. Ten writes take no key and refuse one: a Dataset Version pin, which is idempotent per principal, a read-session `access` call, and eight service-account writes (rename or describe, set permissions, set the owner, disable, enable, retire, revoke a token and shorten a token), which answer `changed: false` when they change nothing. Of the service-account writes only the three that mint a secret (create, add a token, replace a token) take a key. Two more have no body at all: `POST /requests/{id}/cancel` and `DELETE /dataset-versions/{id}`, which are idempotent by their path.
Request id	Every answer carries `X-Request-Id` and every error body a `requestId`; echo it when reporting a problem. It correlates one HTTP attempt and is not a durable handle.
Timestamps	RFC 3339 in UTC (`Z` or `+00:00`) on every record, task comments included; any other offset is refused where a string is expected.
Identifiers	Strings up to 200 characters, except task-comment ids at 256; content identities and hashes are `sha256:` followed by 64 hex characters.
Pagination	`GET` lists take `cursor` and `limit` (1 to 100, default 50) and answer `items` and `nextCursor`, except `GET /service-accounts`, which pages narrower: 1 to 25, default 25. A `limit` over a list’s own maximum is refused, never clamped. Cursors are opaque and typed per list; a cursor from another list is refused. Task-comment lists are `POST` routes that page by `before` and answer `threads` or `replies` with `nextBefore`. `GET /project-groups` answers the whole list unpaged, and `GET /project-shelf` takes `cursor`, `search` and `folded` but no `limit`.
Conditional reads	`GET /api/v1/requests/{id}` answers an `ETag`; send it back as `If-None-Match` for a `304`.
Rate limits	A `429` carries `RATE_LIMITED` and `Retry-After` in whole seconds.

Async Requests

Some writes are accepted rather than completed. POST /api/v1/datasets/{id}/versions answers 202 with an operationId. The Request is the durable handle.

Route	What it does
`GET /api/v1/requests/{id}`	The Request: `operation` (one of `import`, `export`, `model-run`, `report`, `prediction-import`, `dataset-version`), `state` (`queued`, `running`, `succeeded`, `failed`, `cancelled`), counts, result references, a report reference that is `retained` or `expired`, and on failure an error with an issue code.
`GET /api/v1/requests`	The account’s Requests, filterable by operation, state and principal.
`GET /api/v1/requests/{id}/items`	The per-item report: pending, succeeded, failed, rejected or cancelled items, up to 1000 per Request.
`POST /api/v1/requests/{id}/cancel`	Asks for cancellation; the answer is the acknowledgement, not a completed cancellation. `REQUEST_NOT_CANCELLABLE` when the kind cannot be cancelled.

A poll honors Retry-After (5 seconds by default) and sends If-None-Match. The Python SDK’s requests.wait polls with a ten-minute default budget; a wait never cancels on your behalf.

Stage	What the server does	Refusal it can answer
Discover	The client reads capabilities once and refuses methods below their floor locally.	`SERVER_VERSION_INCOMPATIBLE` (client side)
Authenticate	Hashes the bearer token and resolves the credential, account and principal.	`AUTH_REQUIRED`, `AUTH_INVALID_TOKEN`
Authorize	Checks the route’s scope or rung. A write that reaches guarded authorization records an allow or deny Decision; a read check records nothing.	`AUTHORIZATION_DENIED`, with `decisionId` when a Decision was recorded
Validate	Parses the body against the contract, the 1 MiB cap and the idempotency key.	`INVALID_ARGUMENT`, `INVALID_JSON`, `IDEMPOTENCY_CONFLICT`, `CHECKPOINT_REQUIRED`
Append	Appends the event to the branch with a Ledger entry, or accepts a Request.	Domain codes such as `DATASET_`, `SOURCE_`, `STORAGE_*`

Every refusal is one JSON envelope; the Python SDK maps each code to an error class. A decisionId is present only when the denial reached guarded write authorization.

Route inventory

Every operation answers the same error envelope on 400, 401, 403, 404, 405, 409, 413, 422 and 429. The scope column is the x-nitsor-scope of each operation: an account permission for account-level routes, a project rung for project-level ones.

Route	What it does	Scope
`POST /requests/{id}/cancel`	Cancel an async Request.	The operation’s own write scope
`GET /requests/{id}`	Read an async Request.	`account:read`
`GET /requests/{id}/items`	List an async Request’s per-item report.	`account:read`
`GET /requests`	List async Requests.	`account:read`
`GET /blind-checks/plan`	Read one blind-check plan and where it stands.	`read` rung
`POST /blind-checks/plan/rate`	Change the share of scans a running blind-check plan samples. Not callable by an integration today: it needs a signed-in person, and neither an Agent token nor a personal token is accepted. Change the plan on the Pipeline tab.	`operate` rung
`POST /blind-checks/plans/start`	Turn blind checks on for an auto-label stage and fix the plan. Not callable by an integration today: it needs a signed-in person, and neither an Agent token nor a personal token is accepted. Change the plan on the Pipeline tab.	`operate` rung
`POST /blind-checks/plan/stop`	Stop a running blind-check plan before its verdict. Not callable by an integration today: it needs a signed-in person, and neither an Agent token nor a personal token is accepted. Change the plan on the Pipeline tab.	`operate` rung
`GET /blind-checks/plans`	List a project’s blind-check plans.	`read` rung
`GET /blind-checks/checks`	List a plan’s submitted blind checks and their scores.	`read` rung
`GET /capabilities`	Discover server capabilities and version floors.	Anonymous
`POST /dataset-versions/{id}/access`	Open, renew or close a scoped read session on a Dataset Version.	`read` rung
`POST /datasets/{id}/versions`	Create an immutable Dataset Version.	`operate` rung
`GET /datasets/{id}/versions`	List a Dataset’s versions.	`read` rung
`DELETE /dataset-versions/{id}`	Tombstone a Dataset Version (a service account a project admin allowed to delete).	`admin` rung
`GET /dataset-versions/{id}`	Read a Dataset Version.	`read` rung
`GET /dataset-versions/{id}/exclusions`	List a Dataset Version’s excluded members.	`read` rung
`GET /dataset-versions/{id}/labels`	Read frozen labels with an opt-in layer filter and per-layer counts.	`read` rung
`POST /dataset-versions/{id}/pin`	Record this principal’s consumption of a Dataset Version.	`read` rung
`GET /dataset-versions/{id}/stats`	Read a Dataset Version’s Stats Block reference.	`read` rung
`POST /datasets`	Define a dataset.	`operate` rung
`GET /datasets`	List a project’s datasets.	`read` rung
`GET /datasets/{id}`	Read a dataset.	`read` rung
`POST /datasets/{id}`	Revise a dataset.	`operate` rung
`GET /decisions`	List audit decisions.	`account:read`
`GET /executions/detail`	Describe an execution.	`read` rung
`GET /executions/work-items`	List an execution’s work items.	`read` rung
`GET /executions`	List executions.	`read` rung
`GET /ledger`	List ledger entries.	`account:read`
`GET /model-label-outcomes/proposal`	Read what happened to one Proposal’s model labels.	`read` rung
`GET /model-label-outcomes/task`	Read the model label outcomes one Task recorded.	`read` rung
`POST /model-runs`	Run a model on Tasks, within the allowance a person confirmed.	Token permission `projects:write`, and the caller must also hold the `operate` rung on the project
`POST /model-runs/estimate`	Estimate the time and GPU-seconds a model run on Tasks would take.	`operate` rung
`GET /openapi.json`	Read the OpenAPI description of this API.	Anonymous
`POST /projects/{id}/assets`	Bind a Source Version into a Project as a Project Asset.	`operate` rung
`POST /projects`	Create a project.	`projects:write`
`GET /projects`	List accessible projects.	`read` rung
`POST /project-groups`	Create a project group.	`account:update`
`GET /project-groups`	List the account’s project groups.	`projects:read`
`POST /project-groups/{id}/delete`	Delete a project group, keeping its projects.	`account:update`
`POST /project-groups/{id}/move`	Move a project group.	`account:update`
`POST /project-groups/{id}`	Rename a project group.	`account:update`
`GET /project-shelf`	Page the project shelf: groups and readable projects.	`projects:read`
`POST /projects/{id}/group`	File a project into a group, or into none.	`account:update`
`POST /service-accounts/{id}/tokens`	Add a token to a service account; its secret is shown once.	`service-accounts:manage`
`POST /service-account-tokens/{id}/replace`	Replace a token with a successor under the same restriction; the secret is shown once.	`service-accounts:manage`
`POST /service-account-tokens/{id}/revoke`	Revoke a service account token now.	`service-accounts:manage`
`POST /service-account-tokens/{id}/shorten`	Move a service account token’s expiry earlier.	`service-accounts:manage`
`POST /service-accounts`	Create a service account, with or without a first token whose secret is shown once.	`service-accounts:manage`
`GET /service-accounts`	List the account’s service accounts.	`service-accounts:manage`
`POST /service-accounts/{id}/disable`	Disable a service account: every token stops until it is enabled.	`service-accounts:manage`
`POST /service-accounts/{id}/enable`	Enable a disabled service account: its unexpired, unrevoked tokens work again.	`service-accounts:manage`
`GET /service-accounts/{id}`	Read a service account with its tokens and project grants.	`service-accounts:manage`
`POST /service-accounts/{id}`	Rename or describe a service account.	`service-accounts:manage`
`POST /service-accounts/{id}/retire`	Retire a service account for good: every token is revoked and its project access ends.	`service-accounts:manage`
`POST /service-accounts/{id}/owner`	Name the member who answers for a service account.	`service-accounts:manage`
`POST /service-accounts/{id}/permissions`	Replace the permissions a service account holds.	`service-accounts:manage`
`GET /projects/{id}/service-accounts`	List the service accounts granted access to a project.	`admin` rung, personal token only
`POST /projects/{id}/service-accounts`	Grant a service account a rung on a project, or change it.	`admin` rung, personal token only
`POST /projects/{id}/service-accounts/remove`	Remove a service account’s access to a project.	`admin` rung, personal token only
`GET /session`	Describe the current authenticated session.	None beyond a valid token
`POST /sources/mask-read-presign`	Presign mask reads for a source.	`read` rung
`POST /sources/representation/presign`	Presign a read of a Source or Task viewer representation with exact integrity pins.	Source access or Task authority
`GET /sources/representation`	Read viewer representation status under Source access or Task authority.	Source access or Task authority
`GET /sources`	List registered sources.	`sources:browse`
`POST /sources`	Register source objects from a storage connection.	`sources:register`
`POST /storage-connections`	Register a storage connection.	`storage:write`
`GET /storage-connections/{id}`	Read a storage connection and the viewer bytes Nitsor wrote into it.	`storage:read`
`GET /storage-credential-handles`	List the account’s provisioned storage credential handles.	`storage:write`
`POST /storage-credentials`	Connect a bucket with your own key: test it, then seal it and create a read-only connection.	Personal authority only (owner or admin). An Agent token is refused, so an integration cannot call it today
`POST /tasks/comments/attention`	List task comments needing attention.	`read` rung
`POST /tasks/comments/list`	List task comments.	`read` rung
`POST /tasks/comments/replies`	List task comment replies.	`read` rung
`POST /tasks/comments/write`	Write a task comment.	`contribute` rung
`GET /taxonomy`	Read the taxonomy.	`read` rung
`POST /taxonomy/bind`	Bind the taxonomy.	`operate` rung
`POST /version-graph/annotations/commit`	Commit annotations.	`contribute` rung
`POST /version-graph/branches`	Create a version-graph branch.	`operate` rung
`GET /version-graph/branches`	List version-graph branches.	`read` rung
`POST /version-graph/commits`	Append a version-graph commit.	`operate` rung
`POST /version-graph/landmarks/delete`	Delete a version-graph landmark.	`operate` rung
`POST /version-graph/landmarks`	Upsert a version-graph landmark.	`operate` rung
`POST /version-graph/merges`	Merge version-graph branches.	`operate` rung
`GET /version-graph/position`	Read the version-graph position.	`read` rung
`POST /version-graph/project-metadata`	Update version-graph project metadata.	`operate` rung
`GET /workflow/definition`	Read the workflow definition.	`read` rung
`POST /workflow/definition/bind`	Bind the workflow definition.	`operate` rung

Paths above omit the /api/v1 prefix. The Data model and contracts page describes the records these routes read and write; the OpenAPI document carries every field. The source representation routes report status (unavailable, pending, failed or ready) and presign a read of a ready viewer representation. See Model label outcomes for outcome categories and finality.

Session and expiry

GET /api/v1/session answers who the credential acts as, which token it is, what it can do and where. It takes limit and cursor to page the reach, like any list. It describes only the token that made the request, never another token of the same service account, and it never returns a token’s text or hash.

Field	What it holds
`accountId`, `accountName`	The workspace behind the credential.
`principal`	`displayName`, `subject` and `type`: `agent` for a service account’s token, `user` for a personal token.
`serviceAccount`	`id`, `name` and `status` (`active`, `disabled` or `retired`) of the service account the token belongs to. Absent on a personal token. A token of a disabled or retired service account does not authenticate, so the call fails with 401 before it can report that state; the 401’s `reason` says why, which for a disabled service account is `service_account_disabled` only on an otherwise live token (Refused tokens).
`token`	`expiresAt` (RFC 3339 in UTC); `hint`, the last four characters of the token, absent on a token made before hints and on a personal token; `restriction`, `inherits` when the token carries no limits of its own and `narrower` when it carries its own list of permissions, or a nonempty list of projects, even a permission list that equals its service account’s list today; `projectRungCap`, the highest project access level the token can use, `operate` for every service account token; and `createdVia`, which says how a personal token was made.
`effectivePermissions`	The account permissions the credential holds right now. It is the answer the API’s own `403` checks use, so a refusal never contradicts it.
`projects`, `nextCursor`	One page of the projects the credential reaches, each with `name`, `projectId` and its `rung`. A page can hold fewer projects than `limit`, or none, while `nextCursor` is set, so keep following it until it is null.

accountId, accountName and principal are always present. Every other field is optional on the wire, so a client reads a server that predates it. In the last 14 days of a token’s life, every authenticated response carries a Nitsor-Token-Expires header. Its value is the instant the token stops working, RFC 3339 in UTC with millisecond precision. Earlier responses carry no header, and a token that has already ended never authenticates. The rule is the same for a service account’s token and a personal token, and the OpenAPI document declares the header. Expiry warnings says what the Python SDK does with it.

Service accounts

A service account is the lasting identity a job runs as, and its tokens are the secrets that prove it. These thirteen routes manage both under the same rules as the dashboard: Service accounts and tokens explains each rule. Every route needs the service-accounts:manage permission, reads included, on a personal token. Nitsor does not issue personal tokens today, so no call to these routes succeeds yet. A service account’s own token is refused on every one of them with AUTHORIZATION_DENIED (403) naming service-accounts:manage, so a service account cannot manage a service account. Bodies are strict: a body that names an id beside the path’s {id} is refused, and so is an idempotencyKey on any write except the three that mint a secret.

Route	What it does	Request fields	Answer
`GET /service-accounts`	Lists service accounts, newest first.	Query: `status` (`active`, `disabled` or `retired`), `limit` (1 to 25, default 25; 26 or more is refused as `INVALID_ARGUMENT`, 400), `cursor`.	`items` and `nextCursor`.
`POST /service-accounts`	Creates a service account, with or without a first token. Grants it no project access.	`name`, `accountPermissions` (may be empty) and `idempotencyKey`; optional `description`, `ownerEmail` or `ownerMembershipId` (not both) and `firstToken` (`name`, `expiresInDays` or `expiresAt`, `accountPermissions`, `projects`, `storageNote`).	201 with `outcome` (`created` or `replayed`), `serviceAccount` and `token`, which carries `secret` once.
`GET /service-accounts/{id}`	Reads one service account with its tokens and its project grants.	None.	`serviceAccount`, `tokens` newest first, `tokensTruncated`, `grants` (`projectId`, `projectName`, `rung`, `createdAt`) and `grantsTruncated`.
`POST /service-accounts/{id}`	Renames or describes it.	`name`, `description`; name at least one. An empty `description` clears it.	`changed` and `serviceAccount`.
`POST /service-accounts/{id}/permissions`	Replaces the list of account permissions it holds.	`accountPermissions` (may be empty).	`added`, `removed`, `changed` and `serviceAccount`.
`POST /service-accounts/{id}/owner`	Names the member who answers for it.	Exactly one of `ownerEmail`, the address the member signs in with, and `ownerMembershipId`, the member’s row on the account.	`changed` and `serviceAccount`.
`POST /service-accounts/{id}/disable`, `/enable`, `/retire`	Pauses it, resumes it, or ends it for good.	Optional `reason`.	`changed` and `serviceAccount`; retire adds `revokedTokens`.
`POST /service-accounts/{id}/tokens`	Adds a token.	`name` and `idempotencyKey`; optional `expiresInDays` or `expiresAt`, `accountPermissions`, `projects`, `storageNote`.	201 with `outcome` (`issued` or `replayed`), `serviceAccountId` and `token`.
`POST /service-account-tokens/{id}/revoke`	Revokes a token now.	Optional `reason`.	`changed` and `token`.
`POST /service-account-tokens/{id}/replace`	Replaces a live token with a successor under the same restriction and name.	`idempotencyKey`; optional `overlapMs`, `expiresInDays` or `expiresAt`.	201 with `outcome`, `previous` (`id`, `name`, `status`, `stopsAt`), `serviceAccountId` and `token`.
`POST /service-account-tokens/{id}/shorten`	Moves a live token’s expiry earlier.	`expiresAt`.	`changed`, `previousExpiresAt` and `token`.

Each write that changes nothing answers changed: false, such as the same rename again, disabling a disabled service account, revoking a revoked token or shortening to the cutoff the token already has.

Field rules

Field	Rule
`name`	1 to 100 characters after trimming. Unique, whatever the letter case, among service accounts that are not retired. A token’s `name` defaults to its service account’s name when `firstToken` names none.
`description`, `reason`	Up to 500 characters.
`storageNote`	Up to 200 characters. Where you will keep the secret, a label and never a secret.
`accountPermissions` on a service account	A list of account permissions, never including `members:write`, `billing:write`, `clearance:write` or `service-accounts:manage`. On create, every permission must be one your own token holds. When you replace the list, only the permissions you add must be; keeping or removing an entry the list already has needs nothing more than `service-accounts:manage`.
`accountPermissions` on a token	Absent: the token inherits its service account’s list. A list: an upper bound, and it can only name permissions the service account holds. An empty list: no account permission, and the token can still act through its project access.
`projects` on a token	Up to 32 project ids of the account. Absent or empty: every project the service account is granted.
`expiresInDays`, `expiresAt` on a new token or a replace	Name one or neither. `expiresInDays` is 7, 30, 90 or 365. `expiresAt` is an instant at least one hour and at most 365 days away. Neither: 90 days.
`expiresAt` on a shorten	Any instant in the future that is not later than the token’s current expiry. The one-hour floor does not apply.
`overlapMs`	A whole number of milliseconds from 0 to 86,400,000 (24 hours), 24 hours by default. The replaced token keeps working until the earlier of its current expiry and `overlapMs` from now, so a token that expires sooner than the overlap still stops at its own expiry. `previous.stopsAt` says when. The successor has the same name, so two live tokens share a name until the old one stops: name the old token by its id.
`ownerMembershipId`	The membership id of an active member. On create, the caller is the owner only when both `ownerMembershipId` and `ownerEmail` are absent.
`ownerEmail`	The email an active member signs in with, matched without regard to case, so the member need not own a service account yet. It needs a token that also holds `members:read`. Name the owner by this or by `ownerMembershipId`, never both.

A service account holds at most 10 live tokens. A replace is allowed at 10, because it ends the replaced token. A token that already has a successor cannot be replaced again, and a successor cannot be replaced while the token it replaced is still live.

The resources

A service account carries id, subject, name, description, status, accountPermissions, createdAt and createdBy, and once it was disabled or retired disabledAt, disabledBy, disabledReason, retiredAt, retiredBy and retiredReason. owner carries membershipId, active and, once the membership ended, leftAt; name and email appear only for a caller holding members:read. liveTokens carries count, lastUsedAt and soonestExpiresAt, and projectGrants carries count; each says truncated when its read stopped at a ceiling, and then count is a floor. A token carries id, serviceAccountId, name, status (active, disabled while its service account is disabled, expired or revoked), hint, createdAt, createdBy, expiresAt, lastUsedAt, storageNote, restriction (accountPermissions, absent when the token inherits, and projects) and effectivePermissions, what the service account and the token allow together now. A rolled token adds replacedAt, replacedByTokenId or replacesTokenId, and a revoked one revokedAt, revokedBy and revokedReason. A token never carries its text or its hash.

Secrets are shown once

Three routes mint a secret: create with a first token, add a token and replace a token. The secret is on the answer that created the token and on no other. Nitsor keeps only a hash of it and the hint. A retry under the same idempotency key with the same request answers replayed and carries no secret, because the secret was shown on the first answer. The same key with a different request is refused as IDEMPOTENCY_CONFLICT. If you lost the first answer, replace the token.

Refusals

For a caller that holds service-accounts:manage, a request that fails the contract’s schema is refused before any rule runs, as INVALID_ARGUMENT (400) with no reason and, when one field is at fault, its fieldPath: a name that is empty or over 100 characters, a description or reason over 500, a storage note over 200, more than 32 projects, an overlap outside 0 to 24 hours or not a whole number, an unknown field, or an expiry in the wrong form. A rule the request passed the schema but broke is the usual error envelope with the code API_ERROR, the registry’s HTTP status and a reason that names the rule. A reused idempotency key keeps its own code: IDEMPOTENCY_CONFLICT (409) with the reason idempotency_conflict.

Reason	Status	When
`service_account_not_found`	404	The id is not a service account of this account.
`service_account_update_empty`	400	An update names neither a name nor a description.
`service_account_name_taken`	409	Another service account that is not retired carries the name.
`service_account_permission_ineligible`	400	The list names a permission a service account can never hold. For a service account’s list, on create and when you replace it, the caller’s own reach is checked first, so a permission your token does not hold is refused as `token_scope_escalation` and this answer means your token holds it. For a token’s own `accountPermissions` (a first token or an added token) this is checked first, before the list is compared with the service account’s and with your own reach.
`owner_not_member`	409	The owner is not an active member of the account. An `ownerEmail` that no active member has gets this answer too, whether it was never a member’s or its member left.
`owner_email_needs_members_read`	403	An `ownerEmail` on a token that does not hold `members:read`. Answered before any member is read, so it says nothing about whether the address belongs to one. Use a token that holds it, or name the owner by `ownerMembershipId`.
`owner_email_unresolved`	409	An `ownerEmail` could not be settled to one member: two active members share it, or the roster is too large to search whole (over 2,000 memberships, past members included), which leaves even a single match unresolved. Name the owner by `ownerMembershipId`.
`service_account_disabled`	409	A token was added or replaced while the service account is disabled.
`service_account_retired`	409	A rename, a description, a permission or owner change, a disable, an enable, a second retire or an added token on a retired service account. Revoking a token is not refused.
`token_live_limit_reached`	409	The service account already holds 10 live tokens.
`token_expiry_ambiguous`, `token_expiry_too_soon`, `token_expiry_in_past`, `token_expiry_exceeds_maximum`	400	Both a preset and a date, a new token’s instant under an hour away, an instant in the past, or an instant over 365 days away. A shorten has no one-hour floor.
`token_expiry_extension_refused`	409	A shorten that would move the expiry later. Replace the token to extend it.
`token_scope_escalation`	403	The request names a permission the caller’s own token does not hold: any permission on create, a permission you add when you replace a service account’s list, or a permission a new token would hold, checked after the token’s list has passed the eligibility and service-account checks.
`token_restriction_beyond_issuer`, `token_issuer_rung_capped`	403	The caller’s own token reaches fewer projects, or is capped below `operate`, than the token it would issue.
`token_restriction_exceeds_identity`	409	A token’s list names a permission its service account does not hold.
`project_not_found`	404	A token’s restriction names a project that is not on the account.
`token_not_found`	404	The id is not a token of this account.
`token_not_live`	409	A replace or a shorten on a token that is revoked or expired.
`token_already_replaced`, `token_rollout_in_progress`, `token_restriction_unheld`	409	A token that already has a successor, a replaced token that is still live, or a restriction that names a project the service account holds no grant on. A replace never restores a removed grant.
`idempotency_conflict`	409	The idempotency key was used for a different request. The envelope’s code is `IDEMPOTENCY_CONFLICT`.
`service_account_list_incomplete`, `service_account_name_check_incomplete`	409	While a deployment finishes an upgrade, a list filtered by `status` is refused whole, and a create or rename can be refused before its name is checked. The unfiltered list is complete, the name is not the cause, and both clear on their own.

A service account’s access to a project

Three routes under /api/v1/projects/{id}/service-accounts list, grant, change and remove a service account’s access to one project, the same act as that project’s Access page. Each needs a personal token that holds admin on the project through its own project list and rung cap; no account permission is required, and a service account’s own token never holds admin, so it is refused on all three. A personal token capped at admin lasts 7 days at most. Nitsor does not issue personal tokens today, so no call to these routes succeeds yet.

Route	What it does	Request fields	Answer
`GET /projects/{id}/service-accounts`	Lists the service accounts granted access to the project, oldest grant first.	Query: `limit` (1 to 100, default 50), `cursor`.	`items` and `nextCursor`.
`POST /projects/{id}/service-accounts`	Grants a service account a rung on the project, or changes the rung it holds. A service account holds `operate` at most.	`serviceAccountId`, `rung` (`read`, `contribute`, `operate` or `admin`) and `idempotencyKey`.	`changed`, `previousRung`, `rung`, `projectId`, `serviceAccountId`, `releasedHeldTasks`, `releasedAllHeldTasks` and `endedDelegatedActions`.
`POST /projects/{id}/service-accounts/remove`	Removes the service account’s access, whatever its state.	`serviceAccountId` and `idempotencyKey`.	`changed`, `projectId`, `serviceAccountId`, `releasedHeldTasks` and `releasedAllHeldTasks`.

A drop to read, and a remove, release the Tasks the service account held in the project, one page per call: while releasedAllHeldTasks is false, send the same request again under a new key. A changed rung also ends any delegated action the service account held there, named in endedDelegatedActions (today only dataset-version:delete); a project admin gives it again if it is still needed. Both writes take the request body’s idempotencyKey: a retry under it answers the first call’s outcome and changes nothing, even after someone else changed the grant since; the same key with a different request is IDEMPOTENCY_CONFLICT (409).

Reason	Status	When
`principal_permission_denied`	403	On `GET`: the caller’s personal token does not hold `admin` on this project. A service account’s own token is refused the same way: only a personal token can call these routes. On the two `POST` routes the same refusal has no `reason`; see below the table.
`service_account_rung_exceeds_cap`	403	The request names `admin` for a service account. A service account holds `operate` at most.
`service_account_disabled`	409	A grant or a rung change on a disabled service account. Remove still works.
`service_account_retired`	409	A grant or a rung change on a retired service account. Remove still works.
`project_not_found`	404	The id is not a project of this account.
`service_account_not_found`	404	The id is not a service account of this account.
`idempotency_conflict`	409	The idempotency key was used for a different request. The envelope’s code is `IDEMPOTENCY_CONFLICT`.

On the two POST routes, a caller without admin on the project gets AUTHORIZATION_DENIED (403) with missingScope: "admin" and no reason. A decisionId comes with it only when the request reached guarded write authorization, so a refused request with a malformed body carries none. A script that checks for principal_permission_denied must also check for this code.

Decisions, Ledger, and denials

Authorization of a write records both allowed and denied Decisions once the request reaches guarded write authorization; a read check refuses without recording one. An unscoped write whose body is invalid is refused as 403 before any Decision is written and carries no decisionId. A denied write that recorded a Decision returns a decisionId, which connects the response to the Decision (verdict, policy, reason code, resource, scope, principal) through GET /api/v1/decisions. A Ledger entry ties each accepted event to its Decision and is listed by GET /api/v1/ledger. Both are attributed to the credential subject that made the request. Neither has a dashboard screen.

Issue-code vocabulary

Every refusal is one JSON envelope: code, message, requestId, retryable, and where they apply fieldPath, remediation, missingScope, decisionId, reason, the rule a domain refusal names beside its code, and expiredAt, the instant a refused token stopped working. Clients can treat the served codes below, plus the client-only DEADLINE_EXCEEDED, as the bounded vocabulary; a newer server may add one, and a client that meets an unknown code treats it as a refusal on the merits.

Group	Codes
Authentication and authority	`AUTH_REQUIRED`, `AUTH_INVALID_TOKEN`, `AUTHORIZATION_DENIED`, `ACCOUNT_NOT_FOUND`
Request shape	`INVALID_ARGUMENT`, `INVALID_JSON`, `METHOD_NOT_ALLOWED`, `IDEMPOTENCY_CONFLICT`, `RATE_LIMITED`, `CHECKPOINT_REQUIRED`, `API_ERROR`, `UNEXPECTED_ERROR`
Client conditions	`API_UNREACHABLE`, `UNKNOWN_COMMAND`, `SERVER_VERSION_INCOMPATIBLE` (in the vocabulary, minted by clients), `DEADLINE_EXCEEDED` (client-only)
Sources and storage	`STORAGE_CONNECTION_REGISTER_FAILED`, `SOURCE_REGISTER_FAILED`, `SOURCE_LIST_FAILED`, `SOURCE_VERSION_AMBIGUOUS`, `STORAGE_OBJECT_NOT_FOUND`, `STORAGE_OBJECT_TOO_LARGE`, `STORAGE_OBJECT_CHANGED_DURING_READ`, `STORAGE_READ_FAILED`, `MIXED_FORMAT_FAMILIES`, `UNRECOGNIZED_FORMAT`
DICOM and volumes	`CORRUPT_DICOM`, `NO_VALID_DICOM_SLICES`, `DUPLICATE_SOP_INSTANCE_UID`, `SERIES_IDENTITY_MISMATCH`, `SLICE_ORDER_INCONSISTENT`, `MISSING_SLICE`, `GEOMETRY_INCONSISTENT`, `GEOMETRY_OUT_OF_RANGE`, `UNSUPPORTED_TRANSFER_SYNTAX`, `UNSUPPORTED_PIXEL_FORMAT`, `CORRUPT_VGI`, `VGI_VOL_MISMATCH`, `UNSUPPORTED_VGI_SCENE`
Projects, graph, workflow	`PROJECT_CREATE_FAILED`, `VERSION_GRAPH_OPERATION_FAILED`, `TAXONOMY_OPERATION_FAILED`, `WORKFLOW_OPERATION_FAILED`
Datasets	`DATASET_NOT_FOUND`, `DATASET_NAME_CONFLICT`, `DATASET_REVISION_CONFLICT`, `DATASET_SELECTION_EMPTY`, `DATASET_HEAD_UNCOMMITTED`, `DATASET_NO_QUALIFYING_COMMIT`, `DATASET_MEMBERSHIP_UNDECLARED`, `DATASET_HARD_MEMBER_MISSING`, `DATASET_HARD_MEMBER_EXCLUDED`, `DATASET_OBJECT_MISSING`, `DATASET_OBJECT_CHANGED`, `DATASET_MEMBER_TOO_LARGE`, `DATASET_LAYOUT_UNSATISFIABLE`
Dataset Versions	`DATASET_VERSION_NOT_FOUND`, `DATASET_VERSION_RESOLVING`, `DATASET_VERSION_NAME_CONFLICT`, `DATASET_BUILD_UNAVAILABLE`, `DATASET_BUILD_INVALID`, `DATASET_FREEZE_TIMEOUT`, `DATASET_VERSION_CANCELLED`, `DATASET_VERSION_TOMBSTONED`, `DATASET_VERSION_REVOKED`, `DATASET_MANIFEST_HASH_MISMATCH`, `DATASET_READ_SESSION_NOT_FOUND`, `DATASET_READ_SESSION_CLOSED`
Requests	`REQUEST_NOT_FOUND`, `REQUEST_NOT_CANCELLABLE`, `REQUEST_LANDING_TOO_LARGE`, `REQUEST_REPORT_EXPIRED`, `REQUEST_WORKER_EXHAUSTED`

The Python SDK maps each code to one error class; see Python SDK.

Python SDK

The Python SDK is generated from the same contract. Its authenticated calls work on Team and Enterprise. A Community deployment has no supported way to issue the agent credential it needs; credentials are issued in the hosted app on Team and Enterprise. Its service-account methods need a personal token, so they cannot succeed; see Service accounts. Anonymous discovery needs no credential. The SDK is named nitsor and is not on PyPI. Call the HTTP API directly. The table describes the SDK as built.

Fact	`nitsor` (Python)
Runtime	Python 3.11 to 3.13; sync `Nitsor` and async `AsyncNitsor`; Pydantic models under `nitsor.types`.
Methods	`session`, `capabilities`, `projects`, `branches` (create only), `sources`, `assets`, `outcomes`, `model_runs`, `datasets` (with `versions.create_and_wait`), `service_accounts` (with `tokens` and `project_access`) and `requests`; no manifest walk outside the reader, which is `nitsor.data.open`. See the coverage table.
Credentials	`Nitsor()` and `AsyncNitsor()` resolve once: an explicit `token`, then `NITSOR_TOKEN`, then the `credentials.json` profile in `NITSOR_CONFIG_DIR` (`~/.config/nitsor` by default, `NITSOR_PROFILE` picks the profile); a present but unusable source fails, never falls through. `NITSOR_API_URL` names the API origin for an environment token, and the default is `https://api.nitsor.com`. See Credential profiles below for the file’s shape.
Transport rules	HTTPS except loopback; redirects refused; JSON reads capped at 1 MiB; 429, 5xx and connection failures retried with full jitter; other 4xx never retried, over `httpx2`.
Pagination	`auto_paging_iter()`; repeated cursors and more than 10,000 pages fail explicitly.
Errors	`NitsorError` and subclasses `AuthRequiredError`, `AuthRejectedError`, `RefusedError`, `TransientError`, `IncompatibleServerError`, `UnknownRefusalError`; each carries `reason` when the refusal names its rule, and `expired_at` on a refused token’s.
Training reader	`nitsor.data.open((version_id, manifest_hash), installation_id=…, assignment=…)`; `nitsor[torch]` and `nitsor[monai]` extras.

The Python reader streams a pinned version in whole shards, verifies every chunk before it reaches a cache or a tensor, refuses an uneven assignment locally with the numbers and the fix, and checks the per-epoch coverage invariant yielded + skipped_tombstoned + skipped_holdout == assigned.

Credential profiles

Set NITSOR_TOKEN for a single account; the Quickstart and Register a source journeys both use it. A profile file lets you switch between accounts, or store a token with its base URL, without setting NITSOR_TOKEN in every shell. No command writes it. Create credentials.json by hand in ~/.config/nitsor/, or in the directory that NITSOR_CONFIG_DIR names:

{
  "version": 2,
  "defaultProfile": "default",
  "profiles": {
    "default": {
      "accountId": "<accountId from GET /api/v1/session>",
      "baseUrl": "https://api.nitsor.com",
      "token": "..."
    }
  }
}

accountId, baseUrl and token are required strings on every profile. defaultProfile names the profile Nitsor() reads when NITSOR_PROFILE is unset; with exactly one profile, defaultProfile can be left out. NITSOR_PROFILE=<name> or profile="<name>" picks a different one. On macOS and Linux, restrict the file to its owner (chmod 600 ~/.config/nitsor/credentials.json). There the SDK prints a warning on stderr, and still reads the file, when other users can read it. On Windows the SDK does not check the file’s permissions, so restrict access to the file yourself.

Next step

Review the Python SDK for the tested client surface or Data model and contracts for the records these routes expose.

Plans	All plans
Last verified	2026-10-21

Get started

Concepts

Guides

Reference

The OpenAPI document

Authentication

Refused tokens

Discovery and versioning

Request conventions

Async Requests

What happens to one request

Route inventory

Session and expiry

Service accounts

Field rules

The resources

Secrets are shown once

Refusals

A service account’s access to a project

Decisions, Ledger, and denials

Issue-code vocabulary

Python SDK

Credential profiles

Next step

​The OpenAPI document

​Authentication

​Refused tokens

​Discovery and versioning

​Request conventions

​Async Requests

​What happens to one request

​Route inventory

​Session and expiry

​Service accounts

​Field rules

​The resources

​Secrets are shown once

​Refusals

​A service account’s access to a project

​Decisions, Ledger, and denials

​Issue-code vocabulary

​Python SDK

​Credential profiles

​Next step

The OpenAPI document

Authentication

Refused tokens

Discovery and versioning

Request conventions

Async Requests

What happens to one request

Route inventory

Session and expiry

Service accounts

Field rules

The resources

Secrets are shown once

Refusals

A service account’s access to a project

Decisions, Ledger, and denials

Issue-code vocabulary

Python SDK

Credential profiles

Next step