GunSpec
Trust

How this is verified

Documentation is a set of promises: this endpoint exists, it answers this shape, this snippet runs, this plan may call it. Nothing about a documentation site makes any of that true. This page is about the machinery that does, and about how you can check it without taking our word for anything.

Why this page exists

A reader cannot tell the difference between documentation generated from a running system and documentation a model wrote about a system it never called. Both are fluent. Both look complete. One of them sends you to an endpoint that has never existed, with a sample id that was never in the catalog, under a plan that cannot reach it.

colt-1911beretta-m9mp5
Three ids this reference once printed in published examples. None of them has ever been in the catalog. A reader's first act is to paste an example, so each one taught somebody that the API was broken. That is why ids are now checked against the data that seeds production.

We know because all three happened here. The reference once described two SDK methods that did not exist and listed two error statuses where the operation declares six. Published samples named `colt-1911`, `beretta-m9` and `mp5`, none of which this catalog has ever held. A reader's first act is to paste an example, and one that names a missing record teaches them the API is broken. Every mechanism below was built after a specific failure of that kind, and each one makes its class of failure impossible rather than unlikely.

What is checked, and what each check prevents

Eight mechanisms, each one guarding a different way documentation goes wrong. They run in CI, on every push and on a nightly schedule.

  1. 01

    The reference is generated, not written

    Every endpoint page, field table, status code and access rule on the API reference is derived from the OpenAPI specification this API serves. There is no hand-written list of endpoints anywhere, so a route added or changed without being documented is not possible: the page is a view of the contract.

    Without it: a documented endpoint that 404s, or a field table describing a payload the API stopped sending.

  2. 02

    The SDK reference is generated from the SDK

    Method signatures, arguments, return types and the endpoint each method calls are read out of the published packages and joined to the specification. A method whose endpoint cannot be resolved fails the build, so a new SDK call is documented or CI stops.

    Without it: a client library and its documentation describing two different surfaces, which is how methods that do not exist get documented.

  3. 03

    Every id in every example is real

    The firearm slugs, cartridge ids, categories and vocabulary values printed in samples are checked against the catalog data that seeds production. A sample naming a record we do not hold fails the build. Relevance is checked too: a sample for "list variants" must name a record that actually has variants.

    Without it: a first call that returns 404 or an empty array, which reads as a broken API rather than a stale page.

  4. 04

    Every printed example is executed

    Every sample on this reference is run in the runtime a reader would paste it into - the cURL by curl, the TypeScript tab by node, the Python tab by a virtualenv - exactly as printed, with only the key filled in. The SDK samples are installed from the registry into a fresh project and run the same way. Nightly, and after every release.

    Without it: a snippet that compiled once, published forever, and stopped working the day an argument changed.

  5. 05

    Every sample that cannot be executed is still checked

    The Unity, Unreal and GDScript tabs are fragments meant to be dropped into a class, an actor or a scene, so there is no way to run one without wrapping it in code this site never printed - and a badge over a wrapper we wrote would be worth less than none. Instead each is checked against the endpoint it is printed under: it must call that path, and carry a key wherever the endpoint requires one. That result is published beside the executed ones.

    Without it: a hand-written engine sample left pointing at a path that was renamed, sitting there wrong indefinitely because nothing ever called it.

  6. 06

    Every operation is held against the document

    A suite calls every documented operation against production and checks the status, the media type, the response schema, the envelope, the fields promised against the fields sent, and the caching contract. An operation that answers something the document does not describe is a failure, not a footnote.

    Without it: a deploy that quietly changed a payload, with a reference that still describes last month's shape.

  7. 07

    The plan gates are proven in both directions

    Each gated endpoint is called three ways: with no key at all, with a key of the plan the reference names, and with a key one plan below it. The first two must be refused and admitted; the third must be refused with `PLAN_REQUIRED`.

    Without it: a paid endpoint quietly serving a cheaper plan. Every other check passes over it, since the body is valid and the status documented, and nobody reports getting more than they paid for.

  8. 08

    Every figure is derived

    Catalog counts, endpoint totals, SDK versions, rate limits, prices and plan names are generated from the systems that own them: the database, the specification, the package manifests, the billing config. Copy interpolates them; nobody types them.

    Without it: six different firearm counts on six pages, and a pricing table that disagrees with the invoice.

  9. 09

    The data says where it came from

    Records carry the pages they were compiled from, a confidence figure, and which fields a source actually stated. Source strength is classified from a published list, so "four independent sources" cannot mean four retailers repeating one maker's figure.

    Without it: a specification database that cannot tell you why it believes a number, which is indistinguishable from one that made it up.

The evidence, in full

Each run is published as it happened: passes, failures and the checks that could not be made. A page that could only ever be green would be a graphic, not evidence.

Endpoint healthEvery documented operation against the live API, with the plan gates proven per endpoint.Command verificationEvery cURL, TypeScript and Python sample on this reference, executed exactly as printed.SDK example verificationEvery SDK example, run from the published package in a fresh project.Data confidenceHow completely a record is specified, how well it is sourced, and what that figure does not mean.

For agents and the people who deploy them

An agent reading an API reference cannot tell a verified page from a plausible one, and it will not hesitate before calling what it read. That makes unverified documentation an operational risk rather than a quality problem: the failure arrives inside somebody's product, at runtime, in a tool call nobody reviewed.

So the evidence is machine-readable and keyless. The same runs this page links to are served as JSON, alongside `llms.txt` and instruction packs for the common coding agents. An agent can check whether the example it is about to run passed last night, before running it, and so can the person who deployed the agent.

Check it yourself
bash
# Every documented operation, held against this reference, with the plan gatescurl --request GET \  --url 'https://api.gunspec.io/v1/contract' # Whether the printed examples still run: all three reference tabs and both SDKscurl --request GET \  --url 'https://api.gunspec.io/v1/examples/verification'

What this does not claim

A guarantee that overstates itself is worth less than a narrow one that holds. Four things these runs deliberately do not prove:

  1. 01

    Writes are not run.

    Examples that would write are not run against production, because a support ticket or a seller listing created nightly is a real record somebody has to clean up. They are published as "not run" with the reason, and never counted as passes.

  2. 02

    The game-engine tabs are not executed.

    The Unity, Unreal and GDScript samples are illustrations, not programs: each is a fragment meant to be dropped into a class, an actor or a scene, so there is nothing to run without wrapping it in code this site did not print. What is checked is that each one calls the same endpoint an executed sample covers, and carries a key wherever the endpoint requires one. Whether the engine binding around it still compiles depends on a Unity or Unreal release rather than on this API, and nothing here claims to answer it.

  3. 03

    A run proves a moment.

    A run proves what was true when it ran. Each page shows when that was, so a stale result reads as stale rather than as a current pass.

  4. 04

    Behaving as documented is not being correct.

    These checks prove the API behaves as documented. Whether a barrel length is correct is a separate question, answered by the confidence and provenance on each record and by accuracy benchmarking that is still in progress.

  5. 05

    This is our own CI.

    This is our own CI reporting on our own API. It is published in full, with failures and the commit it ran from, so the claim can be checked rather than believed. It is not a third-party audit and we do not describe it as one.

If you find something on these pages that is not true, that is a bug worth reporting, and the run that should have caught it is a bug too. Both are worth hearing about.