Public HTTP API

Limited design-partner access Status: Limited design-partner access. The route contract and handlers below are implemented and tested. Access is limited by distribution, not by the authentication design: no supported public environment exists yet.

Authentication: every request carries Authorization: Bearer nitsor_agent_<48 hex>. The server stores only the SHA-256 hash of the token and derives the account and the acting Agent principal from the matching credential record. No request carries an account identifier or caller-declared principal data, so a caller cannot claim an identity it cannot prove. Credentials are scoped per operation, revocable with attribution, and issued only in the dashboard. Use this interface only inside an agreed design-partner environment.

No request example is presented as runnable. A public copy-and-paste request example remains forbidden until an end-to-end test executes the same request against a supported public environment.

Route inventory

The statuses below are the possibilities implemented by each current handler. Representative HTTP tests cover the shared success and failure mappings, but not every listed status is independently asserted for every route. No OpenAPI document is published.

Route	Purpose	Handler-implemented statuses	Current evidence
`GET /api/v1/decisions`	List recorded authorization decisions.	`200`, `400`, `404`	Registered handler and response contract
`GET /api/v1/ledger`	List event-attribution records connected to decisions.	`200`, `400`, `404`	Registered handler and response contract
`GET /api/v1/sources`	List a page of registered sources.	`200`, `400`	Registered handler, client coverage, and response contract
`POST /api/v1/sources`	Register a source from object references.	`201`, `400`, `403`, `422`	Registered handler and request/response contracts
`POST /api/v1/projects`	Create a project with an attributable principal and repeat-request key.	`201`, `400`, `403`, `404`	Registered handler and request/response contracts
`GET /api/v1/projects`	List projects for the current account.	`200`, `400`, `404`	Registered handler, client coverage, and response contract
`GET /api/v1/session`	Resolve the account associated with the current credential.	`200`, `401`	Registered handler, client coverage, and response contract
`POST /api/v1/storage-connections`	Register an object-storage connection without accepting raw secret values.	`201`, `400`, `403`	Registered handler and request/response contracts
`POST /api/v1/version-graph/branches`	Create an isolated branch from a known position.	`201`, `400`, `403`	Registered handler and request/response contracts
`GET /api/v1/version-graph/branches`	List version-graph branches.	`200`, `400`	Registered handler and response contract
`POST /api/v1/version-graph/commits`	Create a checkpoint-derived commit.	`201`, `400`, `403`	Registered handler and request/response contracts
`POST /api/v1/version-graph/landmarks/delete`	Append a landmark-deletion event.	`200`, `400`, `403`, `409`	Registered handler and request/response contracts
`POST /api/v1/version-graph/landmarks`	Append a landmark-upsert event.	`200`, `400`, `403`, `409`	Registered handler and request/response contracts
`POST /api/v1/version-graph/merges`	Attempt a typed three-way merge.	`200`, `400`, `403`	Registered handler; no client currently exercises this route
`GET /api/v1/version-graph/position`	Read a bounded page of the current landmark position.	`200`, `400`	Registered handler and response contract
`POST /api/v1/version-graph/project-metadata`	Append a project-metadata update event.	`200`, `400`, `403`, `409`	Registered handler and request/response contracts

The source routes provide cursor-based listing and reference-based registration. They recognize several format depths, but they do not upload source bytes, make every format viewable, or prove a supported public service.

Decisions, Ledger, and denials

Authorization records both allowed and denied decisions. A denied request can return a decisionId, which connects the response to the corresponding Decision and Ledger evidence. That evidence is attributed to the credential subject that made the request. A session identifies the account accepted by the current credential. It is not a published browser-session, refresh-token, or service-account contract.

Issue-code vocabulary

Clients can treat these 36 codes as the bounded issue vocabulary. A response may also carry a field path, remediation, missing permission scope, or decision identifier.

