GolfAPI Driver Catalog — API Reference

Unlisted API reference. Current behavior version: 2026-09-24. Club documents reuse the published 2026-09-15 representation. Check /coverage for the live build and counts.

What this API is

A catalog of golf drivers from major manufacturers. It exists to answer two questions: which club is this, and what exact build did the manufacturer offer.

It is deliberately positioned for programmatic consumers, including AI agents, rather than for a human browsing a website.

Product tiers

The omission rule

This is the central data contract and it matters when you evaluate the responses. An absent field means no value was published for that record. It may still be awaiting curation; it is not a verified negative. A value only appears after a human has signed off on it. Nulls and placeholders are not used, so you will see objects with fields simply missing rather than set to null.

A real 0 or false is always returned, never dropped. "adjustable_weight": false means verified as not adjustable.

What is in the published catalog

GET /coverage is the live census for the key you send. It names the published build, publication time, club types, manufacturer-by-year counts, and per-field presence. Read it before presenting a search miss as proof that a club does not exist. A year missing from the grid means no record is published for that manufacturer and year; it does not establish that the manufacturer released nothing.

curl -sS https://clubapi.golfapi.dev/coverage \
  -H "Authorization: Bearer $GOLFDEV_API_KEY"

For a driver list filtered by profile, inspect page.profile_coverage. Its counts cover published drivers for the requested manufacturer, or all published drivers when no manufacturer was requested. Other filters do not narrow that denominator. At the 2026-09-24 pin, all_published_records_classified says only that those published records have profiles; catalog_complete: false says the eligible lineup is not certified complete. An empty result cannot establish that a manufacturer made no driver with that profile. Older pins call the first flag complete; it has the same limited meaning.

intro_price is a historical launch MSRP when present. A missing price or profile is an unpublished value, not a verified negative. A real false or 0 is always retained. The current release offers driver identification and core specifications; detailed hosel charts and equipment are separate gated releases.

The launch target is every qualifying US retail driver head from the 11 named manufacturers between 2020-01-01 and 2026-09-15. The published grid is the current subset, not a completion claim. Mini-drivers are a separate resource and have no profile filter.

That target is machine-readable. GET /coverage carries catalog_complete: false and, on the driver entry, a scope naming those 11 manufacturers and the two dates. Read it before treating any count here as a denominator. What the census can establish is what this build published; what it cannot establish is why a head is absent — it counts published records, so a head that was never released and a head not yet ingested are the same zero. A search miss, an empty page and a 404 are all statements about the published build.

Two notes for anyone syncing

updated_at is a record modification timestamp, not a build timestamp. Use it for incremental syncs within one representation shape. When you change the Golfapi-Version pin, perform a full resync; a version change does not guarantee every record's timestamp changes.

Connecting

curl -H "Authorization: Bearer $GOLFDEV_API_KEY" \
  "https://clubapi.golfapi.dev/drivers?manufacturer=ping&limit=2"

Routes

The equipment routes are entitlement-gated like every other resource. No key issued for evaluation carries them, so what you will see is 403, not 503. A key that does carry the entitlement gets 503 until the catalog is published: that is the designed pre-release state, not an outage. Branch on the status you actually receive — 403 means buy the entitlement, 503 means retry later.

/health and what it means

/health is unauthenticated and is not a liveness check for the whole service. It answers 503 only when nothing can be served: the database is unreachable or unbound, a registered club type's table is missing, or the live build holds no document for the default shape.

A shape whose columns were migrated but which no build ever materialized is reported as degraded at 200. Do not page on it, and do not read it as a warning to clients: catalog resolution skips an unmaterialized shape, so a pin at one resolves down to the shape below it and is answered 200 naming that shape in Golfapi-Version. Nothing in degraded produces a 503. Until 2026-09-22 a 2026-09-14 pin on /drivers did answer 503, with Retry-After: 3600 on a shape no retry would ever produce; that is fixed.

/health is read from the live build at request time and has been observed answering degraded for a few minutes after a publish that cleared it. Re-probe before acting on it.

GET /health

{ "ok": true, "db": "ok", "request_id": "req_…" }

The absence of degraded is the machine-readable answer to "did the live build materialize every shape its tables carry". GET / answers the client-facing question separately: version.serving at the top, and a serving date on each entry of resources[]. Nothing automated compares the two; this page previously claimed they were checked against each other on every release, and they were not.

Query parameters

List routes

Detail routes

Response shapes

List — wrapped

GET /drivers?limit=1&manufacturer=ping

