Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: GunSpec.io Firearms 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 (159 KB total) ---
# Full source: https://artifacts.apis.io/gunspec-io/openapi/gunspec-io-firearms-api-openapi.yml