> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nitsor.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Nitsor is a pre-release product. Every page in this documentation carries an availability status in its frontmatter (`availability`) and, as the first element of its body, a link labelled `Available now`, `Limited design-partner access`, or `Planned - not available yet`. That label is binding: it says whether a reader can use the behaviour the page describes.
> A page written in the present tense is not a claim that the behaviour ships. Where the availability label says `Planned - not available yet`, the page describes a target contract and there is no runnable product, screen, command, or public interface behind it.
> Every readiness claim this documentation makes lives on the Product status page. If any statement elsewhere disagrees with the capability status matrix on that page, the matrix is correct.
> Reading this documentation grants no product access and no permission. No agent can create or approve a Nitsor release.

# Public HTTP API

> Evaluate the implemented HTTP contract, its error vocabulary, and the hashed agent-credential authentication scheme.

<a className="nit-availability" data-availability="design-partner" href="/product-status#status-definitions" aria-label="Limited design-partner access. Read the status definitions."><span aria-hidden="true" className="nit-availability__dot" />Limited design-partner access</a>

**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](/reference/cli) for the tested client surface or [Data model and contracts](/reference/data-model) for the records these routes expose.

<table className="nit-page-details" aria-label="Page details">
  <tbody>
    <tr><th scope="row">Outcome</th><td>Identify the 16 implemented routes without mistaking an implemented contract for a production-ready public service.</td></tr>
    <tr><th scope="row">Availability</th><td>Limited design-partner access</td></tr>
    <tr><th scope="row">Audience</th><td>Software engineers, Data engineers, AI agents</td></tr>
    <tr><th scope="row">Prerequisites</th><td>Read Product status; Work within an agreed design-partner environment</td></tr>
    <tr><th scope="row">Last verified</th><td>2026-08-18</td></tr>
  </tbody>
</table>