{
  "data": [
    {
      "id": "clb_01M21MDKGYVNWAT3EFJ9XCE0PC",
      "slug": "g440-k-driver",
      "name": "G440 K Driver",
      "manufacturer": { "slug": "ping", "name": "PING" },
      "family": { "slug": "g440", "name": "G440" },
      "profile": "neutral",
      "released": "2026-01-29",
      "lofts_deg": [9, 10.5, 12],
      "hands": ["rh", "lh"],
      "volume_cc": 460,
      "adjustable_hosel": true,
      "adjustable_weight": true,
      "weight_system": "movable",
      "intro_price": [
        { "market": "US", "msrp_minor": 70500, "currency": "USD" }
      ],
      "url": "https://clubapi.golfapi.dev/drivers/g440-k-driver",
      "hosel_summary": { "adjustable": true },
      "updated_at": "2026-09-21T20:42:39Z"
    }
  ],
  "page": { "limit": 1, "has_more": true, "next": "cur_eyJyIjoi..." }
}

Prices are minor units. 70500 with "currency": "USD" is $705.00. The last two fields arrived with the 2026-09-15 shape; a request pinned below it receives the same record without them.

The price is the figure the manufacturer stated, not a normalized one. Nothing is rounded and no cents are invented, so both encodings you will see are exact: a head announced at $649.99 carries 64999 and one announced at $649 carries 64900. Both whole-dollar and 99-cent prices occur — Qi4D at 64999, the Titleist GT heads at 64900, G440 K at 70500. A trailing 00 is a whole-dollar launch price, never a truncated one.

Lists are ordered. Every list route returns released descending with the clb_ id descending as the tiebreak, and there is no sort parameter. ?q= is the one exception: it orders by relevance first and keeps the same tiebreak under it. Pagination is keyset over that order, so a cursor is only valid for the filter set that produced it.

Only id is required in the OpenAPI schema, and that is about fields=, not about the data. Projection can narrow a response to any subset, so a literal required list would be wrong for every projected response. The unprojected set is published instead as x-required-unprojected on each schema — 13 keys on the basic club document, 15 at 2026-09-15, 21 expanded. Code generators ignore vendor extensions, so a generated client will null-check name, slug, manufacturer and released; none of those has ever been absent from a published record. The two fields that genuinely can be absent are profile and intro_price, and the table above says where.

Detail — not wrapped

GET /drivers/g440-k-driver

{
  "id": "clb_01M21MDKGYVNWAT3EFJ9XCE0PC",
  "slug": "g440-k-driver",
  ...
  "url": "https://clubapi.golfapi.dev/drivers/g440-k-driver"
}

The detail route returns the object at the top level. It is not wrapped in data the way list responses are. Clients must handle both shapes.

Basic vs Club-builder depth

The same club, fetched with two different keys:

Errors

Every error uses the same envelope, with a request_id and an optional param naming the offending input.

{
  "error": {
    "type": "invalid_request",
    "message": "Invalid value for 'limit': must be between 1 and 100.",
    "status": 400,
    "request_id": "req_01M2R68V6A5K9J0A5HQWJB2N2P",
    "param": "limit"
  }
}

Observed error messages: "Unknown field 'nope' for view 'basic'." · "Invalid cursor. Use the 'next' value from a previous page unchanged." · "No driver with slug 'no-such-club'."

Versioning, caching, redirects

