API Reference

Public API

Access your league data programmatically - standings, matches, participants, and more.

User Guide

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
Available to: Pro, Community, and LGS tier accounts.
Interactive docs: mtgsl.cloud/api/docs

Authentication

All /api/v1/ endpoints require authentication via your API key.

Generating an API Key
  1. Go to Profile → Security
  2. Click Generate API Key
  3. 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-here
Code 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();
Security: Keep your API key private. Do not include it in client-side code or commit it to a public repository. Use environment variables or a server-side proxy.

Base URL

https://mtgsl.cloud/api/v1

Endpoints

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.

Returns all calendar events (leagues and majors) for a store, sorted by start date.

Response per event: id, eventType (league or major), name, format, status (upcoming, active, completed), startDate / endDate (ISO 8601), recurrenceGroupId (non-null when part of a recurring series), recurrenceIndex, seriesId, and participantCount.

Use this endpoint to power external dashboards, Discord bots, or custom calendars with live event data from your organisation. Upcoming events within the next 72 hours are a good candidate for automated announcements.

curl https://mtgsl.cloud/api/v1/stores/YOUR_STORE_ID/events \
  -H "X-API-KEY: your-api-key-here"

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

  1. Go to Profile → Security
  2. Click Revoke Key
  3. Generate a new key if needed
Revoking immediately invalidates the key. All integrations using it will stop working until they are updated with a new key.

Ready to start building with the MTGSL API?

Interactive API Docs Create an Account