Top Firearms
Returns the firearms that lead a single measurable stat. Records missing the underlying measurement are excluded rather than ranked as zero.
- stringheaderrequired
Your API key.
Authorization: Bearer <key>is accepted in its place.
- stringrequired
Which superlative to rank by
- Accepts
- Example
- string
Restrict the ranking to a category slug
- Example
- integerdefault
10How many to return
- Range
- 1 – 25
- Example
- TopFirearm[]
The response payload.
- string
Slug of the firearm.
- string
Display name, as the maker writes it.
- string | null
Slug of the manufacturer that makes it. Resolve against
/v1/manufacturers/{id}. - string | null
Slug of the category it belongs to. Resolve against
/v1/categories. - number | null
The figure this ranking is by, in the unit of whichever statistic was requested.
- string
One of g, m, rpm, mm, rounds, J
- 400
VALIDATION_ERRORValidation error - 401
UNAUTHORIZEDAPI key required - 403
FORBIDDENValid key, not permitted - 429
RATE_LIMITEDRate limit exceeded - 500
INTERNAL_ERRORUnexpected server error
Requires Builder tier or higher.
Valid stats: lightest, heaviest, longest-range, highest-rof, most-compact, highest-capacity, most-powerful.
The value field unit depends on the stat (grams for weight, meters for range, RPM for ROF, rounds for capacity, joules for power).
- Minimum tier
- Builder+
- Monthly quota
- 25,000/mo
- Rate limit
- 60/min
- Daily cap
- 2,000
Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.
This read answers conditional requests. Keep the ETag from a response and send it back as If-None-Match: an unchanged record returns 304 Not Modified with no body, which counts toward your per-minute rate limit but not your daily allowance.