Code	Meaning
`ACCOUNT_NOT_FOUND`	The account accepted by the request could not be found.
`API_ERROR`	A request reached the API but failed without a narrower public code.
`API_UNREACHABLE`	The client could not reach the configured API origin.
`AUTHORIZATION_DENIED`	The authenticated principal lacks the required authority.
`AUTH_INVALID_TOKEN`	The current credential was rejected.
`AUTH_REQUIRED`	The operation requires a stored credential.
`CORRUPT_DICOM`	A referenced object could not be read as valid DICOM.
`CORRUPT_VGI`	A referenced VGI descriptor could not be parsed.
`DUPLICATE_SOP_INSTANCE_UID`	More than one object claimed the same DICOM instance identity.
`GEOMETRY_INCONSISTENT`	Slice geometry did not describe one consistent volume.
`GEOMETRY_OUT_OF_RANGE`	Valid geometry exceeds the range the viewer can display.
`IDEMPOTENCY_CONFLICT`	A repeat-request key conflicts with an earlier request.
`INVALID_ARGUMENT`	An input failed the command or request contract.
`INVALID_JSON`	JSON input or output could not be parsed as required.
`MISSING_SLICE`	The series evidence indicates a missing slice.
`MIXED_FORMAT_FAMILIES`	One registration contains objects from more than one format family.
`NO_VALID_DICOM_SLICES`	No referenced object produced a valid DICOM slice.
`PROJECT_CREATE_FAILED`	Project creation failed without a narrower public code.
`SERIES_IDENTITY_MISMATCH`	Referenced objects did not belong to one series identity.
`SLICE_ORDER_INCONSISTENT`	Slice ordering could not be established consistently.
`SOURCE_LIST_FAILED`	Listing registered sources failed.
`SOURCE_REGISTER_FAILED`	Source registration failed without a narrower public code.
`SOURCE_VERSION_AMBIGUOUS`	The referenced source version could not be resolved unambiguously.
`STORAGE_CONNECTION_REGISTER_FAILED`	Storage-connection registration failed.
`STORAGE_OBJECT_CHANGED_DURING_READ`	A referenced object changed while its registration evidence was being read.
`STORAGE_OBJECT_NOT_FOUND`	A referenced storage object was absent.
`STORAGE_OBJECT_TOO_LARGE`	A referenced object exceeded the accepted size boundary.
`STORAGE_READ_FAILED`	Reading a referenced object failed.
`UNEXPECTED_ERROR`	An unexpected failure crossed the public error boundary.
`UNKNOWN_COMMAND`	The command-line parser did not recognize the command.
`UNSUPPORTED_PIXEL_FORMAT`	The DICOM pixel format cannot be rendered.
`UNSUPPORTED_TRANSFER_SYNTAX`	The DICOM transfer syntax is not supported.
`UNSUPPORTED_VGI_SCENE`	The VGI scene cannot be rendered by the current viewer path.
`UNRECOGNIZED_FORMAT`	No known source-format signature was found.
`VERSION_GRAPH_OPERATION_FAILED`	A version-graph operation failed without a narrower public code.
`VGI_VOL_MISMATCH`	The VGI descriptor and referenced VOL data do not agree.

Programmatic access today

The HTTP contract and command-line client are the implemented programmatic surfaces. No public TypeScript or Python SDK, MCP server, webhook, or generated OpenAPI client is published. Their future shape remains open.

Common mistakes and limits

Registered routes do not make transport authentication production-ready.
A Zod contract (Zod is a TypeScript schema-validation library) is not an OpenAPI document.
A Decision record explains an authorization result; it does not authenticate the caller.
Route registration does not prove every route has client-level coverage. Merge is the explicit uncovered case today.

Next step

Review the Command-line interface for the tested client surface or Data model and contracts for the records these routes expose.

Outcome	Identify the 16 implemented routes without mistaking an implemented contract for a production-ready public service.
Availability	Limited design-partner access
Audience	Software engineers, Data engineers, AI agents
Prerequisites	Read Product status; Work within an agreed design-partner environment
Last verified	2026-08-18

Get started

Concepts

Guides

Reference

Route inventory

Decisions, Ledger, and denials

Issue-code vocabulary

Programmatic access today

Common mistakes and limits

Next step

​Route inventory

​Decisions, Ledger, and denials

​Issue-code vocabulary

​Programmatic access today

​Common mistakes and limits

​Next step

Route inventory

Decisions, Ledger, and denials

Issue-code vocabulary

Programmatic access today

Common mistakes and limits

Next step