Firearms

List firearms

Returns a paginated list of firearms with optional filters. Filters combine with AND; features takes comma-separated slugs that must all match.

Available on every plan. Requires an API key; Explorer keys receive a reduced field set.

get/v1/firearms

Request

  • Base URL: https://api.gunspec.io
  • URL: https://api.gunspec.io/v1/firearms
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Query parameters

pageinteger

Page number, from 1 to 10,000

per_pageinteger

Items per page (max 100)

sort'name' | 'weight' | 'year' | 'caliber' | 'created_at' | 'favorites'

Sort field

order'asc' | 'desc'

Sort order

fieldsstring

Comma-separated list of fields to include

manufacturerstring

Filter by manufacturer slug

caliberstring

Filter by caliber slug

categorystring

Filter by category slug

action_typestring

Filter by action type, as stored and underscored. The vocabulary is /v1/firearms/action-types

country_of_originstring

Filter by ISO 3166-1 alpha-2 country code

year_introduced_mininteger

Minimum year introduced

year_introduced_maxinteger

Maximum year introduced

weight_minnumber

Minimum empty weight (grams)

weight_maxnumber

Maximum empty weight (grams)

barrel_length_minnumber

Minimum barrel length (mm)

status'in_production' | 'discontinued' | 'out_of_production' | 'in_service' | 'limited_production' | 'prototype'

Filter by production status

featuresstring

Comma-separated feature slugs; all must match

has_3d_model'true' | 'false'

Only firearms with (or without) a 3D model

has_image'true' | 'false'

Only firearms with (or without) real imagery: a render or a photograph, ignoring the line-art silhouette every firearm has

created_afterstring

Only records added after this ISO 8601 timestamp

created_beforestring

Only records added before this ISO 8601 timestamp

Headers

If-None-Matchstring

The ETag from a previous response. If the body would be byte-identical, the API answers 304 Not Modified with no body. A 304 counts toward the per-minute rate limit but not the daily request allowance.

Response

Paginated list of firearms

successboolean required

Always true on a successful response. Every error carries false and an error object instead.

Example response

{
  "success": true,
  "data": [
    {
      "id": "glock-g17-gen5",
      "name": "Glock 17 Gen5",
      "manufacturerId": "glock",
      "categoryId": "pistol",
      "yearIntroduced": 2017,
      "countryOfOrigin": "AT",
      "actionType": "short_recoil",
      "weightEmptyG": 625,
      "barrelLengthMm": 114,
      "images": [
        {
          "id": 2572,
          "url": "https://api.gunspec.io/v1/firearms/ak-47/images/2572",
          "alt": "AK-47 right profile",
          "width": 1536,
          "height": 1024
        }
      ],
      "createdAt": "2026-09-06 23:55:07",
      "svgLineArtUrl": "https://api.gunspec.io/v1/firearms/glock-g17-gen5/media/silhouette",
      "updatedAt": "2026-09-10 06:42:19",
      "version": "a3f1c2d4e5b6a7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.