• Pin Golfapi-Version: 2026-09-24 to get the current list behavior. Existing keys keep their assigned pin unless they send this header. The 2026-09-24 club document uses the published 2026-09-15 representation; this release changes list search, filter validation, and coverage metadata.
• The response's Golfapi-Version names the shape served. A requested date between releases, or later than the newest release, resolves down to the newest available shape. A pin below 2026-09-08 or an impossible date is 400. The 2026-09-14 club document was never populated, so a pin there resolves to 2026-09-08.
• BasicClub in OpenAPI names the 2026-09-08 version, while NormalClub names the 2026-09-15 document used by the current version. view=basic|expanded is a separate depth choice. Follow the response schema's anyOf. OpenAPI info.version is a release number, not a Golfapi-Version date.
• A legacy pin may serve a smaller catalog: heads with weight_system: reversible are excluded from the 2026-09-08 shape because it cannot name that mechanism. /coverage reports the count at the served shape.
• Responses carry an ETag. A matching If-None-Match returns 304, and so does If-None-Match: *. A list tag is a SHA-256 of the response body. A detail tag is opaque and its shape depends on the version you are served. At 2026-09-15 a plain GET /drivers/g440-k-driver carries "driver-20260915-normal-<sha256>~20260915~vb"; at 2026-09-08 the same request carries "clb_<id>-<epoch>~vb". Three parts, and none of them is a contract: a record tag, then ~ and the shape date with its dashes removed on any shape from 2026-09-14 up, then ~ and an encoding of the representation when the request shaped it (view, fields, variants, market) — ~vb, ~vb.mUS. This page described the record tag as "{id}-{modified epoch}" and named neither of the other two parts until 2026-09-21, so a client written against it and pinned to the current version saw a tag it could not parse. Do not parse any of it: send the whole quoted string back in If-None-Match and nothing else. Cloudflare's edge marks the tag weak (W/"…") when it compresses the response; the API accepts either form.
• A 401 carries WWW-Authenticate: Bearer when the Authorization header is absent and Bearer error="invalid_token" when a credential was sent. It carries no RateLimit-* headers: the limit belongs to a key, and an unaccepted request has none.
• A changed slug returns 301 to the current path. An id never redirects — ids are stable, slugs are not. Test it against /drivers/g440-max-2025-driver, which redirects to /drivers/g440-max-driver.
• A clb_ id is case-insensitive in its 26-character suffix, because Crockford base32 is. clb_01j8… and clb_01J8… are one id: the same document, the same ETag, no redirect. Slugs are genuinely case-sensitive and stay lowercase; /drivers/G440-MAX-DRIVER is a 404 whose message names the lowercase form.
• Golfapi-View names the depth of a document: it is meaningful on a catalog response that serves or revalidates one (200, 304), and on anything else it carries no contract, because an error carries no document. Branch on error.type and the status, not on this header. The two ways of reaching a depth differ: view=expanded asked for by name without the capability is 403, while an omitted detail view at the current shape serves basic and answers 200. Read the header instead of inferring depth from what you sent.
• A path with a trailing slash is normalized: GET /drivers/ is 301 to /drivers, query string preserved, never a 404. It resolves before authentication, so it costs the key nothing.
• Every response carries Golfapi-Request-Id, the same req_… value an error body carries. Quote it in a report about a 200 or a 304.
• A 304 is refunded and does not count against the rate limit. Its RateLimit-Remaining reports the budget after that refund, so a revalidating client sees a counter that holds still because it is not spending, not because it is stuck.
• A 503 from a version pin is not a blip: it clears when an operator publishes a build, which can take days. Retry-After on it is an hour-long hint, not a promise — cap your own backoff and poll /health, which names the shapes the live build is missing.
• Rate limit: 60 requests per 60-second window, aligned to the wall-clock minute. RateLimit-* headers appear only once a key has been accepted and the request has entered an authenticated resource — a 401, a 405, /health and / carry none, because the limit belongs to a key and those responses have not got one. The counter is per key, not per client: if two processes share a key, RateLimit-Remaining moves without either one seeing the other's traffic. Use a separate key per evaluation when you need an isolated observation. Retry-After appears on 429 and on 503, and nowhere else. Check RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds left in the window, never 0). Over the cap is 429 with Retry-After equal to RateLimit-Reset. HTTP header names are case-insensitive, but these are the names the API sends; this page lowercased them until 2026-09-22. GET / carries the same two numbers under rate_limit, so you need not spend a request to learn them.

Known gaps

Stated plainly so evaluation focuses on what matters rather than rediscovering these:

• profile and intro_price are incomplete. Read the current counts in /coverage. Every profile-filtered driver page reports its published-record denominator. catalog_complete: false means even unclassified: 0 does not prove the eligible lineup is complete.
• market is effectively a constant: US is the only market the build prices, and any other well-formed code is 400. Do not build a currency abstraction against it yet.
• /shafts, /grips, /weight-systems each need an explicit equipment grant. They are unpublished: an entitled key receives 503 with Retry-After. A 403 proves only that this key lacks that resource grant.
• /hosel-systems and view=expanded require the Club-builder entitlement. Expanded club documents are available to entitled keys; the separate hosel-system catalog is unpublished and returns 503 to an entitled key.
• List responses are wrapped in data with a page object beside it; a detail response is the bare club document. They are different envelopes, so a client cannot share one parser across the two routes.
• An ETag belongs to a URL, not to a record. market=US changes no bytes today — US is the only priced market — but it is part of the representation, so it still moves the detail tag (the ~…mUS suffix). Store the whole quoted tag against the exact URL you fetched, and do not carry one between two spellings of the same request.
• 429 and its Retry-After are documented but rarely exercised; the limit is 60 per wall-clock minute.

Testing etiquette

This is a live production service on a small budget. Probe correctness and edge cases freely; keep total requests modest and do not load-test, benchmark throughput, or run concurrent floods. Rate limiting will stop you at 60 per 60-second window regardless.