How it works

Architecture

Where your request goes, what decides the answer it gets, and where the figures in it come from. Seven diagrams, each linking to the page that owns the detail.

The path of a request

Every call meets the same checks in the same order: the cache first, then your key, then your plan's limits - and only then is the catalog read. A 304 or a 429 is an answer you get before any of your allowance is spent on looking anything up.

DiagramA request from your client to the answer

100%

flowchart LR
  client["Your client"] --> edge["Our edge"]
  edge -->|"a fresh copy is cached"| cached["Answered from cache"]:::ok
  edge -->|"otherwise"| key["Your API key is checked"]
  key --> limits["Your plan's limits are checked"]
  limits -->|"allowance spent"| capped["Refused: 429 Too Many Requests"]:::fail
  limits -->|"within your plan"| lookup["The catalog is read"]
  lookup --> shape["Shaped to what your plan includes"]
  shape --> answer["Answered: 200, with an ETag to cache against"]:::ok

A request from your client to the answerYour client calls our edge, which answers straight away when a fresh copy of that response is already cached. Otherwise your API key is checked, then your plan's limits: an exhausted allowance is 429 Too Many Requests, and a request inside your plan goes on to read the catalog. What comes back is shaped to the fields your plan includes and carries an ETag you can cache against, so the next identical request can be answered with a 304.

Where this is written up

Rate limits and plans/en/rate-limits Caching and refreshing/en/caching

What decides your status code

401 is about the credential and 403 is about permission, which is why presenting a different key fixes one and never the other. Each leaf here is a real response, and every one of them names a reason your client can branch on.

DiagramHow a request is admitted or refused

100%

flowchart TD
  start["A request to /v1"] --> has{"API key sent?"}
  has -->|"no"| open{"Open without a key?"}
  open -->|"yes"| handler["Answered"]:::ok
  open -->|"no"| unauth["Refused: 401 API_KEY_MISSING"]:::fail
  has -->|"yes"| valid{"Key valid and in date?"}
  valid -->|"no"| expired["Refused: 401 KEY_EXPIRED"]:::fail
  valid -->|"yes"| account{"Account in good standing?"}
  account -->|"no"| suspended["Refused: 403 ACCOUNT_SUSPENDED"]:::fail
  account -->|"yes"| plan{"Plan covers this endpoint?"}
  plan -->|"no"| upgrade["Refused: 403 PLAN_REQUIRED"]:::fail
  plan -->|"yes"| handler

How a request is admitted or refusedWith no API key, an endpoint that is open without one answers normally and any other answers 401 with the reason API_KEY_MISSING. With a key, an invalid or out-of-date key is 401 KEY_EXPIRED, an account not in good standing is 403 ACCOUNT_SUSPENDED, and a plan that does not cover the endpoint is 403 PLAN_REQUIRED. A request that passes all three is answered. A 401 means try a different key; a 403 means the key is fine and this caller is not permitted.

Where this is written up

Authentication/en/authentication Errors and reasons/en/errors

Keeping a copy current

You do not have to re-download the catalog to know your copy is current. Store the ETag you were given, send it back, and an unchanged record answers 304 with no body - a reply that costs you a rate-limit slot and nothing off your daily allowance.

DiagramRevalidating a copy you already hold

100%

sequenceDiagram
  participant C as Your copy
  participant A as GunSpec API
  C->>A: GET a record
  A-->>C: 200, with an ETag
  Note over C: keep the body and the ETag
  C->>A: The same request, If-None-Match
  A-->>C: 304 Not Modified, no body
  Note over A: one rate-limit slot, and nothing<br/>off your daily allowance

Revalidating a copy you already holdThe first request returns the record with an ETag, which you keep beside the body. The next time you ask for the same record you send that ETag back as If-None-Match: if nothing has changed you get 304 Not Modified with no body at all. That reply costs one slot against your per-minute rate limit and nothing against your daily allowance, so keeping a copy current is cheaper than fetching it again.

Where this is written up

Caching and refreshing/en/caching Firearms endpoints/en/api/firearms

Where a record comes from

A record is written and reviewed before it is published, and our checks decide whether it ships at all. Publishing moves its version and its last-changed date, which are the two values you can hold a cached copy against.

DiagramWhat a published record has been through

100%

