Reference

Field reference

Every field a firearm record carries, with its type, unit and meaning, read from the API's OpenAPI specification so it cannot drift from what a response holds.

Response fields are camelCase (weightEmptyG); query parameters are snake_case (per_page).
Measurements use SI units. A field is null when the figure is unknown or does not apply, never 0 or an empty string.
Explorer receives a summary view; fields marked Builder+ appear on paid plans. See what each plan includes.

Firearm fields

All 78 fields on GET /v1/firearms/{id}, grouped. List endpoints return a subset.

78 fields

Identity and lineage

Who made it, what it is, and where it sits in a family of variants.

stringe.g.glock-17-gen5
URL-safe slug identifying the firearm, e.g. glock-17-gen5. Stable: it is what a mirror keys on.
stringe.g.Glock 17 Gen5
Display name, as the maker writes it.
stringe.g.glock
Slug of the manufacturer that makes it. Resolve against /v1/manufacturers/{id}.
stringe.g.pistol
Slug of the category it belongs to. Resolve against /v1/categories.
string | nullBuilder+e.g.glock-17
The firearm this one is a variant of, or null when it is not a variant. Variant relationships are what firearm.variant.updated webhooks and /v1/firearms/{id}/variants follow.
string | nullBuilder+e.g.generation
How this record differs from its parent: optics_ready, compact, threaded and so on. Null when the record has no parent.
string | nulle.g.AT
ISO 3166-1 alpha-2 code of where it was designed, e.g. AT.
string | nullBuilder+e.g.Mikhail Kalashnikov
Person or team credited with the design, where it is known.
string | nullBuilder+e.g.["Avtomat Kalashnikova","Type 56","Kalash"]
JSON array of alternate names/designations
integer | nullyeare.g.2017
Year it entered production or service. Null where the date is disputed or unknown.
integer | nullyear
Year production ended, or null while it is still made.
FirearmStatus | nulle.g.in_production
Production status, one of in_production, discontinued, out_of_production, in_service, limited_production, prototype. Discontinued records are kept deliberately: a rifle built in 2004 wears parts nobody sells today.

Dimensions and weight

Millimetres and grams, measured as the maker quotes them.

number | nullgBuilder+e.g.625
Unloaded weight in grams, without magazine.
number | nullgBuilder+e.g.905
Loaded weight in grams, with a full magazine.
number | nullmmBuilder+e.g.204
Overall length in millimetres, stock extended where it folds or collapses.
number | nullmmBuilder+e.g.490
Length with stock folded (mm)
number | nullmmBuilder+e.g.114
Barrel length in millimetres, measured from the breech face.
number | nullmmBuilder+e.g.139
Height in millimetres, including sights and a fitted magazine.
number | nullmmBuilder+e.g.34
Width in millimetres at the widest point.
number | nullmmBuilder+e.g.165
Distance between front and rear iron sights in millimetres. Null on a record with no iron sights.

Action, trigger and feeding

How it cycles, fires and is fed.

string | nulle.g.short_recoil
How the action cycles: short_recoil, gas_operated, blowback, bolt_action and so on. An open vocabulary: the values in use are published on the schema as x-gunspec-vocabulary, and GET /v1/firearms/action-types is the live list.
string | nullBuilder+e.g.striker-fired
What releases the striker or hammer: striker_fired, hammer_fired.
string | nullBuilder+e.g.safe-action
Trigger arrangement: single_action, double_action, safe_action.
number | nullNBuilder+e.g.28
Trigger pull weight in newtons. Divide by 4.448 for pounds-force.
string | nullBuilder+e.g.["semi_automatic","full_automatic"]
JSON array of firing modes
integer | nullrpmBuilder+
Cyclic rate in rounds per minute. Null on anything that is not automatic.
integer | nullroundsBuilder+e.g.17
Rounds in the standard magazine. Null where the firearm is not magazine-fed.
string | nullBuilder+e.g.detachable-box
Magazine pattern: detachable_box, internal, drum, belt.
string | nullBuilder+
JSON array of feed systems
string | nullBuilder+
JSON array of safety mechanisms

Ballistics

Figures for the default load, plus the source's own figures kept beside ours.

