gunspec-io Health API

openapi: 3.2.0
info:
  title: GunSpec.io Health 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:
- name: Health
  description: Health and readiness checks
paths:
  /health:
    get:
      tags:
      - Health
      summary: Health check
      description: Liveness probe. Answers 200 whenever the API worker is running, and deliberately does not touch the database, so it stays green through a database incident. Use `/ready` to know whether requests will succeed. No authentication, no rate limit, and a flat body rather than the `{ success, data }` envelope.
      operationId: getHealth
      security: []
      responses:
        '200':
          description: The API worker is running
          headers:
            Cache-Control:
              description: 'Always `no-cache`: the answer is computed on every call, so a monitor never reads a stale one.'
              schema:
                type: string
                example: no-cache
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - timestamp
                - version
                - environment
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                    example: ok
                    description: Always `ok`. Getting an answer at all is the signal; there is no degraded value.
                  timestamp:
                    type: string
                    format: date-time
                    example: '2026-09-11T07:35:44.688Z'
                    description: When the probe answered, ISO 8601 UTC. A value that does not move between calls means something in between is caching the reply.
                  version:
                    type: string
                    example: v1
                    description: 'The API version every endpoint is served under: the `v1` in `/v1/...`. Not a build number.'
                  environment:
                    type: string
                    enum:
                    - production
                    - staging
                    - development
                    example: production
                    description: 'Which deployment answered: `production` (api.gunspec.io), `staging`, or `development` for a worker running locally.'
  /ready:
    get:
      tags:
      - Health
      summary: Readiness check
      description: 'Readiness probe. Runs one query against the database: 200 `ready` when it answers, 503 `not_ready` when it does not, so a load balancer or status page can tell "the API is up" from "the API can serve data". No authentication, no rate limit, and a flat body rather than the `{ success, data }` envelope.'
      operationId: getReady
      security: []
      responses:
        '200':
          description: The database answered the probe query
          headers:
            Cache-Control:
              description: 'Always `no-cache`: the answer is computed on every call, so a monitor never reads a stale one.'
              schema:
                type: string
                example: no-cache
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - database
                properties:
                  status:
                    type: string
                    enum:
                    - ready
                    example: ready
                    description: Always `ready` on a 200.
                  database:
                    type: string
                    enum:
                    - connected
                    example: connected
                    description: The database answered the probe query.
        '503':
          description: The database did not answer the probe query
          headers:
            Cache-Control:
              description: 'Always `no-cache`: the answer is computed on every call, so a monitor never reads a stale one.'
              schema:
                type: string
                example: no-cache
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - database
                properties:
                  status:
                    type: string
                    enum:
                    - not_ready
                    example: not_ready
                    description: Always `not_ready` on a 503.
                  database:
                    type: string
                    enum:
                    - disconnected
                    example: disconnected
                    description: The probe query failed or the database could not be reached. Requests that read the catalog fail until it recovers; retry after a short wait.
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key passed via X-API-Key header
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key passed via Authorization: Bearer header'