Content

Latest contract check run

Every documented operation is called against this API on a schedule and held against this document: the status, the media type, the schema, the envelope, the fields promised against the fields sent, the cache contract, and the plan gates. This returns the most recent run, with the verdict for each operation, the checks that failed, and what happened when each gate was exercised with a key above it, at it and below it.

This is not uptime. Whether the API is answering is GET /health and the status page; this is whether what it answers is still what the reference promises, which a perfectly available deploy of last week's code gets wrong.

No API key required.

get/v1/contract

Request

  • Base URL: https://api.gunspec.io
  • URL: https://api.gunspec.io/v1/contract
  • Auth: one of:
    • none
    • API key in header X-API-Key
    • HTTP bearer

Query parameters

env'production' | 'staging' | 'local'

Which environment to report. Production unless asked otherwise; a staging run is never mixed into it.

surface'api' | 'mcp' | 'fitment' | 'catalogue' | 'integrity' | 'plausibility' | 'anomalies' | 'cartridges' | 'materials' | 'corroboration' | 'sources' | 'manufacturers' | 'links'

Which product or data suite the run measured: api for this REST API, mcp for the hosted MCP server, fitment for the attachment compatibility suite, catalogue for the catalogue record checks: every file against its schema, no company under two ids, and no firearm whose fields cannot all be true, integrity for the integrity checks: figures, prose and feature lists copied between unrelated guns, citations that are not evidence, timelines, weight against size, and confidence against evidence, plausibility for the plausibility checks: a loaded weight against the empty one and its magazine, a gun older than its cartridge, figures in the wrong unit, energy against velocity, variants that disagree with their family, and the same gun filed twice, anomalies for the statistical anomaly checks: a figure unusually far from its family's or its cohort's median, and a barrel an unusual share of its gun's length; each a figure to verify, not one shown wrong, cartridges for the cartridge checks: energy against bullet and velocity, pressure in MPa against psi, dimensions no case can have, a bullet against the calibre its name states, a cartridge older than its parent, and each load against its cartridge, materials for the materials registry: every material's density quoted from a page that still states it, within the range it declares, and every material value the catalogue uses covered, so the mass checks read sourced densities, corroboration for the corroboration checks: firearm figures compared with a second, independent source (Wikidata), sources for the source checks: how many records cite their own maker or another authority, and which heavily cited sites the source hierarchy cannot yet name, manufacturers for the manufacturer checks: every manufacturer record held against Wikidata for its website, founding year, country and whether it still trades, links for the link checks: every manufacturer website and every cited source asked whether it still answers and is still the page cited. Defaults to api.

Response

The latest run for that environment. run is null when nothing has been checked there yet, which is deliberately different from a run where everything failed.

successboolean required

Always true on a successful response. Every error carries false and an error object instead.

Example response

{
  "success": true,
  "data": {
    "run": {
      "surface": "api",
      "env": "production",
      "specVersion": "1.1.0",
      "commitSha": "9f1c2ab",
      "runUrl": "https://github.com/buun-group/gunspec/actions/runs/123456",
      "ranAt": "2026-09-13T03:15:00.000Z",
      "durationMs": 28837,
      "operations": 128,
      "passed": 110,
      "failed": 2,
      "skipped": 16,
      "tiers": [
        "studio"
      ],
      "results": [
        {
          "key": "get /v1/firearms/{id}",
          "method": "get",
          "path": "/v1/firearms/{id}",
          "tag": "Firearms",
          "tier": "explorer",
          "status": 200,
          "ms": 41,
          "verdict": "pass",
          "checks": {
            "passed": 12,
            "skipped": 2
          },
          "failures": [
            {
              "check": "schema",
              "detail": "/data/[]/id must be integer"
            }
          ],
          "access": [
            {
              "check": "tier-refuses",
              "tier": "builder",
              "verdict": "pass",
              "detail": "builder key refused 403 PLAN_REQUIRED, as `x-gunspec-tier: studio` requires"
            }
          ]
        }
      ],
      "systemChecks": [
        {
          "id": "json-not-stringified",
          "describes": "No response carries JSON inside a string.",
          "status": "pass",
          "checked": 127,
          "sample": [
            "get /v1/firearms/by-feature"
          ]
        }
      ]
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.