Laboratory › Developers › Reference

API reference

Generated from content/api-registry.json — the same file the OpenAPI document and the API index come from, and the one a build test checks against the routes actually emitted, in both directions.

There is no second, hand-written description of API semantics anywhere in this project. That is the only way documentation and implementation stay in step without discipline nobody sustains.

OpenAPI 3.1 · base URL https://tiffany.systems · contract 2026-09-10

Scientific records Available

Published scientific claims and the record of how their standing has changed. Empty by design today: nothing has completed the release process.

Authority: These endpoints transport records that were already qualified by the publication process. Reaching one of them establishes nothing about a claim. Availability is not validity.

Authentication: none. Fixtures never appear in this family.

GET /api/claims.json Available Stable No auth

Every published scientific claim identity.

The entry point for a client that wants the laboratory's current scientific positions. Returns an empty set until a finding completes release review. A fixture can never appear here.

Response: application/json · claim-index schema (enforced at build time)

count is 0 today and the note field says why. An empty result is the correct answer, not an outage.
Fixtures are served under /api/demo/ and carry classification DEMO_FIXTURE. This endpoint has no classification field precisely because it can only ever contain public science.

GET /api/changes.json Available Stable No auth

Scientific state changes, newest first.

Poll this to learn that a claim was superseded, withdrawn, replicated, or had a falsifier executed against it. It is not a release log: it carries the changes that make claims weaker as well as stronger.

Response: application/json · changes schema (enforced at build time)

A claim becoming superseded or withdrawn appears here. It is not an API contract change and does not appear in the API changelog.

GET /feed.xml Available Stable No auth

The same scientific state changes as an Atom feed.

For readers and aggregators that speak Atom rather than JSON. Fixtures never appear in it.

Response: application/atom+xml · self-describing reference document; no published envelope schema

Currently carries a subtitle explaining the empty state and no entries.

Reference documents Available

The vocabulary, the publication rules, the schemas, the operational status and the ledger of what was deliberately not built.

Authority: Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims.

Authentication: none. Fixtures never appear in this family.

GET /api/index.json Available Stable No auth

Discovery document listing every other public endpoint.

A client that knows only the base URL starts here. It also states the guarantees the URL scheme makes, so an agent can decide what it is allowed to cache and cite.

Response: application/json · api-index schema (enforced at build time)

GET /api/ontology.json Available Stable No auth

Every status term used anywhere on the site, defined and versioned.

A machine client must resolve status terms through this document rather than pattern-matching strings. The definitions are versioned; a changed meaning requires a new ontology version, never a silent edit.

Response: application/json · self-describing reference document; no published envelope schema

Self-describing reference document. Its shape is stable but is not constrained by a published JSON Schema — the definitions themselves are the contract.

GET /api/policy.json Available Stable No auth

The deterministic publication rules and state-machine invariants enforced at build time.

Lets a client check what a published record was required to satisfy. Generated from the running implementation, not maintained beside it.

Response: application/json · self-describing reference document; no published envelope schema

GET /api/status.json Available Stable No auth

What is published, what is sealed, what is deferred, and the state of each API family.

Operational state. Nothing in it is evidence about any claim, and traffic or uptime never affects a scientific status.

Response: application/json · status schema (enforced at build time)

GET /api/deferred.json Available Stable No auth

Components designed and deliberately not built, each with the condition that would activate it.

So a client can tell the difference between a capability that is missing because it failed a gate and one that is missing because nobody thought of it.

Response: application/json · self-describing reference document; no published envelope schema

GET /api/errors.json Available Stable No auth

The public error taxonomy, with which codes are emitted today.

Fixed now so clients can be written against it before any dynamic endpoint exists, and so the shape cannot be invented differently later under pressure.

Response: application/json · self-describing reference document; no published envelope schema

GET /api/schema/{name}.schema.json Available Stable No auth

A published JSON Schema.

Every response envelope on this surface is validated against its schema during the build, so these are enforced contracts rather than documentation.

Path parameters

Name	In	Meaning
`name`	path	Schema name without the .schema.json suffix. The full list is at /developers/api/schemas.

Response: application/schema+json · self-describing reference document; no published envelope schema
Example: /api/schema/claim.schema.json

