API reference
Read-only JSON for player profiles, contracts and team lineups, refreshed daily.
First request
Every endpoint lives under this base URL:
https://capwages.com/api/gateway/v1- Subscribe to the API add-on. It works with or without a CapWages plan.
- Generate a key in Settings. It is shown once, so store it somewhere safe, like an environment variable.
- Send it on every request as
Authorization: ApiKey <your key>.
Try it with the first five players:
curl "https://capwages.com/api/gateway/v1/players?limit=5" \
-H "Authorization: ApiKey $CAPWAGES_API_KEY"Responses are JSON with apiVersion (currently 1.2), success, data and meta. Amounts are whole US dollars.
Fair use and caching
The data refreshes once a day, so most apps need one full import a day and nothing more.
- Cache responses and import the full database at most once a day. Before importing, check
meta.lastUpdatedon a single/playerspage. If it matches your last import, nothing has changed. - Keep to 4 requests per second or fewer. Keys that go well past this may be suspended.
- Page through
/playerswithlimit=100. Players are sorted by slug, and fetching every page in one run keeps the whole list on the same daily build. - On the player endpoints,
meta.lastUpdatedis when the data was last rebuilt. On/lineupsit is when that team's lineup last changed.
Errors
Check the HTTP status first. Auth and routing errors come back as a plain { error } object, not the usual envelope.
| Status | Body | Cause and fix |
|---|---|---|
| 401 | Body{ "error": "Missing API Key" } | Cause and fixNo Authorization header, or it doesn't start with ApiKey and a space. |
| 403 | Body{ "error": "Invalid key" } | Cause and fixThe key is wrong, expired or revoked. Generate a new one in Settings. |
| 404 | Body{ "apiVersion": "1.2", "success": false, "error": { "code": 404, "message": "Player not found" } } | Cause and fixNo player with that slug. |
| 404 | Body{ "apiVersion": "1.2", "success": false, "error": { "code": 404, "message": "Lineup not found for this team" } } | Cause and fixThe team slug isn't recognised. See Team slugs. |
| 404 | Body{ "error": "Not Found" } | Cause and fixThe path doesn't match an endpoint. Check the /v1 prefix. |
| 500 | Body{ "error": "Proxy failed" } | Cause and fixTemporary server problem. Retry after a few seconds, with backoff. |
GET/players
Every player in the database, sorted by slug, one page at a time. Use it to collect slugs, then fetch each player's details.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| page | Typeinteger | Default1 | DescriptionPage to return, starting at 1. A page past the last one returns an empty data array. |
| limit | Typeinteger | Default25 | DescriptionPlayers per page. Use 100 for a full import. Values below 1 or non-numbers fall back to the default. |
Request
curl "https://capwages.com/api/gateway/v1/players?page=1&limit=100" \
-H "Authorization: ApiKey $CAPWAGES_API_KEY"Response
{
"apiVersion": "1.2",
"success": true,
"data": [
{
"slug": "connor-mcdavid",
"name": "Connor McDavid",
"note": "C",
"pos": "C",
"current_team_slug": "edmonton_oilers"
},
{
"slug": "mitch-marner",
"name": "Mitch Marner",
"note": null,
"pos": "RW, C, LW",
"current_team_slug": "vegas_golden_knights"
}
],
"meta": {
"pagination": {
"page": 2,
"limit": 100,
"total": 7980,
"totalPages": 80,
"links": {
"first": "/v1/players?page=1&limit=100",
"prev": "/v1/players?page=1&limit=100",
"next": "/v1/players?page=3&limit=100",
"last": "/v1/players?page=80&limit=100"
}
},
"lastUpdated": "2026-11-11T00:11:20.000Z"
}
}Fields
| Field | Type | Meaning |
|---|---|---|
| slug | Typestring | MeaningThe player's ID. Pass it to /players/:slug. |
| name | Typestring | MeaningFull name. |
| note | Typestring | null | MeaningCaptaincy: C or A, otherwise null. |
| pos | Typestring | MeaningEvery position the player is listed at, comma separated, primary first. For example RW, C, LW. |
| current_team_slug | Typestring | null | MeaningTeam slug, for example edmonton_oilers. Null for players without an NHL team. Pass it straight to /lineups. |
| meta.pagination.total | Typeinteger | MeaningPlayers across all pages, including prospects and retired players. |
| meta.pagination.totalPages | Typeinteger | MeaningLast page number for this limit. Stop paging here. |
| meta.pagination.links | Typeobject | Meaningfirst, prev, next and last as paths under /v1. Prefix them with https://capwages.com/api/gateway. prev and next are null at the ends. |
| meta.lastUpdated | Typestring | MeaningWhen the data was last rebuilt (ISO 8601). It changes about once a day, so compare it with your cached copy to decide whether to re-import. |
GET/players/:slug
A player's profile, draft details and every contract, season by season.
Path parameters
| Parameter | Type | Description |
|---|---|---|
| slug | Typestring | DescriptionThe player's ID from /players, for example connor-mcdavid. |
Fetch only the players you need
/players returns about 8,000 players, including prospects and retired players. If you only need NHL rosters, keep the ones with a current_team_slug before calling this endpoint for each.
Request
curl "https://capwages.com/api/gateway/v1/players/connor-mcdavid" \
-H "Authorization: ApiKey $CAPWAGES_API_KEY"Response
{
"apiVersion": "1.2",
"success": true,
"data": {
"name": "Connor McDavid",
"slug": "connor-mcdavid",
"team": "Edmonton Oilers",
"position": "C",
"leagueStatus": "NHL",
"acquisition": {
"method": "Draft",
"details": "2015 EDM, 1st round, 1st pick (1st overall)",
"year": 2015,
"round": 1,
"overallPick": 1,
"draftTeam": "EDM"
},
"nhlId": 8478402,
"jerseyNumber": 97,
"personalInfo": {
"birthDate": "1997-01-13",
"birthPlace": "Richmond Hill, Ontario, CAN",
"nationality": "CAN"
},
"physicalAttributes": {
"hand": "Left",
"height": { "imperial": "6'1\"", "metric": 185 },
"weight": { "imperial": "194 lbs", "metric": 88 }
},
"ageLimits": {
"entryLevelContractSigningAge": 18,
"waiversEligibilityAge": 18
},
"contracts": [
{
"contractType": "Standard Contract (Extension)",
"contractLength": "2 years",
"contractYears": 2,
"contractValue": 25000000,
"expiryStatus": "UFA",
"signingTeam": "Edmonton Oilers",
"signingDate": "2025-10-06",
"signedBy": "Stan Bowman",
"seasons": [
{
"season": "2026-27",
"clause": "NMC",
"capHit": 12500000,
"aav": 12500000,
"performanceBonuses": 0,
"signingBonuses": 13400000,
"baseSalary": 850000,
"totalSalary": 14250000,
"minorsSalary": 0
}
]
}
]
},
"meta": {
"lastUpdated": "2026-11-11T00:11:20.000Z"
}
}Fields
| Field | Type | Meaning |
|---|---|---|
| team | Typestring | null | MeaningCurrent team's full name. |
| position | Typestring | MeaningPrimary position only, the first entry of pos from /players. |
| leagueStatus | Typestring | MeaningWhere the player is now. See League status values. |
| acquisition.method | Typestring | MeaningHow the current team got him: Draft, Trade, Signed, Waivers claim, PTO and others. |
| acquisition.details | Typestring | null | MeaningFree text describing the acquisition. Null when it isn't known. |
| acquisition.year, .round, .overallPick | Typeinteger | null | MeaningDraft year, round and overall pick. Null for undrafted players. |
| acquisition.draftTeam | Typestring | null | MeaningThree-letter code of the drafting team. |
| nhlId | Typeinteger | null | MeaningNHL.com player ID. |
| jerseyNumber | Typeinteger | null | MeaningCurrent sweater number. |
| personalInfo.birthDate | Typestring | null | MeaningYYYY-MM-DD. |
| personalInfo.nationality | Typestring | null | MeaningCountry code, usually three letters. |
| physicalAttributes.hand | Typestring | null | MeaningLeft or Right. Shoots for skaters, catches for goalies. |
| …height.metric, …weight.metric | Typeinteger | null | MeaningCentimetres and kilograms. |
| ageLimits | Typeobject | MeaningAge at first contract signing, which sets entry-level length and waiver exemption under the CBA. |
| contracts[] | Typearray | MeaningEvery contract the player has signed, oldest first by signingDate. |
| contracts[].contractType | Typestring | MeaningFree text, for example Entry-Level Contract or 35+ Contract. |
| contracts[].contractLength | Typestring | MeaningTerm as text, for example "2 years". |
| contracts[].contractYears | Typeinteger | MeaningTerm in years, for example 2. |
| contracts[].contractValue | Typeinteger | MeaningTotal value in US dollars. |
| contracts[].expiryStatus | Typestring | MeaningStatus when it ends: UFA, RFA, RFA (Arb), UFA (No QO) and others. |
| contracts[].signedBy | Typestring | null | MeaningGeneral manager who signed it. |
| seasons[].season | Typestring | MeaningSeason label, for example 2026-27. Seasons are in order. |
| seasons[].clause | Typestring | null | MeaningTrade protection: NMC, NTC, M-NTC and combinations. |
| seasons[].capHit, .aav | Typeinteger | MeaningCap hit and average annual value for the season, in US dollars. |
| seasons[].baseSalary, .signingBonuses, .performanceBonuses | Typeinteger | MeaningPay components in US dollars. totalSalary is base salary plus signing bonuses. |
| seasons[].minorsSalary | Typeinteger | MeaningPay while in the minors on a two-way deal, in US dollars. 0 when the contract doesn't set one. |
| seasons[].buyout | Typeobject | MeaningOnly on bought-out seasons: teamName, teamSlug (may be null), cost, earning, savings, capHit. |
| seasons[].retention | Typeobject | MeaningOnly when salary is retained. Keyed by team name: { "San Jose Sharks": { "capHit": 2924000, "retainedPct": 86 } }. |
| meta.lastUpdated | Typestring | MeaningWhen the data was last rebuilt, the same value as on /players. |
GET/lineups/:teamSlug
A team's current lines: the latest game-day lineup once training camp opens, and projected lines before that.
Path parameters
| Parameter | Type | Description |
|---|---|---|
| teamSlug | Typestring | DescriptionTeam slug, for example toronto_maple_leafs. The hyphenated form (toronto-maple-leafs) also works. |
Request
curl "https://capwages.com/api/gateway/v1/lineups/toronto_maple_leafs" \
-H "Authorization: ApiKey $CAPWAGES_API_KEY"Response
{
"apiVersion": "1.2",
"success": true,
"data": {
"teamSlug": "toronto_maple_leafs",
"players": [
{ "playerSlug": "oliver-ekman-larsson", "line": "d1", "position": "ld" },
{ "playerSlug": "chris-tanev", "line": "d1", "position": "rd" },
{ "playerSlug": "jake-mccabe", "line": "d2", "position": "ld" },
{ "playerSlug": "darren-raddysh", "line": "d2", "position": "rd" }
]
},
"meta": {
"lastUpdated": "2026-11-11T00:00:00Z",
"source": "game_day"
}
}Fields
| Field | Type | Meaning |
|---|---|---|
| data.teamSlug | Typestring | MeaningThe slug as you sent it. |
| data.players[] | Typearray | MeaningOne entry per slot, sorted alphabetically by line then position: defense, then forwards, then goalies. |
| players[].playerSlug | Typestring | MeaningPass it to /players/:slug. |
| players[].line, .position | Typestring | MeaningWhere the player slots in. See the code map below. |
| meta.source | Typestring | Meaninggame_day for the latest real lineup, projected for preseason projections. The API falls back to the other one when a team has none. |
| meta.lastUpdated | Typestring | MeaningWhen this lineup last changed. Unlike the player endpoints, this is real data freshness. |
Line and position codes
| line | lw | c | rw |
|---|---|---|---|
| f1 | 1st line LW | 1st line C | 1st line RW |
| f2 | 2nd line LW | 2nd line C | 2nd line RW |
| f3 | 3rd line LW | 3rd line C | 3rd line RW |
| f4 | 4th line LW | 4th line C | 4th line RW |
| line | ld | rd |
|---|---|---|
| d1 | 1st pair LD | 1st pair RD |
| d2 | 2nd pair LD | 2nd pair RD |
| d3 | 3rd pair LD | 3rd pair RD |
| d4 | Extra LD | Extra RD |
| line | g1 | g2 |
|---|---|---|
| g | Starter | Backup |
Team slugs
The slug is what current_team_slug returns and what /lineups takes. /lineups also accepts it with hyphens.
| Team | Slug | Code |
|---|---|---|
| Anaheim Ducks | Sluganaheim_ducks | CodeANA |
| Boston Bruins | Slugboston_bruins | CodeBOS |
| Buffalo Sabres | Slugbuffalo_sabres | CodeBUF |
| Calgary Flames | Slugcalgary_flames | CodeCGY |
| Carolina Hurricanes | Slugcarolina_hurricanes | CodeCAR |
| Chicago Blackhawks | Slugchicago_blackhawks | CodeCHI |
| Colorado Avalanche | Slugcolorado_avalanche | CodeCOL |
| Columbus Blue Jackets | Slugcolumbus_blue_jackets | CodeCBJ |
| Dallas Stars | Slugdallas_stars | CodeDAL |
| Detroit Red Wings | Slugdetroit_red_wings | CodeDET |
| Edmonton Oilers | Slugedmonton_oilers | CodeEDM |
| Florida Panthers | Slugflorida_panthers | CodeFLA |
| Los Angeles Kings | Sluglos_angeles_kings | CodeLAK |
| Minnesota Wild | Slugminnesota_wild | CodeMIN |
| Montréal Canadiens | Slugmontreal_canadiens | CodeMTL |
| Nashville Predators | Slugnashville_predators | CodeNSH |
| New Jersey Devils | Slugnew_jersey_devils | CodeNJD |
| New York Islanders | Slugnew_york_islanders | CodeNYI |
| New York Rangers | Slugnew_york_rangers | CodeNYR |
| Ottawa Senators | Slugottawa_senators | CodeOTT |
| Philadelphia Flyers | Slugphiladelphia_flyers | CodePHI |
| Pittsburgh Penguins | Slugpittsburgh_penguins | CodePIT |
| San Jose Sharks | Slugsan_jose_sharks | CodeSJS |
| Seattle Kraken | Slugseattle_kraken | CodeSEA |
| St. Louis Blues | Slugst_louis_blues | CodeSTL |
| Tampa Bay Lightning | Slugtampa_bay_lightning | CodeTBL |
| Toronto Maple Leafs | Slugtoronto_maple_leafs | CodeTOR |
| Utah Mammoth | Slugutah_mammoth | CodeUTA |
| Vancouver Canucks | Slugvancouver_canucks | CodeVAN |
| Vegas Golden Knights | Slugvegas_golden_knights | CodeVGK |
| Washington Capitals | Slugwashington_capitals | CodeWSH |
| Winnipeg Jets | Slugwinnipeg_jets | CodeWPG |
League status values
Values of leagueStatus on /players/:slug.
| Value | Meaning |
|---|---|
| NHL | MeaningOn an NHL roster. |
| Minor | MeaningPlaying in the minors. |
| IR | MeaningOn injured reserve. |
| Loan | MeaningLoaned to another league. |
| Prospect | MeaningUnsigned. current_team_slug is the team holding his rights, when there is one. |
| Junior | MeaningSigned, playing junior hockey. |
| Undrafted | MeaningNever drafted and not under contract. |
| KHL | MeaningPlaying in the KHL. |
| Inactive | MeaningNo current contract or rights. Most of the table. |
| Retired | MeaningRetired. |
| Deceased | MeaningDeceased. |