Head to Head
Returns a per-stat verdict between exactly two firearms, plus the win/loss/draw tally across all compared stats.
- stringheaderrequired
Your API key.
Authorization: Bearer <key>is accepted in its place.
- stringrequired
First firearm slug
- Max length
- 255
- Example
- stringrequired
Second firearm slug
- Max length
- 255
- Example
- object
The response payload.
- HeadToHeadFirearm
One of the two compared firearms, as selected: the sixteen columns the verdicts are computed from, snake_case, under their database names.
- string
URL-safe slug identifying the firearm. Stable: it is what a mirror keys on.
- string
Display name, as the maker writes it.
- string | null
Slug of the manufacturer.
manufacturerIdon the camelCase endpoints. - string | null
Slug of the category.
categoryIdon the camelCase endpoints. - number | null
Unloaded weight in grams, without magazine.
- number | null
Overall length in millimetres.
- number | null
Barrel length in millimetres, measured from the breech face.
- integer | null
Standard magazine capacity, in rounds.
- number | null
Muzzle velocity in metres per second, with the reference load.
- number | null
Muzzle energy in joules, with the reference load.
- number | null
Effective range in metres.
- number | null
Cyclic rate of fire in rounds per minute; null for a semi-automatic or manual action.
- HeadToHeadFirearm
One of the two compared firearms, as selected: the sixteen columns the verdicts are computed from, snake_case, under their database names.
- string
URL-safe slug identifying the firearm. Stable: it is what a mirror keys on.
- string
Display name, as the maker writes it.
- string | null
Slug of the manufacturer.
manufacturerIdon the camelCase endpoints. - string | null
Slug of the category.
categoryIdon the camelCase endpoints. - number | null
Unloaded weight in grams, without magazine.
- number | null
Overall length in millimetres.
- number | null
Barrel length in millimetres, measured from the breech face.
- integer | null
Standard magazine capacity, in rounds.
- number | null
Muzzle velocity in metres per second, with the reference load.
- number | null
Muzzle energy in joules, with the reference load.
- number | null
Effective range in metres.
- number | null
Cyclic rate of fire in rounds per minute; null for a semi-automatic or manual action.
- object
One verdict per compared stat, keyed by the stat's camelCase name (
weightEmptyG,overallLengthMm,barrelLengthMm,magazineCapacity,muzzleVelocityMps,muzzleEnergyJ,effectiveRangeM,rateOfFireRpm). A stat neither firearm carries is omitted, so the key set is the stats that could be compared.
- 400
VALIDATION_ERRORValidation error - 401
UNAUTHORIZEDAPI key required - 403
FORBIDDENValid key, not permitted - 404
NOT_FOUNDResource not found - 429
RATE_LIMITEDRate limit exceeded - 500
INTERNAL_ERRORUnexpected server error
Requires Builder tier or higher.
verdicts is an object keyed by the camelCase stat name (weightEmptyG, magazineCapacity ...), not an array. Each entry carries winner (a, b or draw), both values, and better, which says what winning means for that stat (lighter, longer, higher ...).
A stat neither firearm carries is omitted; a firearm that carries a value beats one that does not.
a and b are the sixteen columns the verdicts are computed from, under their snake_case database names, the same rule as /v1/firearms/search.
- 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.