Do You Know Ball API

Authentication

All endpoints require an API key passed as a request header.

X-API-Key: your_api_key_here

Don't have an API key? See /license for instructions on how to register and generate one.

Get Player ID

Looks up a player by name and returns their unique MLB ID. Supports initials (e.g. J. Smith). If multiple players share the same name, provide a date of birth to disambiguate.

curl "https://do-u-know-ball.com/get-player-id?name=Juan%20Soto" \
  -H "X-API-Key: your_api_key_here"

{
  "fullName": "Juan Soto",
  "mlbId": 665742
}

If multiple players share the same name, a 300 response is returned:

{
  "error": "Multiple players found with that name.",
  "message": "Please provide a 'dob' parameter (YYYY-MM-DD) to disambiguate.",
  "options": [
    { "fullName": "Jose Rodriguez", "birthDate": "1988-06-03" },
    { "fullName": "Jose Rodriguez", "birthDate": "2000-04-14" }
  ]
}

List All Players

Returns an alphabetically sorted list of all players, including their MLB ID, headshot URL, and eligible positions.

curl "https://do-u-know-ball.com/players" \
  -H "X-API-Key: your_api_key_here"

{
  "count": 1200,
  "players": [
    {
      "name": "Aaron Judge",
      "id": 592450,
      "headshotUrl": "https://img.mlbstatic.com/...",
      "positions": ["RF", "DH"]
    },
    ...
  ]
}

Get Player Stats

Returns hitting and/or pitching stats for one or more players by MLB ID. Optionally filter by season year.

curl "https://do-u-know-ball.com/player-stats?ids=665742,592450" \
  -H "X-API-Key: your_api_key_here"

curl "https://do-u-know-ball.com/player-stats?ids=665742&year=2024" \
  -H "X-API-Key: your_api_key_here"

{
  "count": 2,
  "results": [
    {
      "player": { "id": "665742", "name": "Juan Soto", "position": "Designated Hitter" },
      "team":   { "id": 121, "name": "New York Mets", "abbreviation": "NYM" },
      "year":   "2025",
      "stats":  { "gamesPlayed": 158, "homeRuns": 43, "avg": ".288", ... }
    },
    ...
  ]
}

List All Teams

Returns all 30 MLB teams with their unique IDs and abbreviations, sorted alphabetically.

curl "https://do-u-know-ball.com/teams" \
  -H "X-API-Key: your_api_key_here"

{
  "count": 30,
  "teams": [
    { "id": 113, "name": "Cincinnati Reds", "abbreviation": "CIN" },
    { "id": 147, "name": "New York Yankees", "abbreviation": "NYY" },
    ...
  ]
}

Get Depth Chart

Returns a team's roster organized by position, including each player's current injury status.

curl "https://do-u-know-ball.com/depth-chart?teamId=113" \
  -H "X-API-Key: your_api_key_here"

{
  "teamId": "113",
  "positions": {
    "Pitcher": [
      { "id": 669302, "name": "Hunter Greene", "status": "Active" },
      ...
    ],
    "Catcher": [
      { "id": 663728, "name": "Tyler Stephenson", "status": "10-Day IL" }
    ],
    ...
  }
}

Daily Transactions

Returns all Major League transactions for the current day, including trades, IL placements, and call-ups.

curl "https://do-u-know-ball.com/transactions" \
  -H "X-API-Key: your_api_key_here"

{
  "date": "2025-05-01",
  "count": 12,
  "transactions": [
    {
      "playerId": 123456,
      "playerName": "Carlos Correa",
      "fromTeam": "Minnesota Twins",
      "fromTeamId": 142,
      "toTeam": "New York Mets",
      "toTeamId": 121,
      "description": "Traded to New York Mets"
    },
    ...
  ]
}

Value Players

The core valuation endpoint. Given a budget, draft context, and the stats that matter to your league, returns a ranked list of players with scores and recommended dollar values.

curl -X POST "https://do-u-know-ball.com/value" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "budget": 150,
    "players_left_to_draft": 3,
    "relevant_stats": "HR,AVG,RBI,SB",
    "unavailable_player_ids": [665742, 592450],
    "player_ids": [670712, 663728, 669302]
  }'

{
  "budget": 150,
  "relevant_stats": ["HR", "AVG", "RBI", "SB"],
  "player_count": 3,
  "results": [
    { "mlbId": 670712, "fullName": "Elly De La Cruz", "score": 0.8741, "value": 43 },
    { "mlbId": 669302, "fullName": "Hunter Greene",   "score": 0.6210, "value": 31 },
    { "mlbId": 663728, "fullName": "Tyler Stephenson","score": 0.4033, "value": 20 }
  ]
}