gunspec-io Firearm Discovery API

openapi: 3.2.0
info:
  title: GunSpec.io Firearm Discovery API
  version: 1.1.0
  description: 'Comprehensive firearms specification database API. ## Authentication


    All `/v1` endpoints accept an API key via **`X-API-Key`** header or **`Authorization: Bearer `**. Some endpoints are accessible without a key (anonymous tier), while others require a minimum subscription tier. The tier required by each endpoint is stated in its description. ## Plans and limits


    | Tier | Price | Requests/month | Daily cap | Rate limit | Max page depth |

    |------|-------|----------------|-----------|------------|----------------|

    | Explorer | $0 | 200 | 50 | 10/min | 5 |

    | Builder | $29/mo | 25,000 | 5,000 | 60/min | 25 |

    | Studio | $79/mo | 150,000 | 10,000 | 120/min | Unlimited |

    | Enterprise | $249/mo | 1,000,000 | 50,000 | 300/min | Unlimited |


    **Explorer**: For evaluation and testing

    - 200 requests/month

    - 10 requests/min

    - Try any endpoint up to Studio with 50 one-time credits

    - Basic fields

    - 5 pages max


    **Builder**: For indie developers and side projects

    - 25,000 requests/month

    - 60 requests/min

    - Full specs

    - Compare endpoint

    - 25 pages max


    **Studio**: For production applications

    - 150,000 requests/month

    - 120 requests/min

    - All endpoints

    - Unlimited pages

    - Priority support


    **Enterprise**: For high-volume use, and for retailers advertising stock across the catalog

    - 1,000,000 requests/month

    - 300 requests/min

    - All endpoints

    - Unlimited pages

    - Seller listing on every part and firearm you stock

    - Your logo, price and stock, linking to your own checkout

    - Listed in the API too, so partner sites carry your offers

    - Price in your own currency, shown to the regions you ship to

    - Dedicated support

    - SLA


    Anonymous requests (no API key) are treated as Explorer with a 50 request/day cap. ## Rate Limiting


    Three limits can refuse a call with `429`. The per-minute limit returns `RATE_LIMITED` with `Retry-After: 60`. The daily limit, counted per key, returns `DAILY_CAP_EXCEEDED`: nothing is served until it resets at midnight UTC, `Retry-After` is the seconds left until then (at most 86,400), and the body carries `error.limit`, `error.resetsAt` (an ISO 8601 instant) and `error.retryAfter`. The monthly allowance, which is the plan''s requests per month and belongs to the whole account (every key draws on one pool), returns `MONTHLY_CAP_EXCEEDED` in the same shape, with `Retry-After` up to 2,678,400 and the reset at midnight UTC on the first of next month. Only calls that were served spend the month: a call a limit refused, and a `304`, do not. Whichever limit is reached first refuses, and when both are, the monthly one is the one reported because it lasts longer. What is left of the **day** and of the **month** is sent on every response, so a script never has to ask. Every `/v1` response on a plan with a daily limit carries `X-Daily-Limit`, `X-Daily-Remaining` and `X-Daily-Reset` (the UTC midnight it rolls over at, as an ISO 8601 instant), a response to a call made with a key also carries `X-Monthly-Limit`, `X-Monthly-Remaining` and `X-Monthly-Reset` (midnight UTC on the first of next month), and a call through the hosted MCP server carries `X-Daily-MCP-*` beside them. A plan with no daily limit sends none of them. `Remaining` is what is left after the call that returned it, so the response that reports `0` is the last one that will be served: stop there and resume at `Reset`. Treat `Remaining` as a figure to pace against rather than settle on: it is served from a short cache while you are well under the limit and read live once you are near it, so it can read high by about a minute of traffic early in the day. `GET /v1/me/usage` is the figure to reconcile against, and the one that shows every key at once. Stop at the first `DAILY_CAP_EXCEEDED`. A call made after it is refused too and still counted, and a free key that keeps calling after being refused is paused (`403` with `KEY_ON_HOLD` and a `Retry-After`) until the limit resets or the account moves to a paid plan. Signing in, the portal and billing are not affected by a pause.'
  contact:
    name: GunSpec.io
    url: https://gunspec.io
  license:
    name: Proprietary
    url: https://gunspec.io/terms
servers:
- url: https://api.gunspec.io
  description: This API
tags:


# --- truncated at 32 KB (111 KB total) ---
# Full source: https://artifacts.apis.io/gunspec-io/openapi/gunspec-io-firearm-discovery-api-openapi.yml