GET /developers/openapi.json Available Stable No auth

OpenAPI 3.1 description of this surface.

Generated from this registry in the same build that emits the routes, and tested against the actual route inventory in both directions.

Response: application/json · self-describing reference document; no published envelope schema

GET /api/operation-contract.json Available Experimental No auth

The future machine-operation contract, as data.

Describes the authority ladder, operation states and stop reasons a machine actor would face if authority were ever delegated. It is a specification, not an endpoint that accepts operations.

Response: application/json · self-describing reference document; no published envelope schema

live is false and delegations_issued is 0. Nothing on this site accepts an operation envelope over the network, and there is no control endpoint.
A client must not treat this document as evidence that autonomous operation exists.

Demonstration fixtures Available

The worked fixture claim and everything attached to it. Not science.

Authority: None whatsoever. Every document here carries classification DEMO_FIXTURE and a plain-words notice. A client reading only the scientific endpoints can never receive one of these.

Authentication: none. This family contains only fixtures, and every document in it is classified DEMO_FIXTURE.

GET /api/demo/claims.json Available Stable No auth

Fixture claim identities.

The same shape as the scientific index, so a client can be exercised end to end against fixtures before any real record exists.

Response: application/json · claim-index schema (enforced at build time)

Distinguished from the scientific index by classification: DEMO_FIXTURE and by path, not by content inspection.

GET /api/demo/claims/{slug}.json Available Stable No auth

Every version of one fixture claim identity.

The full history, oldest first. Supersession and withdrawal never remove a version from it.

Path parameters

Name	In	Meaning
`slug`	path	Claim identity without the claim/ prefix, e.g. demo-0001.

Response: application/json · claim-history schema (enforced at build time)
Example: /api/demo/claims/demo-0001.json

GET /api/demo/claims/{slug}/{version}.json Available Stable No auth

One immutable claim version, with coverage, policy decisions and semantic diff.

This is the citable object. Its bytes never change; its digest is recomputable by the client from the record it contains.

Path parameters

Name	In	Meaning
`slug`	path	Claim identity without the claim/ prefix.
`version`	path	Exact version, e.g. v2. There is no 'latest' alias by design — a client that wants the current state reads the history document and follows current_version.

Response: application/json · claim-view schema (enforced at build time)
Example: /api/demo/claims/demo-0001/v2.json

A withdrawn or superseded version still returns 200 with its original bytes. The lifecycle field, not the status code, carries the scientific state.
This is deliberate: a citation must resolve to what was read. Returning 404 or 410 for withdrawn science would erase the record.

GET /api/demo/changes.json Available Stable No auth

Semantic change history for the fixture claim.

Shows what a real scientific change feed will look like, including the withdrawal.

Response: application/json · changes schema (enforced at build time)

GET /api/demo/queries/{name}.json Available Stable No auth

The answer to one bounded, named scientific question.

The questions a scientific reader actually asks, precomputed. No query language, no execution surface, no complexity budget to tune, and the answers keep working offline.

Path parameters

Name	In	Meaning
`name`	path	One of: lacking-independent-replication, open-evidence-debt, unmeasurable, depends-on, withdrawal-impact, changed-since.

Response: application/json · query-result schema (enforced at build time)
Example: /api/demo/queries/lacking-independent-replication.json

GET /demo/bundles/{slug}-{version}.json Available Stable No auth

A portable, self-describing scientific record.

Record, digest, citation, artifact manifest and verification recipe in one file, intended to survive this website.

Path parameters

Name	In	Meaning
`slug`	path	Claim identity without the claim/ prefix.
`version`	path	Exact version, e.g. v2.

Response: application/json · bundle schema (enforced at build time)
Example: /demo/bundles/demo-0001-v2.json

Carries status_at_bundle_time. A client holding an old bundle must re-fetch the version URL to learn what happened since.

GET /demo/artifacts/{file} Available Stable No auth

Raw evidence bytes, served verbatim.

The files whose digests appear in claim records and bundles. Fetch, hash, compare.

Path parameters

Name	In	Meaning
`file`	path	A flat file name. Artifact paths permit no separators and no parent references.

