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, draw, or unknown when only one firearm states the stat), both values, and better, which says what winning means for that stat (lighter, longer, higher ...).
A stat neither firearm carries is omitted. A stat only one carries is unknown: a missing figure is a gap in the catalogue, not a loss, so no winner is named.
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
- 5,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.