{"openapi":"3.1.0","info":{"title":"GunSpec.io API","version":"1.0.0","description":"Comprehensive firearms specification database API.\n\n## Authentication\n\nAll `/v1` endpoints accept an API key via **`X-API-Key`** header or **`Authorization: Bearer <key>`**.\n\nSome endpoints are accessible without a key (anonymous tier), while others require a minimum subscription tier.\n\n## Pricing Tiers\n\n| Tier | Price | Requests/month | Rate Limit |\n|------|-------|----------------|------------|\n| Free | $0 | 1,000 | 10/min |\n| Indie | $19/mo | 25,000 | 60/min |\n| Pro | $49/mo | 100,000 | 120/min |\n| Enterprise | $199/mo | 1,000,000 | 600/min |\n\n## Rate Limiting\n\nResponses include rate limit headers:\n- `X-RateLimit-Limit` — Requests allowed per window\n- `X-RateLimit-Remaining` — Requests remaining\n- `X-RateLimit-Reset` — Window reset time (Unix timestamp)\n\n## Response Format\n\nAll responses follow a consistent envelope:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"pagination\": { \"page\": 1, \"limit\": 20, \"total\": 42, \"totalPages\": 3 }\n}\n```\n\nError responses:\n```json\n{\n  \"success\": false,\n  \"error\": { \"code\": \"NOT_FOUND\", \"message\": \"Firearm not found: abc\" }\n}\n```\n","contact":{"name":"GunSpec.io","url":"https://gunspec.io"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.gunspec.io","description":"Production"},{"url":"http://localhost:8787","description":"Local development"}],"tags":[{"name":"Health","description":"Health and readiness checks"},{"name":"Firearms","description":"Firearms specifications, search, comparison, and related data"},{"name":"Manufacturers","description":"Firearm manufacturers and their products"},{"name":"Calibers","description":"Ammunition calibers and cartridge specifications"},{"name":"Categories","description":"Firearm categories (pistol, rifle, shotgun, etc.)"},{"name":"Game Stats","description":"Versioned game stats snapshots. Pin your game to a specific dataset version (e.g., \"2025.1\") so rebalancing changes don't break your build mid-development. List available versions, then query firearms stats within a frozen snapshot. Requires Indie tier or higher."}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key passed via X-API-Key header"},"BearerAuth":{"type":"http","scheme":"bearer","description":"API key passed via Authorization: Bearer header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"NOT_FOUND"},"message":{"type":"string","example":"Firearm not found: unknown-id"}},"required":["code","message"]}},"required":["success","error"]},"Pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total":{"type":"integer","example":42},"totalPages":{"type":"integer","example":3}},"required":["page","limit","total","totalPages"]},"FirearmListItem":{"type":"object","properties":{"id":{"type":"string","example":"glock-17-gen5"},"name":{"type":"string","example":"Glock 17 Gen5"},"manufacturerId":{"type":"string","example":"glock"},"categoryId":{"type":"string","example":"pistol"},"yearIntroduced":{"type":"integer","nullable":true,"example":2017},"status":{"type":"string","nullable":true,"example":"in_production"},"countryOfOrigin":{"type":"string","nullable":true,"example":"AT"},"actionType":{"type":"string","nullable":true,"example":"semi-automatic"},"weightEmptyG":{"type":"number","nullable":true,"example":625},"barrelLengthMm":{"type":"number","nullable":true,"example":114}}},"FirearmDetail":{"type":"object","description":"Full firearm specification with nested relations","properties":{"id":{"type":"string","example":"glock-17-gen5"},"name":{"type":"string","example":"Glock 17 Gen5"},"manufacturerId":{"type":"string","example":"glock"},"categoryId":{"type":"string","example":"pistol"},"parentFirearmId":{"type":"string","nullable":true,"example":"glock-17"},"variantType":{"type":"string","nullable":true,"example":"generation"},"yearIntroduced":{"type":"integer","nullable":true,"example":2017},"yearDiscontinued":{"type":"integer","nullable":true},"status":{"type":"string","nullable":true,"example":"in_production"},"countryOfOrigin":{"type":"string","nullable":true,"example":"AT"},"weightEmptyG":{"type":"number","nullable":true,"example":625},"weightLoadedG":{"type":"number","nullable":true,"example":905},"overallLengthMm":{"type":"number","nullable":true,"example":204},"barrelLengthMm":{"type":"number","nullable":true,"example":114},"heightMm":{"type":"number","nullable":true,"example":139},"widthMm":{"type":"number","nullable":true,"example":34},"sightRadiusMm":{"type":"number","nullable":true,"example":165},"actionType":{"type":"string","nullable":true,"example":"semi-automatic"},"firingMechanism":{"type":"string","nullable":true,"example":"striker-fired"},"triggerType":{"type":"string","nullable":true,"example":"safe-action"},"triggerPullN":{"type":"number","nullable":true,"example":28},"magazineCapacity":{"type":"integer","nullable":true,"example":17},"magazineType":{"type":"string","nullable":true,"example":"detachable-box"},"muzzleVelocityMps":{"type":"number","nullable":true,"example":375},"muzzleEnergyJ":{"type":"number","nullable":true,"example":570},"effectiveRangeM":{"type":"number","nullable":true,"example":50},"maxRangeM":{"type":"number","nullable":true},"rateOfFireRpm":{"type":"integer","nullable":true},"barrelRifling":{"type":"string","nullable":true,"example":"polygonal"},"riflingTwistMm":{"type":"number","nullable":true,"example":250},"numberOfGrooves":{"type":"integer","nullable":true},"frameMaterial":{"type":"string","nullable":true,"example":"polymer"},"slideMaterial":{"type":"string","nullable":true,"example":"steel"},"barrelMaterial":{"type":"string","nullable":true,"example":"steel"},"stockMaterial":{"type":"string","nullable":true},"finish":{"type":"string","nullable":true,"example":"nDLC"},"safetyMechanisms":{"type":"string","nullable":true,"description":"JSON array of safety mechanisms"},"features":{"type":"string","nullable":true,"description":"JSON array of features"},"feedSystems":{"type":"string","nullable":true,"description":"JSON array of feed systems"},"gameDamage":{"type":"integer","nullable":true},"gameAccuracy":{"type":"integer","nullable":true},"gameRange":{"type":"integer","nullable":true},"gameFireRate":{"type":"integer","nullable":true},"gameMobility":{"type":"integer","nullable":true},"gameRecoilControl":{"type":"integer","nullable":true},"gameReloadSpeed":{"type":"integer","nullable":true},"gameConcealment":{"type":"integer","nullable":true},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"designer":{"type":"string","nullable":true,"description":"Person who designed the firearm","example":"Mikhail Kalashnikov"},"foldedLengthMm":{"type":"number","nullable":true,"description":"Length with stock folded (mm)","example":490},"alternateNames":{"type":"string","nullable":true,"description":"JSON array of alternate names/designations","example":"[\"Avtomat Kalashnikova\",\"Type 56\",\"Kalash\"]"},"firingModes":{"type":"string","nullable":true,"description":"JSON array of firing modes","example":"[\"semi_automatic\",\"full_automatic\"]"},"conflicts":{"type":"string","nullable":true,"description":"JSON array of conflict objects with name, years, and sides","example":"[{\"name\":\"Vietnam War\",\"years\":\"1955-1975\",\"sides\":[\"North Vietnam / Viet Cong\",\"South Vietnam / United States\"]},{\"name\":\"Soviet-Afghan War\",\"years\":\"1979-1989\",\"sides\":[\"Soviet Union\",\"Mujahideen\"]}]"},"productionNumbers":{"type":"string","nullable":true,"description":"JSON object with estimated_total, production_years, and notes","example":"{\"estimated_total\":75000000,\"production_years\":\"1947-1975\",\"notes\":\"Approximately 75 million AK-47 type rifles produced.\"}"},"lore":{"type":"string","nullable":true,"description":"Historical trivia / game-dev flavor text","example":"The AK-47 is so iconic it appears on the national flag of Mozambique."},"sources":{"type":"string","nullable":true,"description":"JSON array of source URLs"},"dataConfidence":{"type":"number","nullable":true,"example":0.95},"createdAt":{"type":"string","example":"2025-01-15 12:00:00"},"updatedAt":{"type":"string","example":"2025-01-15 12:00:00"},"manufacturer":{"$ref":"#/components/schemas/Manufacturer"},"category":{"$ref":"#/components/schemas/Category"},"calibers":{"type":"array","items":{"$ref":"#/components/schemas/FirearmCaliber"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/FirearmImage"}},"users":{"type":"array","items":{"$ref":"#/components/schemas/FirearmUser"}}}},"FirearmVariant":{"type":"object","properties":{"id":{"type":"string","example":"glock-17-gen5-mos"},"name":{"type":"string","example":"Glock 17 Gen5 MOS"},"variantType":{"type":"string","nullable":true,"example":"optics-ready"},"yearIntroduced":{"type":"integer","nullable":true,"example":2018},"status":{"type":"string","nullable":true,"example":"in_production"}}},"FirearmGameStats":{"type":"object","properties":{"id":{"type":"string","example":"glock-17-gen5"},"name":{"type":"string","example":"Glock 17 Gen5"},"gameDamage":{"type":"integer","nullable":true,"example":45},"gameAccuracy":{"type":"integer","nullable":true,"example":72},"gameRange":{"type":"integer","nullable":true,"example":35},"gameFireRate":{"type":"integer","nullable":true,"example":68},"gameMobility":{"type":"integer","nullable":true,"example":85},"gameRecoilControl":{"type":"integer","nullable":true,"example":70},"gameReloadSpeed":{"type":"integer","nullable":true,"example":75},"gameConcealment":{"type":"integer","nullable":true,"example":80}}},"FirearmImage":{"type":"object","properties":{"id":{"type":"integer","example":1},"firearmId":{"type":"string","example":"glock-17-gen5"},"url":{"type":"string","example":"https://images.gunspec.io/glock-17-gen5/main.webp"},"type":{"type":"string","nullable":true,"enum":["primary","gallery","thumbnail","svg"],"example":"gallery"},"source":{"type":"string","nullable":true,"example":"manufacturer"},"license":{"type":"string","nullable":true,"example":"fair-use"}}},"FirearmUser":{"type":"object","properties":{"id":{"type":"integer","example":1},"firearmId":{"type":"string","example":"glock-17-gen5"},"userName":{"type":"string","example":"Austrian Armed Forces"},"userType":{"type":"string","nullable":true,"example":"military"},"countryCode":{"type":"string","nullable":true,"example":"AT"},"adoptedYear":{"type":"integer","nullable":true,"example":1982},"designation":{"type":"string","nullable":true,"example":"Pistole 80"}}},"FirearmCaliber":{"type":"object","properties":{"caliberId":{"type":"string","example":"9x19mm-parabellum"},"isPrimary":{"type":"integer","example":1},"name":{"type":"string","example":"9x19mm Parabellum"},"natoDesignation":{"type":"string","nullable":true,"example":"9mm NATO"},"bulletDiameterMm":{"type":"number","nullable":true,"example":9.01},"caseLengthMm":{"type":"number","nullable":true,"example":19.15}}},"Manufacturer":{"type":"object","properties":{"id":{"type":"string","example":"glock"},"name":{"type":"string","example":"Glock Ges.m.b.H."},"countryCode":{"type":"string","nullable":true,"example":"AT"},"foundedYear":{"type":"integer","nullable":true,"example":1963},"website":{"type":"string","nullable":true,"example":"https://www.glock.com"},"logoUrl":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"createdAt":{"type":"string","example":"2025-01-15 12:00:00"},"updatedAt":{"type":"string","example":"2025-01-15 12:00:00"}}},"Caliber":{"type":"object","properties":{"id":{"type":"string","example":"9x19mm-parabellum"},"name":{"type":"string","example":"9x19mm Parabellum"},"aliases":{"type":"string","nullable":true,"description":"JSON array of aliases"},"natoDesignation":{"type":"string","nullable":true,"example":"9mm NATO"},"bulletDiameterMm":{"type":"number","nullable":true,"example":9.01},"neckDiameterMm":{"type":"number","nullable":true,"example":9.65},"baseDiameterMm":{"type":"number","nullable":true,"example":9.93},"caseLengthMm":{"type":"number","nullable":true,"example":19.15},"overallLengthMm":{"type":"number","nullable":true,"example":29.69},"maxPressureMpa":{"type":"number","nullable":true,"example":235},"maxPressurePsi":{"type":"number","nullable":true,"example":34084},"typicalBulletWeightG":{"type":"number","nullable":true,"example":7.45},"typicalMuzzleVelocityMps":{"type":"number","nullable":true,"example":360},"typicalMuzzleEnergyJ":{"type":"number","nullable":true,"example":481},"primerType":{"type":"string","nullable":true,"example":"small-pistol"},"cartridgeType":{"type":"string","nullable":true,"example":"rimless"},"parentCartridgeId":{"type":"string","nullable":true},"yearIntroduced":{"type":"integer","nullable":true,"example":1902},"designer":{"type":"string","nullable":true,"example":"Georg Luger"},"createdAt":{"type":"string","example":"2025-01-15 12:00:00"},"updatedAt":{"type":"string","example":"2025-01-15 12:00:00"}}},"Category":{"type":"object","properties":{"id":{"type":"string","example":"pistol"},"name":{"type":"string","example":"Pistol"},"description":{"type":"string","nullable":true,"example":"Handguns designed to be fired with one or two hands"}}},"ManufacturerFirearmListItem":{"type":"object","properties":{"id":{"type":"string","example":"glock-17-gen5"},"name":{"type":"string","example":"Glock 17 Gen5"},"categoryId":{"type":"string","example":"pistol"},"yearIntroduced":{"type":"integer","nullable":true,"example":2017},"status":{"type":"string","nullable":true,"example":"in_production"},"actionType":{"type":"string","nullable":true,"example":"semi-automatic"}}},"CaliberFirearmListItem":{"type":"object","properties":{"id":{"type":"string","example":"glock-17-gen5"},"name":{"type":"string","example":"Glock 17 Gen5"},"manufacturerId":{"type":"string","example":"glock"},"categoryId":{"type":"string","example":"pistol"},"yearIntroduced":{"type":"integer","nullable":true,"example":2017},"status":{"type":"string","nullable":true,"example":"in_production"},"actionType":{"type":"string","nullable":true,"example":"semi-automatic"}}},"CategoryFirearmListItem":{"type":"object","properties":{"id":{"type":"string","example":"glock-17-gen5"},"name":{"type":"string","example":"Glock 17 Gen5"},"manufacturerId":{"type":"string","example":"glock"},"yearIntroduced":{"type":"integer","nullable":true,"example":2017},"status":{"type":"string","nullable":true,"example":"in_production"},"actionType":{"type":"string","nullable":true,"example":"semi-automatic"}}},"GameStatsVersion":{"type":"object","properties":{"id":{"type":"integer","example":1},"version":{"type":"string","example":"2025.1"},"description":{"type":"string","nullable":true,"example":"Initial game stats snapshot"},"firearmCount":{"type":"integer","example":450},"createdAt":{"type":"string","example":"2025-06-01 12:00:00"}}},"GameStatsSnapshotEntry":{"type":"object","properties":{"firearm_id":{"type":"string","example":"glock-17-gen5"},"firearm_name":{"type":"string","example":"Glock 17 Gen5"},"game_damage":{"type":"integer","nullable":true,"example":42},"game_accuracy":{"type":"integer","nullable":true,"example":68},"game_range":{"type":"integer","nullable":true,"example":35},"game_fire_rate":{"type":"integer","nullable":true,"example":55},"game_mobility":{"type":"integer","nullable":true,"example":78},"game_recoil_control":{"type":"integer","nullable":true,"example":62},"game_reload_speed":{"type":"integer","nullable":true,"example":72},"game_concealment":{"type":"integer","nullable":true,"example":70}}}},"parameters":{"page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number"},"per_page":{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page (max 100)"},"sort":{"name":"sort","in":"query","schema":{"type":"string"},"description":"Sort field"},"order":{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"description":"Sort order"},"slugId":{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Resource slug ID","example":"glock-17-gen5"}},"responses":{"BadRequest":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"VALIDATION_ERROR","message":"Invalid query parameters"}}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}}}},"Forbidden":{"description":"Insufficient tier for this endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"This endpoint requires a Pro tier API key"}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NOT_FOUND","message":"Firearm not found: unknown-id"}}}}},"TooManyRequests":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded. Try again later."}}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred"}}}}}}},"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health check","description":"Returns API status, version, and environment. No authentication required.","operationId":"getHealth","responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"timestamp":{"type":"string","example":"2025-01-15T12:00:00.000Z"},"version":{"type":"string","example":"1.0.0"},"environment":{"type":"string","example":"production"}}}}}}}}},"/ready":{"get":{"tags":["Health"],"summary":"Readiness check","description":"Verifies the database connection is active. No authentication required.","operationId":"getReady","responses":{"200":{"description":"Database connected","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ready"},"database":{"type":"string","example":"connected"}}}}}},"503":{"description":"Database disconnected","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"not_ready"},"database":{"type":"string","example":"disconnected"}}}}}}}}},"/v1/firearms":{"get":{"tags":["Firearms"],"summary":"List firearms","description":"Returns a paginated list of firearms with optional filters. Auth is optional — anonymous users get default rate limits.","operationId":"listFirearms","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"},{"name":"sort","in":"query","schema":{"type":"string","enum":["name","weight","year","caliber"],"default":"name"},"description":"Sort field"},{"$ref":"#/components/parameters/order"},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated list of fields to include"},{"name":"manufacturer","in":"query","schema":{"type":"string"},"description":"Filter by manufacturer slug","example":"glock"},{"name":"caliber","in":"query","schema":{"type":"string"},"description":"Filter by caliber slug","example":"9x19mm-parabellum"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug","example":"pistol"},{"name":"action_type","in":"query","schema":{"type":"string"},"description":"Filter by action type","example":"semi-automatic"},{"name":"country_of_origin","in":"query","schema":{"type":"string"},"description":"Filter by ISO country code","example":"AT"},{"name":"year_introduced_min","in":"query","schema":{"type":"integer"},"description":"Minimum year introduced"},{"name":"year_introduced_max","in":"query","schema":{"type":"integer"},"description":"Maximum year introduced"},{"name":"weight_min","in":"query","schema":{"type":"number"},"description":"Minimum empty weight (grams)"},{"name":"weight_max","in":"query","schema":{"type":"number"},"description":"Maximum empty weight (grams)"},{"name":"barrel_length_min","in":"query","schema":{"type":"number"},"description":"Minimum barrel length (mm)"},{"name":"status","in":"query","schema":{"type":"string","enum":["in_production","discontinued","prototype"]},"description":"Filter by production status"}],"responses":{"200":{"description":"Paginated list of firearms","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/FirearmListItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/firearms/search":{"get":{"tags":["Firearms"],"summary":"Full-text search firearms","description":"Searches firearms using FTS5 full-text index. Results are ranked by relevance. Auth is optional.","operationId":"searchFirearms","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Search query","example":"glock 9mm"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"},{"$ref":"#/components/parameters/order"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/FirearmListItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/firearms/compare":{"get":{"tags":["Firearms"],"summary":"Compare firearms","description":"Returns full details for up to 5 firearms side-by-side. **Requires Pro tier or higher.**","operationId":"compareFirearms","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated firearm IDs (max 5)","example":"glock-17-gen5,sig-sauer-p320-m17,beretta-m9a3"}],"responses":{"200":{"description":"Array of full firearm details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/FirearmDetail"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/firearms/{id}":{"get":{"tags":["Firearms"],"summary":"Get firearm details","description":"Returns full specification for a single firearm, including manufacturer, category, calibers, images, and known users. Auth is optional.","operationId":"getFirearm","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/slugId"}],"responses":{"200":{"description":"Full firearm detail","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/FirearmDetail"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/firearms/{id}/variants":{"get":{"tags":["Firearms"],"summary":"Get firearm variants","description":"Lists all variants (generations, special editions, etc.) of a parent firearm. Auth is optional.","operationId":"getFirearmVariants","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/slugId"}],"responses":{"200":{"description":"List of variants","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/FirearmVariant"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/firearms/{id}/images":{"get":{"tags":["Firearms"],"summary":"Get firearm images","description":"Returns all images for a firearm. **Requires Pro tier or higher.**","operationId":"getFirearmImages","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/slugId"}],"responses":{"200":{"description":"List of images","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/FirearmImage"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/firearms/{id}/game-stats":{"get":{"tags":["Firearms"],"summary":"Get firearm game stats (live)","description":"Returns **live** game-balance stats (0–100 scale) for a single firearm. **Requires Indie tier or higher.**\n\nThese stats are derived from real-world specifications and normalized into 8 categories:\n\n| Stat | What it measures |\n|------|-----------------|\n| `gameDamage` | Muzzle energy relative to category |\n| `gameAccuracy` | Barrel length, sight radius, weight stability |\n| `gameRange` | Effective range relative to category |\n| `gameFireRate` | Rate of fire (cyclic or practical) |\n| `gameMobility` | Inverse of loaded weight |\n| `gameRecoilControl` | Weight vs muzzle energy balance |\n| `gameReloadSpeed` | Magazine type and capacity |\n| `gameConcealment` | Inverse of overall dimensions |\n\n**Important:** This endpoint always returns the **latest** values. If we rebalance stats, your game will see the changes immediately. For stability guarantees, use the **versioned snapshots** at `/v1/game-stats/versions/{version}/firearms/{id}` instead — pin to a version like `2025.1` and upgrade on your own schedule.","operationId":"getFirearmGameStats","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/slugId"}],"responses":{"200":{"description":"Game stats","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/FirearmGameStats"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/firearms/{id}/users":{"get":{"tags":["Firearms"],"summary":"Get firearm users","description":"Lists known military, law enforcement, and other users/adopters of a firearm. Auth is optional.","operationId":"getFirearmUsers","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/slugId"}],"responses":{"200":{"description":"List of users/adopters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/FirearmUser"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/manufacturers":{"get":{"tags":["Manufacturers"],"summary":"List manufacturers","description":"Returns a paginated list of firearm manufacturers. Auth is optional.","operationId":"listManufacturers","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"},{"$ref":"#/components/parameters/order"},{"name":"country","in":"query","schema":{"type":"string"},"description":"Filter by ISO country code","example":"US"}],"responses":{"200":{"description":"Paginated list of manufacturers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Manufacturer"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/manufacturers/{id}":{"get":{"tags":["Manufacturers"],"summary":"Get manufacturer details","description":"Returns full details for a single manufacturer. Auth is optional.","operationId":"getManufacturer","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/slugId"}],"responses":{"200":{"description":"Manufacturer detail","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Manufacturer"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/manufacturers/{id}/firearms":{"get":{"tags":["Manufacturers"],"summary":"List firearms by manufacturer","description":"Returns a paginated list of firearms made by a specific manufacturer. Auth is optional.","operationId":"getManufacturerFirearms","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/slugId"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"},{"$ref":"#/components/parameters/order"}],"responses":{"200":{"description":"Paginated list of firearms","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ManufacturerFirearmListItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/calibers":{"get":{"tags":["Calibers"],"summary":"List calibers","description":"Returns a paginated list of ammunition calibers. Auth is optional.","operationId":"listCalibers","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"},{"$ref":"#/components/parameters/order"},{"name":"cartridge_type","in":"query","schema":{"type":"string"},"description":"Filter by cartridge type","example":"rimless"},{"name":"primer_type","in":"query","schema":{"type":"string"},"description":"Filter by primer type","example":"small-pistol"}],"responses":{"200":{"description":"Paginated list of calibers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Caliber"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/calibers/{id}":{"get":{"tags":["Calibers"],"summary":"Get caliber details","description":"Returns full cartridge specifications for a single caliber. Auth is optional.","operationId":"getCaliber","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/slugId"}],"responses":{"200":{"description":"Caliber detail","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Caliber"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/calibers/{id}/firearms":{"get":{"tags":["Calibers"],"summary":"List firearms by caliber","description":"Returns a paginated list of firearms chambered in a specific caliber. Auth is optional.","operationId":"getCaliberFirearms","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/slugId"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"},{"$ref":"#/components/parameters/order"}],"responses":{"200":{"description":"Paginated list of firearms","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CaliberFirearmListItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/categories":{"get":{"tags":["Categories"],"summary":"List categories","description":"Returns all firearm categories. Not paginated. Auth is optional.","operationId":"listCategories","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/categories/{slug}/firearms":{"get":{"tags":["Categories"],"summary":"List firearms by category","description":"Returns a paginated list of firearms in a specific category. Auth is optional.","operationId":"getCategoryFirearms","security":[{},{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Category slug","example":"pistol"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"},{"$ref":"#/components/parameters/order"}],"responses":{"200":{"description":"Paginated list of firearms","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CategoryFirearmListItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/game-stats/versions":{"get":{"tags":["Game Stats"],"summary":"List snapshot versions","description":"Returns all available game stats snapshot versions, newest first. **Requires Indie tier or higher.**\n\nEach version represents a frozen copy of all game stats at a point in time. Use this to discover which versions are available, then query firearms within a specific version.\n\n**Workflow:**\n1. Call this endpoint to see available versions (e.g., `2025.1`, `2025.2`)\n2. Pick a version to pin your game to\n3. Fetch stats via `/v1/game-stats/versions/{version}/firearms`\n4. When ready to upgrade, switch to a newer version","operationId":"listGameStatsVersions","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"List of snapshot versions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/GameStatsVersion"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/game-stats/versions/{version}/firearms":{"get":{"tags":["Game Stats"],"summary":"List firearms in snapshot version","description":"Returns paginated game stats for **all** firearms in a specific snapshot version. **Requires Indie tier or higher.**\n\nUse this to bulk-load weapon stats into your game. Stats are frozen at the time the snapshot was created — they won't change even if we rebalance live values. Each entry includes the firearm slug, display name, and all 8 game stat values (0–100 scale).\n\nSupports standard pagination (`page`, `per_page` up to 100). Results are sorted alphabetically by firearm name.","operationId":"listGameStatsVersionFirearms","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"version","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9.\\-]*$"},"description":"Snapshot version string","example":"2025.1"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"Paginated snapshot entries","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/GameStatsSnapshotEntry"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/v1/game-stats/versions/{version}/firearms/{id}":{"get":{"tags":["Game Stats"],"summary":"Get firearm stats in snapshot version","description":"Returns game stats for a **single firearm** in a specific snapshot version. **Requires Indie tier or higher.**\n\nUse the firearm slug (e.g., `glock-17-gen5`) as the `id` parameter. Returns 404 if the firearm doesn't exist in that snapshot (it may not have had game stats when the snapshot was created).\n\nThe response includes all 8 game stat values (0–100 scale): damage, accuracy, range, fire rate, mobility, recoil control, reload speed, and concealment.","operationId":"getGameStatsVersionFirearm","security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}],"parameters":[{"name":"version","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9.\\-]*$"},"description":"Snapshot version string","example":"2025.1"},{"$ref":"#/components/parameters/slugId"}],"responses":{"200":{"description":"Snapshot entry for a single firearm","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/GameStatsSnapshotEntry"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}