string | nullBuilder+e.g.m882
The ammunition load ballistics figures are quoted against, where one is nominated.
number | nullm/sBuilder+e.g.375
Muzzle velocity in metres per second, for the default load.
number | nullJBuilder+e.g.570
Muzzle energy in joules, for the default load.
number | nullmBuilder+e.g.50
Effective range in metres against a point target.
number | nullmBuilder+
Maximum range in metres. Where the projectile lands, not where it is useful.
string | nullBuilder+e.g.polygonal
Rifling description, e.g. 6 grooves, right-hand twist.
number | nullmmBuilder+e.g.250
Rifling twist rate in millimetres per turn. Divide by 25.4 for inches.
integer | nullcountBuilder+
Number of grooves cut in the bore.
number | nullm/sBuilder+e.g.375
Muzzle velocity in metres per second exactly as the source stated it, kept beside our own figure so a reader can see what was quoted and what was derived.
number | nullJBuilder+e.g.565
Muzzle energy in joules exactly as the source stated it.
number | nullmBuilder+e.g.50
Effective range in metres exactly as the source stated it.
number | nullmBuilder+e.g.1800
Maximum range in metres exactly as the source stated it.
string | nullBuilder+e.g.Manufacturer specification sheet
Where the ballistics figures came from, named in prose.
string | nullBuilder+e.g.https://eu.glock.com/en/pistols/g17
URL of the ballistics source, where it is a page rather than a book.

Materials and finish

What it is made of and how it is finished, plus the feature tags a record carries.

string | nullBuilder+e.g.polymer
What the frame or receiver is made of.
string | nullBuilder+e.g.steel
What the slide is made of. Null on anything without one.
string | nullBuilder+e.g.steel
What the barrel is made of.
string | nullBuilder+
What the stock or furniture is made of.
string | nullBuilder+e.g.nDLC
Surface finish, e.g. nitride, parkerized, cerakote.
string | nullBuilder+
JSON array of features

Game balance

Editorial 0 – 100 balance numbers, not measurements.

integer | null0 – 100Builder+
Editorial game statistic, 0-100. Not a measured figure. These are balance numbers for game use and are not derived from the ballistics above.
integer | null0 – 100Builder+
Editorial game statistic, 0-100. Not a measured figure.
integer | null0 – 100Builder+
Editorial game statistic, 0-100. Not a measured figure.
integer | null0 – 100Builder+
Editorial game statistic, 0-100. Not a measured figure.
integer | null0 – 100Builder+
Editorial game statistic, 0-100. Not a measured figure.
integer | null0 – 100Builder+
Editorial game statistic, 0-100. Not a measured figure.
integer | null0 – 100Builder+
Editorial game statistic, 0-100. Not a measured figure.
integer | null0 – 100Builder+
Editorial game statistic, 0-100. Not a measured figure.

Media

Line art, models, images and documents on file.

integere.g.0
Integer flag, 1 when a 3D model is on file. Stored as the database holds it rather than as a boolean.
string | nullBuilder+e.g.https://assets.gunspec.io/firearms/line/svg/gloc…
Line-art silhouette, or null where none has been drawn.
string | nullBuilder+
GLB model, or null where none is on file.
FirearmImage[]
Every image on file, silhouette first. Each carries an absolute, directly fetchable url.
FirearmSchematic[]Builder+
Exploded-view and parts diagrams on file, empty where none have been sourced.

History and prose

Written context: description, service history, production figures.

