{ "openapi": "3.1.0", "info": { "title": "tiffany.systems public API", "version": "2026-09-10", "summary": "Public, unauthenticated, read-only access to scientific records and the vocabulary that gives them meaning.", "description": "Every endpoint here is a static document generated at build time. There is no request-time computation, no database and no authenticated surface.\n\nTwo rules govern how a client may read these responses:\n\n1. Reaching an endpoint establishes nothing scientific. Availability is not validity, and a digest that verifies proves only that you received the bytes that were published.\n2. A status is a vector, not a score. Resolve every status term through /api/ontology.json rather than pattern-matching strings, and never collapse the dimensions into a single number — they disagree with each other, and the disagreement is the information.\n\nScientific endpoints are empty by design until a finding completes release review. Demonstration fixtures are segregated under /api/demo and /demo, carry classification DEMO_FIXTURE, and never appear in a scientific endpoint.\n\nErrors: Tiffany's JSON error contract governs errors returned by implemented Tiffany API endpoints. A request to an unknown or nonexistent path never reaches one — it is handled by the hosting layer and may return the host's native 404 response rather than Tiffany's envelope. Treat any non-200 as an error and do not assume the body is JSON.", "license": { "name": "CC BY 4.0", "url": "https://tiffany.systems/licenses" } }, "servers": [ { "url": "https://tiffany.systems" } ], "tags": [ { "name": "scientific", "description": "Scientific records — Published scientific claims and the record of how their standing has changed. Empty by design today: nothing has completed the release process." }, { "name": "reference", "description": "Reference documents — The vocabulary, the publication rules, the schemas, the operational status and the ledger of what was deliberately not built." }, { "name": "demonstration", "description": "Demonstration fixtures — The worked fixture claim and everything attached to it. Not science." }, { "name": "integrity", "description": "Integrity and crawler documents — The build manifest and the crawler-facing documents." }, { "name": "resources", "description": "Resources and capabilities — Typed records for everything Tiffany offers or will offer, the capabilities they enable, and the published architecture." } ], "paths": { "/api/claims.json": { "get": { "tags": [ "scientific" ], "summary": "Every published scientific claim identity.", "description": "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.\n\n- count is 0 today and the note field says why. An empty result is the correct answer, not an outage.\n- 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.", "operationId": "api_claims_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/claim-index.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-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." } }, "/api/changes.json": { "get": { "tags": [ "scientific" ], "summary": "Scientific state changes, newest first.", "description": "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.\n\n- A claim becoming superseded or withdrawn appears here. It is not an API contract change and does not appear in the API changelog.", "operationId": "api_changes_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/changes.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-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." } }, "/feed.xml": { "get": { "tags": [ "scientific" ], "summary": "The same scientific state changes as an Atom feed.", "description": "For readers and aggregators that speak Atom rather than JSON. Fixtures never appear in it.\n\n- Currently carries a subtitle explaining the empty state and no entries.", "operationId": "feed_xml", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/atom+xml": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-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." } }, "/api/index.json": { "get": { "tags": [ "reference" ], "summary": "Discovery document listing every other public endpoint.", "description": "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.", "operationId": "api_index_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/api-index.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims." } }, "/api/ontology.json": { "get": { "tags": [ "reference" ], "summary": "Every status term used anywhere on the site, defined and versioned.", "description": "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.\n\n- Self-describing reference document. Its shape is stable but is not constrained by a published JSON Schema — the definitions themselves are the contract.", "operationId": "api_ontology_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims." } }, "/api/policy.json": { "get": { "tags": [ "reference" ], "summary": "The deterministic publication rules and state-machine invariants enforced at build time.", "description": "Lets a client check what a published record was required to satisfy. Generated from the running implementation, not maintained beside it.", "operationId": "api_policy_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims." } }, "/api/status.json": { "get": { "tags": [ "reference" ], "summary": "What is published, what is sealed, what is deferred, and the state of each API family.", "description": "Operational state. Nothing in it is evidence about any claim, and traffic or uptime never affects a scientific status.", "operationId": "api_status_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/status.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims." } }, "/api/deferred.json": { "get": { "tags": [ "reference" ], "summary": "Components designed and deliberately not built, each with the condition that would activate it.", "description": "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.", "operationId": "api_deferred_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims." } }, "/api/errors.json": { "get": { "tags": [ "reference" ], "summary": "The public error taxonomy, with which codes are emitted today.", "description": "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.", "operationId": "api_errors_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims." } }, "/api/schema/{name}.schema.json": { "get": { "tags": [ "reference" ], "summary": "A published JSON Schema.", "description": "Every response envelope on this surface is validated against its schema during the build, so these are enforced contracts rather than documentation.", "operationId": "api_schema_name_schema_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/schema+json": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims.", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Schema name without the .schema.json suffix. The full list is at /developers/api/schemas.", "schema": { "type": "string" } } ], "x-example-url": "https://tiffany.systems/api/schema/claim.schema.json" } }, "/developers/openapi.json": { "get": { "tags": [ "reference" ], "summary": "OpenAPI 3.1 description of this surface.", "description": "Generated from this registry in the same build that emits the routes, and tested against the actual route inventory in both directions.", "operationId": "developers_openapi_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims." } }, "/api/operation-contract.json": { "get": { "tags": [ "reference" ], "summary": "The future machine-operation contract, as data.", "description": "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.\n\n- 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.\n- A client must not treat this document as evidence that autonomous operation exists.", "operationId": "api_operation_contract_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "EXPERIMENTAL", "x-excludes-fixtures": true, "x-scientific-authority": "Definitional. These documents say what terms mean and what rules ran. They contain no scientific claims." } }, "/api/demo/claims.json": { "get": { "tags": [ "demonstration" ], "summary": "Fixture claim identities.", "description": "The same shape as the scientific index, so a client can be exercised end to end against fixtures before any real record exists.\n\n- Distinguished from the scientific index by classification: DEMO_FIXTURE and by path, not by content inspection.", "operationId": "api_demo_claims_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/claim-index.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": false, "x-scientific-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." } }, "/api/demo/claims/{slug}.json": { "get": { "tags": [ "demonstration" ], "summary": "Every version of one fixture claim identity.", "description": "The full history, oldest first. Supersession and withdrawal never remove a version from it.", "operationId": "api_demo_claims_slug_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/claim-history.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": false, "x-scientific-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.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Claim identity without the claim/ prefix, e.g. demo-0001.", "schema": { "type": "string" } } ], "x-example-url": "https://tiffany.systems/api/demo/claims/demo-0001.json" } }, "/api/demo/claims/{slug}/{version}.json": { "get": { "tags": [ "demonstration" ], "summary": "One immutable claim version, with coverage, policy decisions and semantic diff.", "description": "This is the citable object. Its bytes never change; its digest is recomputable by the client from the record it contains.\n\n- A withdrawn or superseded version still returns 200 with its original bytes. The lifecycle field, not the status code, carries the scientific state.\n- This is deliberate: a citation must resolve to what was read. Returning 404 or 410 for withdrawn science would erase the record.", "operationId": "api_demo_claims_slug_version_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/claim-view.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": false, "x-scientific-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.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Claim identity without the claim/ prefix.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "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.", "schema": { "type": "string" } } ], "x-example-url": "https://tiffany.systems/api/demo/claims/demo-0001/v2.json" } }, "/api/demo/changes.json": { "get": { "tags": [ "demonstration" ], "summary": "Semantic change history for the fixture claim.", "description": "Shows what a real scientific change feed will look like, including the withdrawal.", "operationId": "api_demo_changes_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/changes.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": false, "x-scientific-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." } }, "/api/demo/queries/{name}.json": { "get": { "tags": [ "demonstration" ], "summary": "The answer to one bounded, named scientific question.", "description": "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.", "operationId": "api_demo_queries_name_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/query-result.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": false, "x-scientific-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.", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "One of: lacking-independent-replication, open-evidence-debt, unmeasurable, depends-on, withdrawal-impact, changed-since.", "schema": { "type": "string" } } ], "x-example-url": "https://tiffany.systems/api/demo/queries/lacking-independent-replication.json" } }, "/demo/bundles/{slug}-{version}.json": { "get": { "tags": [ "demonstration" ], "summary": "A portable, self-describing scientific record.", "description": "Record, digest, citation, artifact manifest and verification recipe in one file, intended to survive this website.\n\n- Carries status_at_bundle_time. A client holding an old bundle must re-fetch the version URL to learn what happened since.", "operationId": "demo_bundles_slug_version_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/bundle.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": false, "x-scientific-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.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Claim identity without the claim/ prefix.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "Exact version, e.g. v2.", "schema": { "type": "string" } } ], "x-example-url": "https://tiffany.systems/demo/bundles/demo-0001-v2.json" } }, "/demo/artifacts/{file}": { "get": { "tags": [ "demonstration" ], "summary": "Raw evidence bytes, served verbatim.", "description": "The files whose digests appear in claim records and bundles. Fetch, hash, compare.", "operationId": "demo_artifacts_file", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/octet-stream": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": false, "x-scientific-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.", "parameters": [ { "name": "file", "in": "path", "required": true, "description": "A flat file name. Artifact paths permit no separators and no parent references.", "schema": { "type": "string" } } ], "x-example-url": "https://tiffany.systems/demo/artifacts/demo-a-input.csv" } }, "/build-manifest.txt": { "get": { "tags": [ "integrity" ], "summary": "SHA-256 of every file this build wrote, except itself.", "description": "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.\n\n- A manifest cannot contain its own digest. Everything else served from this origin appears here, and a build test enforces that.", "operationId": "build_manifest_txt", "security": [], "responses": { "200": { "description": "The document.", "content": { "text/plain": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "The manifest establishes which bytes this build produced. It establishes nothing scientific." } }, "/sitemap.xml": { "get": { "tags": [ "integrity" ], "summary": "Indexable public pages. Contains no fixture URL.", "description": "Crawler discovery for the public site.", "operationId": "sitemap_xml", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/xml": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "The manifest establishes which bytes this build produced. It establishes nothing scientific." } }, "/robots.txt": { "get": { "tags": [ "integrity" ], "summary": "Crawler policy. Disallows the fixture trees.", "description": "Crawler policy only.\n\n- This is not API access policy. It governs indexing, not access, and nothing on this surface is gated by it.", "operationId": "robots_txt", "security": [], "responses": { "200": { "description": "The document.", "content": { "text/plain": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "The manifest establishes which bytes this build produced. It establishes nothing scientific." } }, "/llms.txt": { "get": { "tags": [ "integrity" ], "summary": "A short orientation document for language-model clients.", "description": "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.\n\n- Grounded entirely in published public material. It grants no authority and adds no capability.", "operationId": "llms_txt", "security": [], "responses": { "200": { "description": "The document.", "content": { "text/plain": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "EXPERIMENTAL", "x-excludes-fixtures": true, "x-scientific-authority": "The manifest establishes which bytes this build produced. It establishes nothing scientific." } }, "/api/resources.json": { "get": { "tags": [ "resources" ], "summary": "Every public resource record.", "description": "Availability, access, release state and scientific status are four separate fields. A client must not merge them: they answer different questions and frequently disagree.\n\n- A field whose answer is not publicly established is absent, not null and not false. Absent means unknown.", "operationId": "api_resources_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/resource-index.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "These describe software and availability. Nothing here carries scientific standing, and a resource being available says nothing about whether any claim is supported." } }, "/api/resources/{id}.json": { "get": { "tags": [ "resources" ], "summary": "One resource record.", "description": "The same record the human page is rendered from, in the same build pass, so the two cannot disagree.\n\n- 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.", "operationId": "api_resources_id_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "https://tiffany.systems/api/schema/portal-resource.schema.json" } } } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "These describe software and availability. Nothing here carries scientific standing, and a resource being available says nothing about whether any claim is supported.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Stable resource identity, e.g. laboratory, public-api, rci.", "schema": { "type": "string" } } ], "x-example-url": "https://tiffany.systems/api/resources/laboratory.json" } }, "/api/capabilities.json": { "get": { "tags": [ "resources" ], "summary": "What can be done today, and what cannot.", "description": "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.", "operationId": "api_capabilities_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "These describe software and availability. Nothing here carries scientific standing, and a resource being available says nothing about whether any claim is supported." } }, "/api/architecture.json": { "get": { "tags": [ "resources" ], "summary": "The published publication architecture and the private-to-public boundary.", "description": "Nodes, edges, invariants and boundary stages. Tiffany's own architecture is not included, because it has not been released.\n\n- The awaiting-publication entry is present and explicitly empty rather than omitted, so a client can tell a withheld architecture from a forgotten one.", "operationId": "api_architecture_json", "security": [], "responses": { "200": { "description": "The document.", "content": { "application/json": {} } }, "404": { "description": "Handled by the hosting layer, not by a Tiffany endpoint, and therefore outside Tiffany's JSON error contract. The body may be the host's native response and must not be assumed to be JSON. See /developers/api/errors.", "content": {} } }, "x-status": "AVAILABLE", "x-stability": "STABLE", "x-excludes-fixtures": true, "x-scientific-authority": "These describe software and availability. Nothing here carries scientific standing, and a resource being available says nothing about whether any claim is supported." } } }, "components": { "securitySchemes": {} }, "x-contract-version": "2026-09-10", "x-planned": [ { "id": "research-objects", "title": "Research, evidence, module, dataset and release endpoints", "status": "PLANNED", "activate_when": "The first finding, module or dataset clears release review." }, { "id": "authentication", "title": "Authentication", "status": "NOT_YET_AVAILABLE", "activate_when": "A non-public tier exists, or a write path exists." }, { "id": "api-keys", "title": "API keys", "status": "NOT_YET_AVAILABLE", "activate_when": "Authentication activates." }, { "id": "rate-limits", "title": "Rate limits", "status": "NOT_YET_AVAILABLE", "activate_when": "A request-time computed endpoint exists, or abuse makes anonymous access unworkable." }, { "id": "webhooks", "title": "Webhooks", "status": "PLANNED", "activate_when": "A consumer needs latency below the polling interval, or polling load becomes material." }, { "id": "sdks", "title": "SDKs", "status": "NOT_YET_AVAILABLE", "activate_when": "Authentication, pagination or request signing makes a correct client non-trivial to write by hand." }, { "id": "playground", "title": "Interactive playground", "status": "DEFERRED", "activate_when": "Authentication exists and constructing a correct request by hand becomes genuinely hard." }, { "id": "accounts", "title": "Developer accounts and organisations", "status": "DEFERRED", "activate_when": "Credentials exist and more than one party needs to manage them." }, { "id": "graph-query", "title": "General graph query", "status": "DEFERRED", "activate_when": "An external replicator needs a question the bounded set cannot express, twice." } ], "x-error-contract-scope": { "statement": "Tiffany's JSON error contract governs errors returned by implemented Tiffany API endpoints. A request to an unknown or nonexistent path never reaches one: it is handled by the hosting layer and may return the host's native 404 response rather than Tiffany's JSON error envelope.", "why": "Every endpoint here is a static document. It either exists, in which case it is returned, or it does not, in which case the request is resolved by the host before any Tiffany code would run. Unknown-path handling is therefore outside this contract rather than an unimplemented part of it.", "client_rule": "Treat any non-200 as an error and do not assume the body is JSON. Parse an error envelope only when an implemented endpoint returned it.", "today": "No implemented endpoint currently emits an error envelope, because a static document cannot fail in a way that produces one. The taxonomy is fixed in advance so its shape cannot be invented differently under pressure when the first endpoint that can fail is built." }, "x-error-codes": [ { "code": "not_found", "http": 404, "retryable": false, "emitted_by_implemented_endpoint": false }, { "code": "invalid_request", "http": 400, "retryable": false, "emitted_by_implemented_endpoint": false }, { "code": "validation_failed", "http": 422, "retryable": false, "emitted_by_implemented_endpoint": false }, { "code": "unsupported_version", "http": 400, "retryable": false, "emitted_by_implemented_endpoint": false }, { "code": "withdrawn_object", "http": 200, "retryable": false, "emitted_by_implemented_endpoint": false }, { "code": "superseded_object", "http": 200, "retryable": false, "emitted_by_implemented_endpoint": false }, { "code": "unauthorized", "http": 401, "retryable": false, "emitted_by_implemented_endpoint": false }, { "code": "forbidden", "http": 403, "retryable": false, "emitted_by_implemented_endpoint": false }, { "code": "rate_limited", "http": 429, "retryable": true, "emitted_by_implemented_endpoint": false }, { "code": "conflict", "http": 409, "retryable": false, "emitted_by_implemented_endpoint": false }, { "code": "unavailable", "http": 503, "retryable": true, "emitted_by_implemented_endpoint": false }, { "code": "internal_error", "http": 500, "retryable": true, "emitted_by_implemented_endpoint": false } ] }