Documentation
13 golf data endpoints over REST and MCP. One key, credits per call.
Your first call
Sign up for a free key (500 credits, no card), swap it in for YOUR_API_KEY, and send this. list_tournaments costs 1 credit.
Request
curl -X POST https://mcp.birdieapi.com/v1/list_tournaments \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"season": 2024,
"major": true,
"limit": 3
}'Response
{
"tournaments": [
{
"tournament_id": "401580344",
"name": "Masters Tournament",
"season": 2024,
"start_date": "2024-04-11",
"end_date": "2024-04-14",
"status": "final",
"major": true,
"scoring_system": "Medal",
"rounds_scheduled": 4,
"purse": 20000000,
"field_size": 89,
...First 14 lines. Full response and every field
REST / cURL
POST to /v1/{tool_name} with your params as JSON body. No MCP client needed:
curl -X POST https://mcp.birdieapi.com/v1/list_tournaments \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY"With parameters:
curl -X POST https://mcp.birdieapi.com/v1/list_tournaments \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"season":2024,"major":true,"limit":3}'Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"birdieapi": {
"url": "https://mcp.birdieapi.com/mcp?key=YOUR_API_KEY"
}
}
}Claude Code
One command:
claude mcp add birdieapi https://mcp.birdieapi.com/mcp?key=YOUR_API_KEY --transport streamable-httpFind the right call
All 13 questions- Which tournaments were played in 2024, and who won them?list_tournaments
- What is Scottie Scheffler's player id?search_players
- What is on this week, and who is defending?get_schedule
- Full results of the 2024 Mastersget_leaderboard
- Scheffler's final round at Augusta, hole by holeget_scorecard
- Which holes played hardest at the Masters?get_course
Endpoints
13 endpoints by category. Each page has parameters, requests in three formats, a full example response and every response field.
Static reference1 credit/call
Basic lookup2 credits/call
- get_leaderboard2 creditsA tournament's full leaderboard: position, rounds, total, earnings and points
- get_course2 creditsA course as set up for a tournament: par and yards per hole and how each hole played
- get_scorecard2 creditsA player's hole-by-hole scorecard for a tournament, with par and yardage
- get_ratings2 creditsOur strokes-versus-field rating: every active player, field-strength adjusted
Stats + aggregation5 credits/call
- get_player5 creditsProfile, rating, season lines and recent finishes
- get_player_results5 creditsA player's tournaments and rounds by season, with strokes versus the field
- get_player_stats5 creditsA player's season stats: scoring, birdies, par-3/4/5 scoring, driving, greens, putting
- get_course_history5 creditsA player's record at one tournament or course, every year
- get_head_to_head5 creditsTwo players' finishes and rounds in every tournament they both played
- get_leaders5 creditsSeason leaders for any stat we compute or ESPN keeps
Reference
Authentication
Every request requires an API key. Pass it via header or query parameter:
x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
# or (MCP only)
?key=YOUR_API_KEYVerify your email, then create an API key from the dashboard. Free accounts get 500 credits.
Base URL
https://mcp.birdieapi.comREST API: POST /v1/{tool} with JSON body. Works with cURL, Python, any HTTP client.
MCP: POST /mcp via Streamable HTTP. Works with Claude Desktop, Claude Code, Cursor, and any MCP client.
Rate limits
| Credit balance | Rate limit |
|---|---|
| 100 credits or more | 60 req/min |
| Under 100 credits | 10 req/min |
The limit is the same on every plan. It is burst protection, not the spend boundary; credits are that, and they are enforced per request. Running low slows you down so you notice before the balance reaches zero.
Error handling
| Code | Meaning | What to do |
|---|---|---|
| 400 | Invalid parameters | Check required fields and value types |
| 401 | Invalid or missing API key | Check your x-api-key header |
| 402 | Insufficient credits | Top up your wallet or upgrade your plan |
| 429 | Rate limit exceeded | Wait and retry (see limits above) |
| 500 | Server error | Retry with idempotency key. Credits auto-refund on server errors. |
Pass x-idempotency-key or x-request-id headers to make retries duplicate-safe.
Data coverage
LPGA Tour (LPGA)
BirdieAPI also serves the LPGA. Pass "league": "lpga" to any tool that lists it, or connect to https://mcp.birdieapi.com/mcp/lpga. What the LPGA data covers.
LIV Golf (LIV)
BirdieAPI also serves the LIV. Pass "league": "liv" to any tool that lists it, or connect to https://mcp.birdieapi.com/mcp/liv. What the LIV data covers.
DP World Tour (DP World Tour)
BirdieAPI also serves the DP World Tour. Pass "league": "dpwt" to any tool that lists it, or connect to https://mcp.birdieapi.com/mcp/dpwt. What the DP World Tour data covers.
| Data | Status | Coverage | Volume |
|---|---|---|---|
Leaderboards and results Finishing position, ties, cut and withdrawal status, score to par, total strokes, each round, earnings and season points. | Available | PGA Tour 2001 to current | Every player in every field |
Hole-by-hole scores Strokes on each hole with par and yardage from the tournament's course setup; for pro-ams, the course each round was played on. PGA Tour only: ESPN keeps round totals, not holes, for the LPGA, LIV and the DP World Tour. | Available | PGA Tour 2001 to current | About 99% of PGA Tour rounds; the rest have round totals only |
Courses Par and yards per hole as set up for each tournament, and how each hole played. | Available | PGA Tour 2001 to current | Every tournament's setup |
Driving, greens and putting ESPN's stat line per player per tournament: driving distance and accuracy, greens in regulation, putts per green, sand saves. PGA Tour only; no strokes gained by category and no shot-level data. | Partial | PGA Tour, from 2011 | Per player per tournament |
Strokes versus the field Each round against its field's average on the same course, adjusted for field strength, and a rating after every tournament. | Available | Each tour's seasons with leaderboards (PGA Tour 2001 on; LPGA, LIV and DP World Tour with the gaps their pages list) | Full 18-hole rounds in fields of ten or more |
Coverage describes the datasets BirdieAPI supports. Freshness and operational health are tracked separately.
Odds snapshot definitions
opening: The first price a sportsbook posted for the player, from a licensed source.
closing: The sportsbook's last price before the tournament's first tee time.
Odds coverage currently documents none: ESPN publishes no golf prices. No outrights, matchups or finishing-position prices yet. No golf odds yet: ESPN publishes none for any tour, and the prices table waits for a licensed source.
Response format
REST API
All successful REST responses wrap the result in a data key:
{ "data": { "tournaments": [...], "count": 49 } }Error responses return:
{ "error": "Insufficient credits", "message": "This tool costs 5 credits, you have 2" }MCP Protocol
MCP responses follow the standard MCP tool result format. The data is returned directly (no data wrapper). Both access methods return identical data, just different envelopes.
Conventions
Seasons: 4-digit season year (the PGA Tour's season as ESPN files it; from 2014 to 2024 seasons began the October before). Example: 2025.
Tournament IDs: ESPN's event ids, e.g. 401580344 (the 2024 Masters). Get them from list_tournaments or get_schedule.
Player IDs: ESPN's athlete ids, the same on every tour. Get them from search_players, or from any leaderboard.
Course IDs: list_tournaments lists each tournament's courses; pass one to get_course or get_course_history.
Pagination: Endpoints use a limit parameter. No cursor or offset. Narrow your filters to get different slices of data.
Credits: Deducted before the request executes. Automatically refunded on server errors. Monthly credits are used first, then wallet balance.