Overview
The MTGSL Public API lets you access your league, store, and series data programmatically. Use it to:
- Build Discord bots that post standings and round results
- Pull standings into Google Sheets or spreadsheets
- Power your store's website with live league data
- Integrate with third-party tournament tools
Authentication
All /api/v1/ endpoints require authentication via your API key.
Generating an API Key
- Go to Profile → Security
- Click Generate API Key
- Copy and store the key securely - the full key is only shown once
If you lose your key, revoke it and generate a new one.
Using the API Key
Include your API key as a request header:
X-API-KEY: your-api-key-hereCode Examples
cURL:
curl https://mtgsl.cloud/api/v1/me \
-H "X-API-KEY: your-api-key-here"JavaScript (fetch):
const response = await fetch('https://mtgsl.cloud/api/v1/me', {
headers: { 'X-API-KEY': 'your-api-key-here' }
});
const data = await response.json();Base URL
https://mtgsl.cloud/api/v1Endpoints
Returns your user account with associated stores, series, and leagues.
Response includes: User profile (id, screenName, tier), list of stores, series, and leagues.
Returns store details.
Response includes: Store name, description, slug, logo, staff list (name, role), series and event counts.
Returns series details.
Response includes: Series name, description, associated store, list of linked events.
Returns aggregated standings across all leagues in the series.
Response per player: rank, user ID and profile, total points, wins/losses/draws, match count, GWP, OWP.
Returns league details.
Optional query parameters:
?include=participants?include=matches?include=participants,matches
Returns current standings for a league.
Response per player: rank, user profile, points, W/L/D, match count, GWP, OWP.
Returns all matches grouped by week/round.
Response per round: round number, match list (match ID, status, player details, result, game scores).
Returns all participants with their stats.
Response per participant: participant ID, user profile, wins/losses/draws, points, isPaid status.
Returns bracket details for a tournament.
Response includes: tournament info, associated league info, bracket matches with player details and results.
Returns single participant details including full decklist history.
Response includes: user info, league info, stats, decklist versions with timestamps.
Practical Examples
Pull Standings into Google Sheets (Apps Script)
function fetchStandings() {
const response = UrlFetchApp.fetch(
'https://mtgsl.cloud/api/v1/leagues/YOUR_LEAGUE_ID/standings',
{ headers: { 'X-API-KEY': 'your-api-key' } }
);
const data = JSON.parse(response.getContentText());
// Write to sheet...
}Discord Bot - Post Weekly Standings (Node.js)
const standings = await fetch(
`https://mtgsl.cloud/api/v1/leagues/${leagueId}/standings`,
{ headers: { 'X-API-KEY': process.env.MTGSL_API_KEY } }
).then(r => r.json());
const message = standings
.slice(0, 10)
.map(p => `${p.rank}. **${p.user.screenName}** — ${p.points} pts (${p.wins}W/${p.losses}L)`)
.join('\n');
channel.send(`**Current Standings:**\n${message}`);Error Responses
| Status Code | Meaning |
|---|---|
401 Unauthorized |
Missing or invalid API key |
403 Forbidden |
Your tier doesn't have access to this endpoint |
404 Not Found |
The requested resource doesn't exist |
429 Too Many Requests |
Rate limit exceeded |
500 Internal Server Error |
Something went wrong on the server |
Rate Limits
1,500 requests per 15 minutes per IP. If exceeded, you'll receive a 429 response. Implement exponential backoff in automated tools to handle rate limit responses gracefully.
Revoking Your API Key
- Go to Profile → Security
- Click Revoke Key
- Generate a new key if needed