# GunSpec.io

> Comprehensive firearms specification database and REST API for developers. Technical data for 8,000+ firearms including dimensions, weight, caliber, capacity, and operational characteristics.

## API Overview

GunSpec.io provides a RESTful API for accessing detailed firearms specifications. The API supports search, comparison, filtering, and pagination. All responses return JSON.

- Base URL: https://api.gunspec.io/v1
- Authentication: API key via X-API-Key header, or Authorization: Bearer <key> - both accepted everywhere, neither is being retired
- Rate Limits: Tier-based (Explorer: 10/min, Builder: 60/min, Studio: 120/min, Enterprise: 300/min)
- Caching: encouraged. Read Cache-Control off each response; catalog records carry updatedAt and version, and catalog responses carry an ETag. Send it back as If-None-Match for a 304 with no body, which does not count toward your daily allowance. Table: https://docs.gunspec.io/en/caching
- Webhooks: on Studio and Enterprise, POST /v1/me/webhooks registers an endpoint and catalog changes are pushed to it, so a mirror needs no polling loop. Events cover firearms, manufacturers and calibers, plus firearm.variant.updated, firearm.source.changed, firearm.confidence.changed and catalog.resynced. The delivery carries the record in the same shape the detail endpoint returns it, version included; a deletion carries the id alone. Dedupe on X-Webhook-Id and verify X-Webhook-Signature before trusting the body.
- Documentation: https://docs.gunspec.io
- OpenAPI Spec: https://api.gunspec.io/openapi.json
- Interactive explorer (Swagger UI): https://api.gunspec.io/docs
- AI / coding-agent skills: https://assets.gunspec.io/ai/

## Response shape and errors

Success: `{ "success": true, "data": ... }`. List endpoints add
`"pagination": { page, limit, per_page }`, plus `total` and `totalPages` on
Builder and above. Do not drive a paging loop from `totalPages`, because it is
absent for Explorer and anonymous callers. Page until a short page comes back.
`per_page` maxes out at 100.
Not every success is JSON: `/v1/ammunition/{id}/bullet.svg`, `/v1/firearms/{id}/media/{selector}` and `/v1/firearms/{id}/images/{imageId}` with `format=raw` (the default) and `/v1/firearms/{id}/model` return the file's bytes, and `/v1/out/{clickId}` answers a 302 redirect. Check `Content-Type` before parsing; see https://docs.gunspec.io/en/media

Error: `{ "success": false, "error": { "code", "message", "request_id" } }`.
Codes: VALIDATION_ERROR (400), UNAUTHORIZED (401), FORBIDDEN (403),
SUBSCRIPTION_REQUIRED (403), NOT_FOUND (404), RATE_LIMITED (429),
INTERNAL_ERROR (500), SERVICE_UNAVAILABLE (503).

SUBSCRIPTION_REQUIRED carries `details.requiredTier`: the caller is
authenticated but their plan does not include the endpoint. Treat it as
"upgrade", never as "retry", and never as "no results".

Every response carries an `X-Request-Id` header. A 429 is `RATE_LIMITED` (the
per-minute limit: wait `Retry-After`, 60 seconds, and retry), `DAILY_CAP_EXCEEDED`
(the key's allowance for the day) or `MONTHLY_CAP_EXCEEDED` (the plan's allowance
for the month, shared by every key on the account). For the last two nothing is
served until the reset, so stop at the first one and never retry in a loop:
`Retry-After` is the seconds until the reset (at most a day, or a month), and the
body carries `error.resetsAt`, `error.limit` and `error.retryAfter`. The SDKs
wait out a reset only when it is a few seconds away and otherwise raise at once.
Only calls that were served spend the month. A free key that keeps calling after
a refusal is paused (`403` with `KEY_ON_HOLD`), or at once on a paid plan. There
is no `X-RateLimit-Remaining`: the edge limiter reports whether a request was
allowed, not how much of the minute is left. What is left is sent on every
response: the day, per key (`X-Daily-Limit`, `X-Daily-Remaining` and
`X-Daily-Reset`, the next midnight UTC, plus `X-Daily-MCP-*` on MCP traffic), and
the month, for the account, on a call made with a key (`X-Monthly-Limit`,
`X-Monthly-Remaining` and `X-Monthly-Reset`). Each remaining figure is what is
left after that call. Pace from those and stop when either reaches 0; reconcile
with `GET /v1/me/usage`, which is itself a counted request, so do not poll it.

## Agent workflow (read this before calling anything)

