GunSpec API

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; 27 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.

   cURLTypeScriptPython

   cURL

   cURLTypeScriptPython

   1curl -H "X-API-Key: your_api_key" \2  "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

   1{2  "success": true,3  "data": [4    {5      "id": "glock-g17-gen5",6      "name": "Glock 17 Gen5",7      "manufacturerId": "glock",8      "updatedAt": "2026-09-10 06:42:19",9      "version": "a3f1c2d4e5b6a7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2"10    },11    /* two more rows */12  ],13  "pagination": {14    "page": 1,15    "per_page": 3,16    "limit": 317  }18}

   • 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.

   • 429MONTHLY_CAP_EXCEEDED

     The plan's monthly request allowance is used up. It resets at midnight UTC on the first of the month. Calls a limit refused do not count towards it. Wait for the reset in Retry-After, error.resetsAt or X-Monthly-Reset, or choose a larger plan, which raises the allowance at once.

   Every code and reason

Pick your path

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

• Explore the referenceEvery endpoint, its parameters and a live console.
• Use an SDKTyped clients for TypeScript and Python, with auto-paging and retries.
• Field referenceEvery field a record carries, with type, unit and meaning.
• AI & agentsAgent packs, llms.txt and the MCP route into the catalog.

How the data is kept right

You are building on figures we publish, so you should be able to see how they are checked. Every record is read against its sources and the physics of what it describes, questions about it are answered with quoted evidence, and all of that work is public.

• Why we publish thisWhy the data quality work is public, and what your subscription pays for.
• Data qualityEvery check the catalogue is held to, and where each stands today.
• MethodsHow each check calculates, with the figures and sources behind it.
• How Redback worksThe research agent that answers questions about a record, and how its work is checked.
• Task boardEvery open question about a record, and where it has got to.
• Completed workWhat was closed, how, and on which sources.

The basics

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

• AuthenticationX-API-Key or Bearer; 401 is your credential, 403 is your plan.
• Paginationpage and per_page; stop on a short page, not on totalPages.
• ErrorsOne envelope, a stable code, a specific reason, a request id.
• Rate limitsPer minute, per day and per month, with Retry-After on a 429.
• CachingETag on every catalog response; a 304 costs none of your daily or monthly quota.
• WebhooksSigned deliveries when the catalog changes, on Studio and up.
• Versioning/v1 is the contract; additive changes land, breaking ones move.
• SecurityWhat protects the platform and how to report a weakness.