GunSpec
Quick start

GunSpec API

Everything you need to integrate firearms specification data into your app, game, or research project: a REST API with a free tier, typed SDKs and a live console.

Base URLhttps://api.gunspec.io
Get API Key
  • 9,162Firearms
  • 1,003Manufacturers
  • 605Calibers
  • 133Operations across 124 paths

133 operations across 124 endpoints: a path that answers both GET and PUT is one endpoint and two operations, so the two figures never match. The reference counts operations; the SDKs, the agent packs and the website count endpoints.

Four steps to a first response

Ten minutes from nothing to a list of firearms in your terminal, with the refusals you will meet on the way explained before you meet them.

  1. 1

    Get a free key

    Every catalog call carries a key; 17 operations answer without one, listed on the Authentication page. A free Explorer key takes a minute and is enough to build against. Send it as X-API-Key, or as Authorization: Bearer. Both work everywhere.

    Requests / month
    200
    Requests / min
    10
    Requests / day
    50
    Pages deep
    5
    Get API KeyCompare the plans
  2. 2

    Make your first request

    The list endpoint is the one to try first: it takes no arguments, answers on every plan, and shows the envelope every other list uses. per_page=3 keeps the output short.

    cURL
    curl -H "X-API-Key: your_api_key" \  "https://api.gunspec.io/v1/firearms?per_page=3"
    Run it in the Try It consoleOr in Swagger UI
  3. 3

    Read the response

    Every /v1 JSON success is the same envelope: success, data, and on a list, pagination. Two things sit outside it on purpose. The /health and /ready probes answer a flat { status } body, since a load balancer reads them and never a client. A handful of operations answer with a file or a redirect instead: the bullet diagram, raw media and 3D model downloads, and the seller click tracker’s 302, all listed on the media page. The sample below is what an Explorer key receives, 5 fields per row, built from the spec’s own examples.

    GET /v1/firearms on Explorer
    json
    {  "success": true,  "data": [    {      "id": "glock-17-gen5",      "name": "Glock 17 Gen5",      "manufacturerId": "glock",      "updatedAt": "2026-09-10 06:42:19",      "version": "a3f1c2d4e5b6a7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2"    },    /* two more rows */  ],  "pagination": {    "page": 1,    "per_page": 3,    "limit": 3  }}
    • data is one page. Walk the rest with page and stop on a short page; the pagination page has the loop that works on every plan.
    • pagination.total and totalPages are absent on Explorer: the free plan does not see how big the catalog is. They appear from Builder up.
    • Explorer rows carry 5 fields. The full record, including dimensions, ballistics, materials and media, is in the field reference and unlocks with a paid plan.
  4. 4

    Handle a refusal

    A refused request is the same envelope with success: false and an error carrying a stable code, a specific reason, a message and a request_id. These four are the ones a first integration meets, in the order it meets them.

    • 401KEY_MISSING

      No API key was sent. Send your key in the X-API-Key header.

    • 403PLAN_REQUIRED

      The credential is valid and its plan is below what this endpoint needs. details.requiredTier names the plan. Upgrade the plan. A new key on the same plan will get the same answer.

    • 429RATE_LIMITED

      Too many requests this minute for the plan. Wait for Retry-After seconds, then retry.

    • 429DAILY_CAP_EXCEEDED

      The plan's daily request allowance is used up. It resets at midnight UTC. Wait for the reset, or upgrade for a larger allowance.

    Every code and reason

Pick your path

Where to go next depends on what you are building. Each card is one page.

The basics

Eight things every integration meets, one line each. The linked page has the rest.