1. **Resolve the name to an id first.** `GET /v1/firearms/resolve?q={what the user said}`.
   Pass their words through unchanged: it is built for "G19 gen 5 MOS", "AK-47",
   "H&K MP5". Never guess a slug: `glock-19-gen5`, `glock-g19-gen5` and
   `glock-19` are not interchangeable, and a guess returns 404 or a record for a
   different variant. This is not search: `/v1/firearms/search` ranks a page of
   records *about* a query and has no notion of certainty; resolve answers which
   record a query *is*.
2. **`status: "ambiguous"` means ask the user, not pick the first.** `firearmId`
   is null and `alternatives` holds the tied candidates with their names. "Glock
   19" does not name a generation, and the generations differ in exactly the
   weights and dimensions people ask about.
   `status: "not_found"` is a 200, not a 404: say we hold no such record. Any
   `match: "fuzzy"` candidate is a suggestion, always scores 0, and is never an
   answer. Read `unresolvedTokens` before replying: those are words the resolver
   could not place, usually a variant the catalog does not hold.
   `POST /v1/firearms/resolve` resolves up to 50 names in one request (Studio).
3. `GET /v1/firearms/{id}` for the full record. `GET /v1/firearms/{id}/variants`
   for the rest of the family.
4. **Never infer a missing specification.** `null` means GunSpec does not hold the
   value. Do not fill it from model knowledge, from a sibling variant, or by
   computing it. Say it is not in the database.
5. **Units are in the field names**: `weightEmptyG` grams, `barrelLengthMm` and
   `overallLengthMm` millimetres, `muzzleVelocityMps` m/s. Read the suffix and
   state the unit. `/v1/firearms/{id}/dimensions` gives metric and imperial.
6. **`dataConfidence` is not accuracy.** It is a 0-1 record-level score set from
   what was actually sourced and never raised by hand, not a per-field
   probability that a number is correct: 0.95 does not mean the barrel length is
   95% likely to be right. 0.5 with `verifiedAt` null is seed model knowledge;
   treat anything below 0.7 as unverified. Use it to rank and triage; follow
   `sources` (or the `provenance` object on a detail record) to verify a specific
   figure. Bands and source order: https://docs.gunspec.io/en/field-reference#data-confidence
7. Specifications legitimately differ by production year, factory, batch and
   regional variant. Where a record notes disagreement between sources, surface
   the disagreement rather than presenting one number as settled.

8. **Cache what you fetch, and refresh conditionally.** Store the `ETag` you were
   given and send it back as `If-None-Match`; a record that has not changed
   answers 304 with no body and no charge against your daily allowance. Compare
   `version` (stable across plans) rather than `ETag` when reconciling mirrors
   held under different keys.

9. **Say how a figure was checked, and whether it is still being checked.**
   A record's `provenance` names its sources and their kind; `provenance.checks`
   lists every check run against it, each with a `finding.why` in the check's
   own words when it raised one. An open task at
   `https://api.gunspec.io/v1/data/tasks?subject={id}` means the figure is under review:
   say so rather than presenting it as settled, and do not call the figure wrong:
   an open task is a question, not a verdict, and can close with the record
   confirmed as it stands. Each task has a page with what changed, the quoted
   source and the reasoning: https://docs.gunspec.io/en/quality/tasks/{number}.
   How each check judges a figure
   (weight against size, loaded against empty, cartridge arithmetic, physical
   bounds, trajectory) is set out, with its equations and sources, on the
   Methods tab: https://docs.gunspec.io/en/methods/overview

Full agent brief (workflow, tool-layer shape, pagination and error handling):
https://docs.gunspec.io/llms-full.txt

## Endpoints

### Firearms
- GET /v1/firearms: List all firearms (paginated; filters: manufacturer, caliber, category, action_type, country_of_origin, status, features, has_image, has_3d_model, year/weight/barrel ranges; sort + order; fields)
- GET /v1/firearms/resolve?q={name}: A name as a person writes it to one id, with an honest `ambiguous` when it is several. Call this first when you start from text
- POST /v1/firearms/resolve: The same for up to 50 names in one request (Studio)
- GET /v1/firearms/search?q={query}: Full-text search across firearms
- GET /v1/firearms/compare?ids={id1},{id2}: Side-by-side comparison
- GET /v1/firearms/{slug}: Detailed specifications for a single firearm
- GET /v1/firearms/{slug}/variants: Variant models of a firearm
- GET /v1/firearms/{slug}/images: Images for a firearm

### Manufacturers
- GET /v1/manufacturers: List all manufacturers
- GET /v1/manufacturers/{slug}: Manufacturer details
- GET /v1/manufacturers/{slug}/firearms: Firearms by manufacturer

