Platform answers

Other short answers

The rest of the questions that have a one-line answer and no page of their own.

GraphQL, gRPC and other protocols

There is no GraphQL endpoint and no gRPC service, and none is planned. GunSpec is REST over JSON with an OpenAPI document at /openapi.json, which is what generates the two official SDKs and what every client generator, Postman, Insomnia or Bruno reads. If you want a typed client in a language we do not publish, generate it from that document rather than writing one.

Timestamps, units and content types

Three formatting questions with the same answer: it is explicit, and it never depends on who is asking.

• Timestamps are ISO 8601 with a UTC offset, always UTC, never localised. Daily quota counters reset at midnight UTC, which is what an alarm should be scheduled against.
• Units are carried by the field name (millimetres, grams, metres per second, joules), so barrelLengthMm is millimetres for every reader. Nothing is imperial and nothing is converted server-side. The field reference lists every suffix.
• Content types are JSON for records, image/svg+xml for silhouettes and bullet diagrams, model/gltf-binary for 3D models, and a 302 redirect for the seller click tracker.
• Money is integer minor units plus an ISO 4217 code, never a float. Format with Intl.NumberFormat at render and divide by nothing beforehand.

CORS, and calling the API from a browser

Two separate reasons, either one decisive. CORS only reflects gunspec.io origins in production, so a fetch from your own site is refused by the browser before we ever see it. A key in client code is also a published key, which keys in production covers. Call from your server.

• Build a thin server route that holds the key and allow-lists the paths you proxy, then call that from the browser.
• The headers a browser can read are X-Request-Id, Retry-After and the daily allowance trio X-Daily-Limit, X-Daily-Remaining and X-Daily-Reset. There is no per-minute remaining figure, because the edge limiter does not report one.
• Preflights are cached for ten minutes, so a proxy that sets a custom header is not paying for an OPTIONS on every call.

Environments: one, plus your own

There is no sandbox host, and that is deliberate: a sandbox is a second dataset to keep true, and a fake catalog teaches an integration nothing about the real one.

• Develop against production with a free Explorer key. It is read-only data, so the worst case is a wasted request; authentication explains what a key unlocks.
• Use a separate key per environment so a staging incident is a staging key, and so the usage breakdown tells you which environment is spending.
• Nothing you can call changes the catalog. The only writes in the public API are on your own account: webhook endpoints, support tickets, data reports and favourites.
• Test your webhook handler against the test delivery rather than waiting for a catalog change.

Uptime, the status page and the SLA

Two probes and a public record. /health says the worker is answering; /ready says it can reach the database. Neither needs a key or counts against your quota. The status page at status.gunspec.io carries the public uptime history, and endpoint health shows the last verification run against every operation. A contractual SLA comes with an Enterprise agreement; the published figures are what those pages report.

1# Liveness: is the worker up. No key, no quota, no database read.2curl -sS https://api.gunspec.io/health3 4# Readiness: is it up *and* can it reach the database.5curl -sS https://api.gunspec.io/ready6 7# Every response carries the id we can trace it by.8curl -sS -D - -o /dev/null https://api.gunspec.io/v1/firearms/glock-g17 \9  -H "X-API-Key: $GUNSPEC_API_KEY" | grep -i '^x-request-id:'

Catalog size: how many firearms the database holds

How many records the database holds, counted at the last docs build. GET /v1/stats/summary answers the same question live, and the statistics endpoints break the catalog down by era, material, country and action type.

Mean record confidence is 74%. It is a completeness and provenance measure for the record as a whole, not a per-figure accuracy score.

Bulk access

There is no dump to download. A mirror built through the API is supported and documented in mirroring the catalog. Systematic scraping designed to replicate the database is not, and that line is drawn in the Terms. For volume beyond the published plans, write to support@gunspec.io; that is what the enterprise tier is for.