GunSpecDOCS
API Documentation

GunSpec API

Everything you need to integrate firearms specification data into your app, game, or research project. 98 REST endpoints, free tier, and detailed response schemas.

Base URLhttps://api.gunspec.io
Get API Key

Quick Start

Grab a free API key and pick where to start. No setup required to read the public data.

Make your first request

1

List Firearms

bash
curl https://api.gunspec.io/v1/firearms
2

Search

bash
curl "https://api.gunspec.io/v1/firearms/search?q=glock"
3

Get Details

bash
curl https://api.gunspec.io/v1/firearms/glock-17-gen5

Authentication

All API endpoints require authentication. Pass your API key via the X-API-Key header. Sign up for a free Explorer key to get started. Higher tiers unlock additional endpoints like search, detail, compare, images, and game stats.

No Auth Required

Browse firearms, search, view specs, and list categories

API Key

Higher rate limits, compare, images, and game stats

Using API Keys

Include your API key in the X-API-Key header:

cURL
curl -H "X-API-Key: your_api_key" \
  https://api.gunspec.io/v1/firearms

Pagination

List endpoints return a fixed-size page of results wrapped in a consistent envelope. Request more with page and per_page (a few endpoints use limit instead).

Paginated response
json
{
  "success": true,
  "data": [ /* items */ ],
  "pagination": { "page": 1, "limit": 20, "total": 137, "totalPages": 7 }
}

Use page (1-based) and per_page to walk pages, and read pagination.totalPages to know when to stop. The official SDKs expose listAutoPaging to iterate every page for you.

Versioning

Every endpoint is namespaced under /v1. We add fields and endpoints without bumping the version; breaking changes ship under a new prefix (such as /v2) and are announced in the changelog first. Pin to /v1 and treat unknown fields as optional.