### Calibers
- GET /v1/calibers: List all calibers
- GET /v1/calibers/{slug}: Caliber details
- GET /v1/calibers/{slug}/firearms: Firearms by caliber

### Categories
- GET /v1/categories: List all categories
- GET /v1/categories/{slug}/firearms: Firearms in a category

## Pricing

| Tier | Price | Requests/month | Rate Limit |
|------|-------|----------------|------------|
| Explorer | $0 | 200 | 10/min |
| Builder | $29/mo | 25,000 | 60/min |
| Studio | $79/mo | 150,000 | 120/min |
| Enterprise | $249/mo | 1,000,000 | 300/min |

## Data

The database includes 8,000+ firearms, 900+ manufacturers and 500+ calibers, with verified technical specifications:
- Dimensions (length, barrel length, height, width)
- Weight (loaded, unloaded)
- Caliber and ammunition compatibility
- Magazine capacity
- Action type and firing mechanism
- Manufacturer information
- Category classification (pistol, rifle, shotgun, etc.)
- Game-ready normalized stats (damage, accuracy, range, fire rate, mobility, recoil, reload speed, concealment)

## Data quality and methods

- How the catalogue is checked: https://docs.gunspec.io/en/quality/overview
- Live totals: https://docs.gunspec.io/en/quality/database-index, https://docs.gunspec.io/en/quality/records-index, https://docs.gunspec.io/en/quality/systems-index
- The methods every check rests on, as Markdown: https://docs.gunspec.io/md/methods-overview.md (one page per model: cartridge mass, loaded weight, apparent density, cartridge arithmetic, physical bounds, trajectory, materials, sources, references)
- Every cited site, its kind and rank: https://api.gunspec.io/v1/data/sources
- Every review task, searchable, each with a page of its own: https://docs.gunspec.io/en/quality/tasks, and the closed ones with who closed them: https://docs.gunspec.io/en/quality/completed
- Redback, the research agent that works the tasks (reads makers' pages and spec-sheet PDFs, quotes the exact words, changes nothing until a person accepts): https://docs.gunspec.io/md/methods-redback-pipeline.md
- Why the data quality work is public and what a subscription pays for: https://docs.gunspec.io/md/quality-faq.md
- Telling us a figure is wrong, and the path a report takes: https://docs.gunspec.io/md/quality-reports.md
- What is checked every night and what it found: https://gunspec.io/en/trust

## Pages

- [API Documentation](https://docs.gunspec.io): Developer docs, interactive API playground, and SDK guides for all endpoints
- [Pricing](https://gunspec.io/en/pricing): Subscription tiers from free Explorer to Enterprise
- [Firearms Database](https://gunspec.io/en/firearms): Browse, search, and filter every firearm in the database
- [Manufacturers](https://gunspec.io/en/manufacturers): Every maker in the catalogue, with what each builds
- [Calibers](https://gunspec.io/en/calibers): Cartridges with dimensions, pressures and the firearms chambered for them
- [Ammunition](https://gunspec.io/en/ammunition): Factory and military loads with bullet weight, velocity, ballistic coefficients and a solved trajectory
- [Attachments](https://gunspec.io/en/attachments): Parts, and which firearms each one fits
- [Recently added](https://gunspec.io/en/recently-added): The newest records, by the day they were added
- [What's new in the catalogue](https://gunspec.io/en/changes): Every record added, corrected, removed or merged, by day, with the fields that moved
- [New releases](https://gunspec.io/en/releases): New firearm models, by the day each was announced, with when it ships and the sources that name it
- [Updates](https://gunspec.io/en/updates): What changed in the API and the catalogue
- [About](https://gunspec.io/en/about): Why the catalogue exists, how it is sourced, and the company that runs it
- [Blog](https://blog.gunspec.io): Articles on API usage, game development, and firearms data
- [MCP server](https://mcp.gunspec.io): Connect an AI assistant to the catalogue over the Model Context Protocol

## Links

- Website: https://gunspec.io
- API Docs: https://docs.gunspec.io
- OpenAPI: https://api.gunspec.io/openapi.json
- Swagger UI: https://api.gunspec.io/docs
- Coding-agent skills: https://assets.gunspec.io/ai/
- Pricing: https://gunspec.io/en/pricing

## Optional

- [Terms of Service](https://gunspec.io/en/terms): Legal terms for API usage
- [Privacy Policy](https://gunspec.io/en/privacy): Data collection and usage policies
- [Disclaimer](https://gunspec.io/en/disclaimer): Legal disclaimers for firearms data