Environments & schema identity

Base URLs

Both appear in the server selector at the top of the API reference. Production is the default; pick Preview while you are integrating.

Everything on this site describes one API surface. It is the same contract on both bases — but the two do not deploy at the same moment, so at any given time one of them may be a build ahead of the other. The rest of this page is how you tell.

The problem

The reference you are reading is a committed artifact. It is generated from the API source and published with the docs site; it is never scraped from a running API. The API you are calling is a deployment. Those two things move on their own schedules.

So "the docs redeployed but the endpoint I care about looks unchanged" is genuinely ambiguous from the outside: it might mean the change was somewhere else, or it might mean you are reading a build that is not the one answering your requests. Before schema identity there was no public way to tell those apart — info.version read 0.0.1 (a package placeholder that never moved), and public health returned only a status and a timestamp.

Schema identity

Every generated copy of the reference carries a schema digest — a SHA-256 content hash of the document itself, in the form sha256:<64 hex characters>. The running API publishes the digest of the document it was built from. If the two strings are equal, that runtime was built from the same public API surface this reference was generated from.

The digest is opaque. It is a fingerprint, not a version number: it has no ordering, so two different digests tell you the reference and the runtime are out of step, but not which one is newer.

How to compare

1. Ask the runtime. The endpoint is public — no API key, no session, no x-organization-slug:

curl https://api.preview.litecommerce.io/api/v1/public/api-schema

{
  "schemaDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
}

That value is a placeholder — a real response carries 64 hex characters of actual digest. Swap the host for https://api.litecommerce.io to check Production.

2. Fetch the reference. The same vendored document rendered by the API reference is available as JSON at /api-reference/openapi.json. Its info.version is the reference digest:

curl -fsS https://docs.litecommerce.io/api-reference/openapi.json \
  | jq -er '.info.version'

The version badge beside the rendered reference title shows the same value. The response sends Cache-Control: no-store, so conforming caches do not retain it across docs deployments and produce a false match after the runtime has moved.

3. Compare the two strings verbatim.

• Equal → the reference you are reading was generated from the same public API surface the runtime was built from. Build against it.
• Different → the reference and that deployment are out of step. Re-check in a few minutes: a deploy may be mid-flight. If it persists, treat the runtime as authoritative for behavior, and raise it with us rather than guessing which side is stale.

Compare against the base you are actually calling. A digest read from Preview says nothing about Production, and vice versa.

For example, this assertion fails a CI job when the published reference and Preview runtime describe different contracts:

reference_digest="$(
  curl -fsS https://docs.litecommerce.io/api-reference/openapi.json \
    | jq -er '.info.version'
)"
runtime_digest="$(
  curl -fsS https://api.preview.litecommerce.io/api/v1/public/api-schema \
    | jq -er '.schemaDigest'
)"
 
test "$reference_digest" = "$runtime_digest"

What equality does not tell you

Equality is a statement about build provenance, not about which routes a given deployment has switched on. The reference describes the API surface, not any one environment's configuration, so a route family that is gated behind deployment configuration is documented here whether or not a particular runtime has it mounted. Such an endpoint can answer 404 on a runtime whose digest matches this reference, and that is not a mismatch.

Today this applies to exactly one family: /api/v1/support-provider/*, the provider-to-litecommerce callout surface, which stays unmounted until an operator enables it. Every public, customer, merchant, storefront, and import route in this reference is mounted wherever the API runs. If some other documented endpoint returns 404 against a matching digest, that is not expected — raise it with us.

What the digest covers

It is computed over the whole generated OpenAPI document — paths, operations, parameters, request and response schemas, security schemes, tags, and the rest of info — with exactly two exclusions:

• servers — the base URL list is publication detail, rewritten per environment. Excluding it is what lets one digest describe the contract on both bases.
• info.version — the digest's own field.

Two normalizations keep it honest, so it moves on real changes and only on real changes: object keys are sorted before hashing (key order carries no meaning in JSON), and parameters lists are sorted (OpenAPI defines them as a set, unique by name and location). Everything else, including the order of required and enum entries, is significant.

So: a new endpoint, a renamed field, a changed type, a dropped security requirement, an added response code, or an edited operation summary all move the digest. Adding a base URL to the server list does not.

info.version is not a release version

info.version in this API's OpenAPI document is the schema digest. It is not semver, not a release number, and it is not comparable — do not parse it, sort by it, or gate behavior on it. Its only supported use is the equality check above.

It used to be 0.0.1, which was the API package's placeholder version and never changed. If you have logic reading that value as a version signal, it is reading noise; replace it with the comparison on this page.

The API's versioning boundary is the /api/v1 path prefix, not this field.

Related

• API reference — the rendered document the digest identifies
• OpenAPI JSON — the same document for automated checks
• Tenants & context — the headers every tenant-scoped call needs
• Storefront integration — building against the API