Response: */* · self-describing reference document; no published envelope schema
Example: /demo/artifacts/demo-a-input.csv

Integrity and crawler documents Available

The build manifest and the crawler-facing documents.

Authority: The manifest establishes which bytes this build produced. It establishes nothing scientific.

Authentication: none. Fixtures never appear in this family.

GET /build-manifest.txt Available Stable No auth

SHA-256 of every file this build wrote, except itself.

Lets a client verify that what it received is what was published, across the whole site at once, without fetching each file's digest separately.

Response: text/plain · self-describing reference document; no published envelope schema

A manifest cannot contain its own digest. Everything else served from this origin appears here, and a build test enforces that.

GET /sitemap.xml Available Stable No auth

Indexable public pages. Contains no fixture URL.

Crawler discovery for the public site.

Response: application/xml · self-describing reference document; no published envelope schema

GET /robots.txt Available Stable No auth

Crawler policy. Disallows the fixture trees.

Crawler policy only.

Response: text/plain · self-describing reference document; no published envelope schema

This is not API access policy. It governs indexing, not access, and nothing on this surface is gated by it.

GET /llms.txt Available Experimental No auth

A short orientation document for language-model clients.

States what this site is, what is empty by design, which surfaces are fixtures, and the reasoning limits that apply — so a model summarising the site is less likely to present a fixture or a withdrawn claim as a finding.

Response: text/plain · self-describing reference document; no published envelope schema

Grounded entirely in published public material. It grants no authority and adds no capability.

Resources and capabilities Available

Typed records for everything Tiffany offers or will offer, the capabilities they enable, and the published architecture.

Authority: These describe software and availability. Nothing here carries scientific standing, and a resource being available says nothing about whether any claim is supported.

Authentication: none. Fixtures never appear in this family.

GET /api/resources.json Available Stable No auth

Every public resource record.

Availability, access, release state and scientific status are four separate fields. A client must not merge them: they answer different questions and frequently disagree.

Response: application/json · resource-index schema (enforced at build time)

A field whose answer is not publicly established is absent, not null and not false. Absent means unknown.

GET /api/resources/{id}.json Available Stable No auth

One resource record.

The same record the human page is rendered from, in the same build pass, so the two cannot disagree.

Path parameters

Name	In	Meaning
`id`	path	Stable resource identity, e.g. laboratory, public-api, rci.

Response: application/json · portal-resource schema (enforced at build time)
Example: /api/resources/laboratory.json

The canonical input contract. A null field means unknown and is never filled with prose; the ingestion gate refuses a record that asserts capability, availability or release without the object that would justify it.

GET /api/capabilities.json Available Stable No auth

What can be done today, and what cannot.

Each capability carries its own availability and names the resource that provides it. Capabilities that do not exist are listed so their absence is explicit rather than inferred from silence.

Response: application/json · self-describing reference document; no published envelope schema

GET /api/architecture.json Available Stable No auth

The published publication architecture and the private-to-public boundary.

Nodes, edges, invariants and boundary stages. Tiffany's own architecture is not included, because it has not been released.

Response: application/json · self-describing reference document; no published envelope schema

The awaiting-publication entry is present and explicitly empty rather than omitted, so a client can tell a withheld architecture from a forgotten one.

Conventions that apply everywhere

Method. GET and HEAD only. Nothing accepts a body, because nothing mutates state.
Pagination. None. Every collection is small enough to return whole, and a paginated view of a scientific index invites a client to act on a partial answer. When a collection outgrows this, pagination arrives as a cursor and a contract-version change, never silently.
Filtering and sorting. None. The questions worth asking are answered as bounded named queries with their reasoning attached.
Caching. Cache-Control: public, max-age=0, must-revalidate everywhere. Version URLs are immutable and could be cached forever; they are not, so that a withdrawal reaches readers promptly. Correctness about scientific state is worth more here than a cache hit.
Status codes. 200 for a document. An address that was never issued is resolved by the hosting layer, not by a Tiffany endpoint, and returns the host's native 404 — outside Tiffany's error contract. A withdrawn or superseded record returns 200: the lifecycle field carries the scientific state, not the transport.
Deprecation. Announced in the changelog, kept working for at least one contract version, with its replacement named before removal.

PreviousExamples

NextSchemas