string | null
Prose summary of the record, where one has been written.
string | nullBuilder+
Free-text notes that do not belong in a specific field.
string | nullBuilder+e.g.The AK-47 is so iconic it appears on the nationa…
Historical trivia / game-dev flavor text
string | nullBuilder+e.g.[{"name":"Vietnam War","years":"1955-1975","side…
JSON array of conflict objects with name, years, and sides
string | nullBuilder+e.g.{"estimated_total":75000000,"production_years":"…
JSON object with estimated_total, production_years, and notes
FirearmUser[]
Forces and agencies that have adopted it.

Relations

Objects embedded in the detail response; see Nested objects below for their fields.

Manufacturer | null
Null when the record names a manufacturer id the catalog no longer holds.
Category | null
Null when the record names a category id the catalog no longer holds.
FirearmCaliber[]
Every cartridge this firearm is chambered for, primary first.

Provenance and caching

Where the figures came from, and the two signals a mirror keys on.

string | nullBuilder+
JSON array of source URLs the record was compiled from. Check a specific figure against these rather than against dataConfidence.
number | null0 – 1Builder+e.g.0.95
How completely the record is specified and how well it is sourced, 0 to 1. A record-level completeness and provenance measure, not a per-field probability of correctness. Use it to rank and triage; use sources to verify an individual number.
Provenance
Where a record's figures came from and how far they have been checked, in one place. sources are the pages consulted; check a specific figure against those. sourceKinds says what each page is and bestSourceKind the strongest of them, on the hierarchy SourceKind defines: a maker or standards-body page is evidence for a figure, a retailer or forum page is evidence the item exists. dataConfidence is the 0 to 1 score set from what was actually sourced and never raised by hand. verifiedAt and verifiedFields say when a source was last read against the record and which fields it stated; null means the row is still seed knowledge. updatedAt and version are the same cache signals the record carries at the top level.
stringBuilder+e.g.2025-01-15 12:00:00
When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.
stringe.g.2026-09-10 06:42:19
When a field we serve last changed. Maintained by the database rather than by whatever wrote the row, so it moves for a corrected specification and does not move for a re-run of the importer.
string | nulle.g.a3f1c2d4e5b6a7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4…
Opaque fingerprint of this record. It changes when and only when a field we serve changes, so a client holding the same value already has the record and need not fetch it. Equality is the only supported operation: do not parse it, and do not assume how it is computed. Null means the record has not been written since versioning began, not that it is unchanged.

Nested objects

The objects a detail record embeds under calibers, images, users, schematics and provenance. Provenance is also what a cartridge and an attachment carry; its meaning is under Data confidence below.

FirearmCaliber22

stringe.g.9x19mm-parabellum
Slug of the cartridge. Resolve against /v1/calibers/{id}.
integere.g.1
Integer flag, 1 on the chambering the firearm is normally sold in. A firearm may be chambered for several cartridges but has at most one primary.
stringe.g.9x19mm Parabellum
Display name, as the maker writes it.
string | nulle.g.9mm NATO
NATO designation where the cartridge has one, e.g. 9mm NATO. Null otherwise.
number | nullmme.g.9.01
Bullet diameter in millimetres.
number | nullmme.g.19.15
Case length in millimetres.
string | nulle.g.rimless
Head type: rimmed, rimless, semi_rimmed, rebated_rim, belted, plus historical values like cap_and_ball. Not the broad class. The registry said pistol/rifle/shotgun until the column was read, and it holds neither.
number | nullmme.g.9.65
Case neck outside diameter in millimetres.
number | nullmm
Bottleneck cases only.
number | nullmme.g.9.93
Case base diameter in millimetres, ahead of the extractor groove.
number | nullmme.g.9.96
Rim diameter in millimetres.
number | nullmme.g.1.27
Rim thickness in millimetres.
number | nullmme.g.29.69
Overall length in millimetres, stock extended where it folds or collapses.
number | nullmme.g.15.5
Typical projectile length.
number | nullge.g.7.45
Representative bullet weight in grams. Divide by 0.0648 for grains.
string | nulle.g.small_pistol
Primer size and type, e.g. small_pistol, large_rifle, rimfire.
string | nulle.g.tapered
Case profile: straight, bottleneck, tapered, belted.
string | nulle.g.brass
What the case is made of: brass, steel, aluminium, polymer.
string | nulle.g.bullet
none is a blank.
string | nulle.g.round_nose
Bullet shape: fmj, hollow_point, soft_point, spitzer, round_nose.
string | nulle.g.bullet
What seals the case mouth; a blank is a star crimp.
string | null
Paint that identifies the load: crimp lacquer on a blank, tip colour on a military round.

FirearmImage14

integere.g.1
Autoincrementing image id. Numeric, unlike the catalog slugs.
stringe.g.glock-17-gen5
Slug of the firearm this row belongs to.
stringe.g.https://assets.gunspec.io/firearms/line/svg/gloc…
Absolute, directly fetchable URL.
ImageType | nulle.g.photo
Role of the image: primary, gallery, thumbnail, svg, render.
string | nulle.g.manufacturer
Where the record came from: a curated entry, an inference, or an import.
string | nulle.g.fair-use
Licence the asset is held under, where one is recorded.
MediaKind | nulle.g.silhouette
What the asset is: silhouette, render, photo, schematic, model. /v1/firearms/{id}/media/{selector} addresses an asset by this.
string | nulle.g.cdn
Where the bytes live: cdn for a static path, r2 for an upload we serve.
string | null
Who made the asset, where it is credited.
string | null
Page the asset or document was taken from.
string | null
Alt text, where one has been written. Null otherwise, so do not render an empty string.
integer | nulle.g.1200
Pixel width, where it is known.
integer | nulle.g.800
Pixel height, where it is known.
integere.g.0
Position within its list, ascending.

FirearmUser7

integere.g.1
Autoincrementing row id.
stringe.g.glock-17-gen5
Slug of the firearm this row belongs to.
stringe.g.Austrian Armed Forces
The force, agency or organisation that adopted it.
string | nulle.g.military
What kind of user: military, police, civilian.
string | nulle.g.AT
ISO 3166-1 alpha-2 code of the user's country.
integer | nulle.g.1982
Year of adoption, where it is known.
string | nulle.g.Pistole 80
What that user calls it, where it differs from the maker's name.

FirearmSchematic13

integere.g.12
Autoincrementing schematic id.
stringe.g.glock-17-gen5
Slug of the firearm this row belongs to.
stringe.g.Exploded view
What the document is called.
SchematicType
What a schematic document is.
stringe.g.https://assets.gunspec.io/firearms/schematics/gl…
Absolute, directly fetchable URL.
string | nulle.g.pdf
File format, e.g. pdf.
string | null
Revision of the document, where the publisher versions it.
string | nulle.g.Glock Ges.m.b.H.
Publisher of the document, often but not always the maker.
string | null
Where the document came from.
string | null
Page the asset or document was taken from.
string | null
Who made the asset, where it is credited.
string | null
Licence the asset is held under, where one is recorded.
stringe.g.2026-05-26 12:36:27
When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.

ProvenanceWhere a record's figures came from and how far they have been checked, in one place. `sources` are the pages consulted; check a specific figure against those. `sourceKinds` says what each page is and `bestSourceKind` the strongest of them, on the hierarchy `SourceKind` defines: a maker or standards-body page is evidence for a figure, a retailer or forum page is evidence the item exists. `dataConfidence` is the 0 to 1 score set from what was actually sourced and never raised by hand. `verifiedAt` and `verifiedFields` say when a source was last read against the record and which fields it stated; null means the row is still seed knowledge. `updatedAt` and `version` are the same cache signals the record carries at the top level.9

string[]e.g.["https://www.glock.com/en/products/pistols/g17-…
The pages consulted when the record was compiled, as an array. Check a specific figure against these rather than against dataConfidence.
object[]e.g.[{"url":"https://www.glock.com/en/products/pisto…
What each cited page is, in sources order, on the SourceKind hierarchy. A host not in the source map is other, never guessed.
SourceKind | nulle.g.manufacturer
The strongest kind among the citations, or null when nothing is cited. manufacturer or standards_body means a figure can be checked against an authority; retailer or community alone means the record is still supported by copies of copies.
number | null0 – 1e.g.0.95
The 0 to 1 score set from what was actually sourced, never raised by hand. See the confidence bands in the docs.
string | nulle.g.2026-09-08
When a source was last read against this record. Null means the row is still seed knowledge.
string[]e.g.["barrel_length_mm","weight_empty_g"]
Which fields the source stated, as an array. Everything else on a verified row is still unverified. Null where no source has been read.
string | null
Cartridges only: the page the drawing figures were taken from. Null on every other kind of record.
stringe.g.2026-09-08 04:10:22
When a served column last changed; the same value the record carries at the top level.
string | nulle.g.ba5c1d9e06c279a5
The record's content version, equal to the top-level version; equal versions mean equal data.

Production status values

What status can hold on a record.

Currently manufactured
No longer manufactured
Production has ended; may return
Out of production but still in active service
Produced in limited numbers
Prototype, never mass-produced

All six are accepted by ?status= on GET /v1/firearms.

Action types

The actionType vocabulary as it occurs in the catalog, most common first. It is not a closed list: GET /v1/firearms/action-types returns every value in use with counts.

Barrel and slide recoil locked together, then unlock (most semi-auto pistols)
Manually cycled rotating bolt
Bolt held only by spring and mass, no locking (smaller cartridges)
Barrels hinge open to load
Gas-operated, pattern not further specified
Gas piston fixed to the carrier, travels its full length (e.g. AK)
Gas vented straight onto the bolt carrier (e.g. AR-15)
Cylinder indexes a fresh chamber behind the barrel
Gas piston travels a short distance to drive the carrier
Loaded from the muzzle; no cartridge
Manually cycled by sliding the forend
Manually cycled by a finger lever
Trigger both cocks and releases the hammer or striker
Breechblock drops vertically to expose the chamber
Rollers delay bolt opening (e.g. MP5, G3)
Hammer or striker cocked before the trigger will fire
Short-stroke piston, the piston named explicitly in the source
Revolver; hammer manually cocked before each shot
Revolver; trigger cocks and releases the hammer
Recoil inertia of the bolt body unlocks the action (some shotguns)
Recoil-operated, pattern not further specified
Blowback with a mechanical delay other than rollers
Barrel and bolt recoil the full stroke together (e.g. Auto-5)
Gas-operated with a rotating bolt lock
Loaded at the breech; single-shot, mechanism not further specified
Breechblock rotates back to open (single-shot)
Bolt cycled with a straight pull, no rotation of the handle
Hinged breechblock lifts forward to load (e.g. Springfield 1873)
Air gun; a spring-driven piston compresses the charge
Breechblock hinges away from the chamber to load
A lever delays bolt opening (e.g. FAMAS)
Barrel driven forward off the standing breech
Externally powered rotary barrels
Trigger always cocks and releases; no single-action mode
Barrel rotates to unlock from the slide
Air gun; pre-charged or pumped air
Gas system switchable between two modes
Blowback delayed by a rotating barrel rather than by rollers
Blowback delayed by gas pressure bled against the bolt
Blowback delayed by lugs camming radially out of the carrier
Short recoil in which the barrel rotates to unlock
Gas-operated with a counter-mass moving against the carrier to cancel recoil
Gas-operated with a balanced recoil system damping the impulse
Gas-operated in which the barrel moves forward rather than the bolt back
Gas-operated, firing from an open bolt
Gas-operated with a bolt that tilts to lock (e.g. FN FAL)

Data confidence

dataConfidence is a score from 0 to 1 for how much of a record a source stands behind. It is set from what was actually sourced when the record was compiled or verified, and it is never raised by hand: a person can lower it after finding a disagreement, and only a new source can lift it. It is a record-level measure, not a per-field probability that a given number is correct: 0.95 does not mean the barrel length is 95% likely to be right.

On a firearm the score also reflects coverage: how much of the record the cited pages covered, and what kind of pages they were. A full record from the maker’s sheet that two references confirm sits above 0.9; a single unconfirmed source sits under 0.7. A count on its own says little, since four retailer pages repeating one maker figure are one source. That is why provenance.sourceKinds classes each page and provenance.bestSourceKind names the strongest. On a cartridge or an attachment the score follows the bands below exactly, because those records are verified one source at a time.

What each band means

The ceiling a record may carry for what was found. A record is placed in the highest band its evidence supports and never above it.

Score	What was sourced
`0.95`	A standards body drawing (SAAMI, CIP) or the maker's own product page or spec sheet, confirming every figure the record states.
`0.90`	A full reference entry, every dimension present, with no standards citation.
`0.80`	A reference entry missing one or more figures, as with an obscure or historical round.
`0.75`	A maker's or distributor's product page confirming existence, calibre, length and colour code, or a retailer confirming a part's figures when the maker's page could not be fetched.
`0.70`	A collector or reference site, a foreign-language reference or a reloading manual page.
`0.60`	Only a retailer or a forum confirms the item exists; the figures stand as seeded.
`0.50`	Nothing found. The record is seed model knowledge, and `verifiedAt` is null.

Two things lower a score below its band. A figure a validator flagged that no second source could resolve caps the record at 0.6, and the disagreement is written into notes. A mounting interface the maker's page contradicts drops an attachment to 0.6 until it is corrected, because a wrong thread is a safety fact.

verifiedFields is the evidence

A cartridge or attachment record carries verifiedFields: exactly the fields its source stated, and nothing more. A field not listed there is at the record's seed standing whatever the score says. Categorical fields such as the case shape or the projectile kind are judgement rather than sourcing and never raise the score on their own. verifiedAt is when that check was made; null means nobody has checked the record against a source yet.

What to do with a low score

Treat anything you would not act on unverified as unverified. At 0.6 only the item's existence was confirmed; at 0.5 nothing was.
Check a specific figure against sources, never against the score. The score says how well the record as a whole is backed; the pages say where each figure could be confirmed.
Filter rather than guess. GET /v1/data/confidence lists records below a threshold, lowest first; on the compatibility endpoints min_confidence hides fits computed through weak evidence.
Report what you find. A wrong figure is a data report a person acts on, and the correction reaches every caller.

The source hierarchy

Every page a record cites is classed as one SourceKind, strongest first, and the record carries the result: provenance.sourceKinds is one { url, kind } per page and provenance.bestSourceKind the strongest of them. Weigh a figure by the best kind behind it, never by how many pages were cited. Specifications legitimately differ by year, factory and market, so pages disagree; when they do, the higher kind wins and the record's notes say that they disagreed.

manufacturer The maker's own product page, manual, datasheet or catalogue. The authority on anything the maker publishes.
standards_body SAAMI, C.I.P. or a NATO standard. The authority on cartridge dimensions and pressures.
government A procurement document, a technical manual, a service's own site, a national museum. Any .mil or .gov host is classed here by rule.
reference An independent reference that names where its figures came from: an encyclopaedia, Modern Firearms, Forgotten Weapons, a museum collection, Jane's.
aggregator A site that compiles figures from other sources without saying which. Useful for coverage, weak as evidence.
press A magazine, review site or blog: a journalist's own measurement, or a maker's figure repeated.
retailer A listing written to sell the item. Evidence the item exists and what the market calls it; its figures are copied from elsewhere.
community A forum, wiki or fan site. Evidence of existence and naming only, never the sole source for a figure.
other A host not yet in the source map. Reported as the weakest kind until it is classed, never guessed, so a share quoted for the stronger kinds can only be understated.

Today 100% of firearms cite at least one page, 83% cite two or more, and 34% cite a manufacturer, standards_body or government page. Computed from the catalog at every build. A record still at seed model knowledge carries dataConfidence 0.5 with verifiedAt null whatever its pages say.

The provenance object

GET /v1/firearms/{id}, GET /v1/calibers/{id} and GET /v1/attachments/{id} carry a provenance object, which is the one place to read sourcing from. It gathers what the sections above describe: the pages consulted and what kind of page each is, the score, when and which fields were verified, and the two cache signals.

sourcesThe pages consulted for the record.
sourceKindsEach cited page and its kind, in the order of `sources`, on the hierarchy above. A host not in the source map is `other`.
bestSourceKindThe strongest kind among the citations, or null when nothing is cited. `manufacturer` or `standards_body` means a figure can be checked against an authority; `retailer` or `community` alone means the record rests on copies.
dataConfidenceThe 0 to 1 score above, or null when the record has never been scored.
verifiedAtWhen the record was last checked against a source; null for seed model knowledge.
verifiedFieldsExactly the fields that source stated; null when nothing has been verified.
updatedAtWhen the served columns last changed, maintained by the database.
versionThe record's content hash; equal versions mean equal data on every plan.
specSourceCartridges only: the page the drawing dimensions were read from.

There is no per-field attribution and no per-record revision history yet: verifiedFields says which fields were confirmed, not by which page, and updatedAt says when the record last changed, not what changed. Do not infer either from the fields above.