Frequently Asked Questions

Our database currently contains — base firearms with over — variants, covering — calibers from — manufacturers across — countries. We continuously expand the database with new entries and update existing records as new information becomes available.

We run regular data refresh cycles to capture updated specifications, new production variants, and corrections. New firearms are added on an ongoing basis. Major updates (new fields, schema changes) are documented in our changelog. The data pipeline automatically cross-references multiple sources to keep information current.

Game studios building weapon systems with realistic stats, military training simulator companies, firearm collector and inventory apps, e-commerce platforms needing product data, educational and reference applications, and research institutions studying firearms trends.

The Explorer tier (200 requests/month) effectively serves as a sandbox. You can sign up for free, get an API key immediately, and test public endpoints with real production data. There's no separate staging environment — the Explorer tier gives you access to the same data as paid tiers, just with lower rate limits and fewer endpoints.

We provide a TypeScript SDK with full type safety via Hono RPC. For other languages, our OpenAPI 3.1 specification (available at /openapi.json) can be used to auto-generate clients in Python, Go, Ruby, Java, C#, and more using tools like openapi-generator or Speakeasy. Our API follows standard REST conventions making it straightforward to consume from any HTTP client.

Authentication uses API keys passed in the X-API-Key header. All endpoints require a valid API key. Create an account, generate a free Explorer key from your dashboard, and include it in every request. Higher tiers unlock additional endpoints like search, compare, game stats, and data quality.

All responses are JSON. Successful responses include a data field with the payload. List endpoints return paginated results with page, limit, and total fields. Error responses include a structured error object with code, message, and details. We follow consistent response envelopes across all endpoints.

GunSpec runs on Cloudflare Workers, which provides edge computing across 300+ data centers worldwide. This architecture delivers sub-50ms response times globally and 99.9%+ uptime. There's no single point of failure — requests are automatically routed to the nearest healthy data center.

We aggregate data from manufacturer specification sheets, military procurement documents, independent ballistic testing databases, reputable firearms reference publications, and government technical manuals. Each firearm is cross-referenced against multiple independent sources. Source URLs are tracked per entry.

Our average confidence score across the database is —%. Well-documented firearms like the HK416 (95%) or Glock 19 Gen5 (93%) have near-complete data verified against 4+ sources. Less common models may have gaps. We're transparent about completeness — every entry shows its confidence score so you can assess fitness for your use case.

Null fields are explicitly returned as null rather than omitted or zero-filled, so you can distinguish 'unknown' from 'zero'. If you find incorrect data, contact us and we'll investigate. Enterprise tier users can access the /v1/data/coverage and /v1/data/confidence endpoints to programmatically identify gaps.

Yes, you can change your plan at any time from your dashboard. Upgrades take effect immediately with prorated billing. Downgrades take effect at the next billing cycle. Your API key stays the same — only the rate limits and endpoint access change.

Enterprise ($249/mo) includes 1,000,000 requests/month, 300 requests/min rate limit, data quality endpoints (/v1/data/coverage and /v1/data/confidence), dedicated support, and a custom SLA. It's designed for teams building production applications that depend on GunSpec data.

We accept all major credit cards (Visa, Mastercard, Amex) and process payments securely through Stripe. Invoices are available from your dashboard. Enterprise customers can request annual billing with net-30 terms.

Game stats reflect real-world performance characteristics, not arbitrary game balance. A .50 BMG sniper rifle genuinely hits harder than a 9mm pistol. However, the normalization ensures values stay within usable 0–100 ranges. Studios typically apply their own balance multipliers on top of our base values. The Studio tier /v1/game/balance-report endpoint flags statistical outliers.

Snapshots are versioned, frozen copies of game stats (e.g., v2026.1). When we recalculate stats from updated specifications, existing snapshots don't change. This lets game studios ship a version and know the values won't shift under their live game. New snapshots are published periodically. Available at /v1/game-stats/versions.

Each firearm is classified into a gameplay archetype based on its stat profile: Sniper, Assault, CQB Specialist, Support Gunner, All-Rounder, etc. Archetypes help game designers quickly categorize weapons and ensure roster diversity. The /v1/firearms/game-meta endpoint lets you query by archetype to find firearms matching a specific gameplay role.

Attribution is appreciated but not required for paid tiers. Explorer tier usage requires a 'Powered by GunSpec' attribution link in your product. Paid tiers (Builder, Studio, Enterprise) have no attribution requirement.

Yes. All tiers, including Explorer, permit commercial use. You can build and sell products that consume GunSpec data. The tier you need depends on your request volume and which endpoints you require, not whether your product is commercial.

GunSpec processes minimal personal data (email and API key for account management). We don't track individual API usage patterns beyond rate limiting. Our infrastructure runs on Cloudflare's global network which offers EU data residency options. See our Privacy Policy for full details.