Your first golf club API request with curl

All you need for a first request is an API key and one curl command. A Free account's test key (sk_test_…) reads a small fixed sample of drivers, mini-drivers and fairway woods, so your responses will match the ones below.

Get a test API key

Create a Free account at console.golfapi.dev. The Free plan includes 1,000 test requests a month and 60 requests a minute per key, and needs no card. Save the key in an environment variable in the terminal you will use. Put your key between the single quotes:

export GOLFDEV_API_KEY='sk_test_...'

Request one driver from the drivers list

The drivers list returns records newest first. Ask for one:

curl 'https://api.golfapi.dev/drivers?limit=1' \
  -H "Authorization: Bearer $GOLFDEV_API_KEY"

Leave $GOLFDEV_API_KEY as written; the shell replaces it with your key. A 401 with the message "Empty bearer token" means the variable is not set in that terminal.

Response with a test key on 3 November 2026, cursor shortened. This record has no variants yet:

{
  "data": [
    {
      "id": "clb_01M5CT01FAVETRE90QN4TMTKQG",
      "slug": "zxi-rkt-ls-driver",
      "name": "ZXi RKT LS Driver",
      "club_type": "driver",
      "summary": "ZXi RKT LS Driver is Srixon's 2026 driver, in the ZXi family.",
      "manufacturer": { "slug": "srixon", "name": "Srixon" },
      "family": { "slug": "zxi", "name": "ZXi" },
      "release_year": 2026,
      "released": "2026-10-16",
      "adjustable_hosel": true,
      "hosel_summary": { "adjustable": true },
      "url": "https://api.golfapi.dev/drivers/zxi-rkt-ls-driver",
      "updated_at": "2026-10-20T14:04:22Z"
    }
  ],
  "page": { "limit": 1, "has_more": true, "catalog_complete": false, "next": "cur_eyJ5IjoyMDI2…" }
}

Read a driver record

A driver record has three kinds of field:

• Identity. id (clb_…) never changes; store it. slug is readable and can change when a name is corrected.
• Summary fields. lofts_deg and hands list every loft and hand across the record's variants.
• Variants. Each driver variant identifies one hand, loft_deg and market, with its own id (var_…). The ZXi RKT LS Driver has no published variants yet, so variants, lofts_deg and hands are absent. GET /drivers/qi4d-driver returns a record with seven variants.

A field with no published value is left out of the record. Show it as Not published. Handle missing specifications covers the rule in code.

Read the response headers

Add -i to the request to see the headers. Log these three:

golfapi-version: 2026-10-02
golfapi-request-id: req_01M6H0T8Q1JSV78HYK4Z27CGTB
ratelimit-remaining: 59

golfapi-version is the response version; 2026-10-02 is the only one served. golfapi-request-id identifies the request; include it when you report a problem. ratelimit-remaining is the number of requests the key has left in the current minute.

Narrow the response with fields and filters

fields returns only the top-level fields you name; id is always included:

curl 'https://api.golfapi.dev/drivers?fields=id,name,release_year,lofts_deg&limit=2' \
  -H "Authorization: Bearer $GOLFDEV_API_KEY"

{
  "data": [
    { "id": "clb_01M5CT01FAVETRE90QN4TMTKQG", "name": "ZXi RKT LS Driver", "release_year": 2026 },
    { "id": "clb_01M5CT01FAK1D58Y0453W8332H", "name": "ZXi RKT Max Driver", "release_year": 2026 }
  ],
  "page": { "limit": 2, "has_more": true, "catalog_complete": false, "next": "cur_eyJ5IjoyMDI2…" }
}

A filter such as manufacturer takes a slug. The test sample has five PING drivers:

curl 'https://api.golfapi.dev/drivers?manufacturer=ping&fields=id,name,hands&limit=5' \
  -H "Authorization: Bearer $GOLFDEV_API_KEY"

{
  "data": [
    { "id": "clb_01M5CT01ACY59WENN7SNRR7T2Z", "name": "G Le4 Driver", "hands": ["rh", "lh"] },
    { "id": "clb_01M21M6H7P2WBY4E4DGH8K9SF6", "name": "G440 K Driver", "hands": ["rh", "lh"] },
    { "id": "clb_01M21M6K0XK5KVT2559D7E7XAM", "name": "G440 SFT Driver", "hands": ["rh", "lh"] },
    { "id": "clb_01M21M6JCVMHZZNDFDFDSBTQDE", "name": "G440 Max Driver", "hands": ["rh", "lh"] },
    { "id": "clb_01M21M6HW9R83GY6Z66A4ESVKA", "name": "G440 LST Driver", "hands": ["rh", "lh"] }
  ],
  "page": { "limit": 5, "has_more": false, "catalog_complete": false }
}

has_more: false means this is the last page. When it is true, send page.next back unchanged as cursor, with the same filters, to get the next page.

Read the full catalog with a live key

A live key (sk_live_…) sends the same requests to the full catalog, which has many more drivers and seven club types. Ids differ between the test sample and the live catalog, so do not keep test-key ids. The quickstart covers the remaining setup. Next, build a club comparison or keep a stored catalog current.

With the MCP server connected, the same first request is a prompt. Ask the assistant to "List three 2026 drivers", and it calls search_clubs on the drivers list. A Free account's test key answers it, because the sample holds every 2025 and 2026 driver.