GunSpec
Schnellstart

GunSpec API

Alles, was du brauchst, um Waffendaten in deine App, dein Spiel oder dein Forschungsprojekt zu integrieren: eine REST-API mit kostenlosem Tarif, typisierten SDKs und einer Live-Konsole.

Basis-URLhttps://api.gunspec.io
API-Key holen
  • 8,630Waffen
  • 939Hersteller
  • 559Kaliber
  • 160Operationen auf 151 Pfaden

160 Operationen auf 151 Endpunkten: ein Pfad, der GET und PUT beantwortet, ist ein Endpunkt und zwei Operationen, deshalb stimmen die beiden Zahlen nie überein. Die Referenz zählt Operationen; SDKs, Agenten-Pakete und Website zählen Endpunkte.

Vier Schritte zur ersten Antwort

Zehn Minuten von nichts zu einer Liste von Waffen im Terminal, mit den Ablehnungen, die unterwegs kommen, erklärt, bevor sie kommen.

  1. 1

    Kostenlosen Schlüssel holen

    Jeder Katalogaufruf trägt einen Schlüssel; 28 Operationen antworten ohne, aufgelistet auf der Authentifizierungsseite. Ein kostenloser Explorer-Schlüssel dauert eine Minute und reicht zum Entwickeln. Sende ihn als X-API-Key oder als Authorization: Bearer. Beides funktioniert überall.

    Anfragen / Monat
    200
    Anfragen / Min
    10
    Anfragen / Tag
    50
    Seiten tief
    5
    API-Key holenTarife vergleichen
  2. 2

    Erste Anfrage stellen

    Der List-Endpunkt ist der richtige Einstieg: keine Argumente, antwortet auf jedem Tarif und zeigt die Hülle, die jede andere Liste nutzt. per_page=3 hält die Ausgabe kurz.

    cURL
    curl -H "X-API-Key: your_api_key" \  "https://api.gunspec.io/v1/firearms?per_page=3"
    In der Try-It-Konsole ausführenOder in Swagger UI
  3. 3

    Antwort lesen

    Jeder JSON-Erfolg unter /v1 ist dieselbe Hülle: success, data und bei einer Liste pagination. Zwei Dinge stehen absichtlich außerhalb: die Prüfpunkte /health und /ready antworten mit einem flachen { status }-Körper, weil ein Load Balancer sie liest und nie ein Client; und eine Handvoll Operationen antwortet stattdessen mit einer Datei oder einer Weiterleitung: das Geschossdiagramm, die Rohdownloads von Medien und 3D-Modellen sowie der 302 des Händler-Klickzählers. Die Medienseite listet sie auf. Das Beispiel unten ist, was ein Explorer-Schlüssel tatsächlich erhält: 5 Felder pro Zeile, gebaut aus den Beispielen der Spezifikation.

    GET /v1/firearms auf Explorer
    json
    {  "success": true,  "data": [    {      "id": "glock-g17-gen5",      "name": "Glock 17 Gen5",      "manufacturerId": "glock",      "updatedAt": "2026-09-10 06:42:19",      "version": "a3f1c2d4e5b6a7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2"    },    /* two more rows */  ],  "pagination": {    "page": 1,    "per_page": 3,    "limit": 3  }}
    • data ist eine Seite. Den Rest mit page durchlaufen und bei einer kurzen Seite stoppen; die Paginierungsseite hat die Schleife, die auf jedem Tarif funktioniert.
    • pagination.total und totalPages fehlen auf Explorer: der kostenlose Tarif sieht nicht, wie groß der Katalog ist. Ab Builder erscheinen sie.
    • Explorer-Zeilen tragen 5 Felder. Der volle Datensatz, samt Maßen, Ballistik, Materialien und Medien, steht in der Feldreferenz und wird mit einem bezahlten Tarif freigeschaltet.
  4. 4

    Ablehnung behandeln

    Eine abgelehnte Anfrage ist dieselbe Hülle mit success: false und einem error mit stabilem code, konkretem reason, Nachricht und request_id. Diese vier trifft eine erste Integration, in dieser Reihenfolge.

    • 401KEY_MISSING

      No API key was sent. Send your key in the X-API-Key header.

    • 403PLAN_REQUIRED

      The credential is valid and its plan is below what this endpoint needs. details.requiredTier names the plan. Upgrade the plan. A new key on the same plan will get the same answer.

    • 429RATE_LIMITED

      Too many requests this minute for the plan. Wait for Retry-After seconds, then retry.

    • 429DAILY_CAP_EXCEEDED

      The plan's daily request allowance is used up. It resets at midnight UTC. Wait for the reset, or upgrade for a larger allowance.

    • 429MONTHLY_CAP_EXCEEDED

      The plan's monthly request allowance is used up. It resets at midnight UTC on the first of the month. Calls a limit refused do not count towards it. Wait for the reset in Retry-After, error.resetsAt or X-Monthly-Reset, or choose a larger plan, which raises the allowance at once.

    Jeder Code und jeder Grund

Wähle deinen Weg

Wohin es weitergeht, hängt davon ab, was du baust. Jede Karte ist eine Seite.

How the data is kept right

You are building on figures we publish, so you should be able to see how they are checked. Every record is read against its sources and the physics of what it describes, questions about it are answered with quoted evidence, and all of that work is public.

Die Grundlagen

Acht Dinge, die jede Integration trifft, je eine Zeile. Die verlinkte Seite hat den Rest.