flowchart LR
  record["A record is written<br/>and reviewed"] --> checks{"Checks pass?"}
  checks -->|"no"| held["Held back, not published"]:::fail
  checks -->|"yes"| published["Published to the catalog"]:::ok
  published --> stamp["Its version and date move"]
  stamp --> api["REST API"]
  api --> sdk["TypeScript and Python SDKs"]
  api --> mcp["Hosted MCP server"]

What a published record has been throughA record is written and reviewed before it is published, and it is only published once our checks pass - anything that fails them is held back rather than shipped. Publishing moves that record's version and its last-changed date, which are the two values you can compare a cached copy against. The REST API serves what was published, and the SDKs and the hosted MCP server serve what the API serves.

Where this is written up

How this is kept honest/en/verified Data quality/en/quality/overview

How a change reaches you

Nothing polls on your behalf. A change to a record is recorded and sent on within fifteen minutes, matched against the events you subscribed to - so it reaches you even if your endpoint was down when it happened, because a failed delivery is retried and then kept for you to replay.

DiagramHow a change reaches your endpoint

100%

flowchart LR
  change["A record changes"] --> recorded["Recorded, and sent on<br/>within 15 minutes"]
  recorded --> matched["Matched to your subscriptions"]
  matched --> post["Signed POST to your endpoint"]
  post --> ok{"Your endpoint answers 2xx?"}
  ok -->|"yes"| done["Delivered"]:::ok
  ok -->|"no"| retry["Retried at 1, 5 and 15 minutes"]:::warn
  retry --> post
  retry --> still{"Still failing?"}
  still -->|"yes"| failed["Left failed, yours to replay"]:::fail

How a change reaches your endpointWhen a record changes, the change is recorded and sent on within fifteen minutes - you do not poll for it. It is matched against the events you subscribed to, and each matching endpoint gets a signed POST. A 2xx reply completes the delivery; anything else is retried after one, five and fifteen minutes, and a delivery still failing after that is left failed for you to inspect and replay.

Where this is written up

Data change webhooks/en/webhooks Webhook endpoints/en/api/me-webhooks

An assistant calling the API

The hosted MCP server holds no data and no credentials of its own: it forwards your key and marks the call as coming from MCP. That mark can only lower your limits, which is what makes the smaller MCP allowance inside your plan possible.

DiagramA tool call through the hosted MCP server

100%

flowchart LR
  agent["Your assistant"] --> server["Our MCP server"]
  server --> key["Forwards your own API key"]
  key --> api["REST API"]
  api --> plan{"Plan's daily allowance left?"}
  plan -->|"no"| capped["Refused: 429 DAILY_CAP_EXCEEDED"]:::fail
  plan -->|"yes"| sub{"MCP allowance left?"}
  sub -->|"no"| mcpcap["Refused: 429 MCP_DAILY_CAP_EXCEEDED"]:::fail
  sub -->|"yes"| answer["Answered, and counted<br/>as one request"]:::ok

A tool call through the hosted MCP serverYour assistant calls our MCP server, which holds no data and no credentials of its own: it forwards your API key and calls the same REST API you would. Your plan's daily allowance is checked first and refuses with DAILY_CAP_EXCEEDED, then the smaller MCP allowance inside it refuses with MCP_DAILY_CAP_EXCEEDED. A call that passes both is answered and counted as one request on your plan.

Where this is written up

MCP overview/en/mcp/overview MCP limits/en/mcp/limits

Why the samples work

The snippet on a reference page is not an illustration. CI installs the published SDK, runs that exact snippet against production, and publishes what happened - passes and failures alike - which is what the badge under each sample is reporting.

DiagramHow a printed sample is proven

100%

flowchart LR
  page["A docs page<br/>prints a sample"] --> run["We run that sample<br/>against production"]
  run --> result{"Did it work?"}
  result -->|"yes"| pass["Recorded as passed"]:::ok
  result -->|"no"| fail["Recorded as failed"]:::fail
  pass --> badge["Shown under the sample"]
  fail --> badge

How a printed sample is provenA docs page prints a sample. We install the published SDK into a fresh project, write that sample exactly as the page shows it, and run it against production. Whether it passed or failed is recorded either way, and that last real run is what the badge under the sample and the verification page are showing - so a sample that has stopped working says so instead of looking fine.

Where this is written up

Example verification/en/api/verification Endpoint health/en/api/health