Laboratory › Developers › Quickstart

Quickstart

No key, no signup, no client library. Everything below is a plain GET you can paste into a terminal right now.

1. Discover the surface

curl -s https://tiffany.systems/api/index.json

Lists every other public document, plus the guarantees the URL scheme makes.

2. Ask for the laboratory's scientific positions

curl -s https://tiffany.systems/api/claims.json

{
  "schema": "tiffany.systems/schema/claim-index/1.0.0",
  "count": 0,
  "note": "Published scientific claims. Empty by design: no finding has completed this laboratory's release process…",
  "claims": []
}

An empty set is the correct answer today. Handle it as data, not as an error.

3. Read a claim's whole history

curl -s https://tiffany.systems/api/demo/claims/demo-0001.json

You get every version, oldest first, with current_version naming the laboratory's present position. Supersession and withdrawal never remove a version from this list.

4. Pin an exact version — this is the one you cite

curl -s https://tiffany.systems/api/demo/claims/demo-0001/v2.json

Two URLs exist for every claim and they mean different things:

There is deliberately no latest alias. An alias that silently changes what it returns is how a citation comes to point at something its author never read.

5. Detect current, superseded and withdrawn

Read record.lifecycle. Do not infer state from the HTTP status code:

curl -s https://tiffany.systems/api/demo/claims/demo-0001/v1.json | grep -o '"lifecycle": "[A-Z]*"' | head -1
# "lifecycle": "SUPERSEDED"

6. Verify what you received

# the record digest is recomputable from the record itself
curl -s https://tiffany.systems/demo/bundles/demo-0001-v2.json -o bundle.json
curl -s https://tiffany.systems/demo/artifacts/demo-a-input.csv -o demo-a-input.csv
shasum -a 256 demo-a-input.csv
# compare against manifest[].sha256 in bundle.json

This proves you hold the bytes the laboratory published. It proves nothing about whether the claim is true — see verification for the six things "verified" can mean here.

7. Errors

Tiffany's JSON error contract governs errors returned by implemented Tiffany endpoints. A request to an unknown or nonexistent path never reaches one — the hosting layer answers it and may return its own native 404, which is not our envelope and may not be JSON.

So: 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. The full taxonomy is on errors.

8. Schemas

Every envelope has a published schema at /api/schema/<name>.schema.json, and every emitted document is validated against it during the build. The list is here.

9. Authentication

There is none, and nothing here is behind one. Do not send an Authorization header; it is ignored. When authenticated endpoints exist, the contract they will honour is already written down on authentication.