Public API Guide (v1.0)

Documentation for Developers and Organizers

Welcome to the MTGSL Public API. This API allows Pro Organiser and Store users to programmatically access their community data, standings, and match results.

1. Getting Started

Authentication

All requests must be authenticated using your Public API Key.

Log in to MTGSL and go to your Profile.
Navigate to Security & Tools.
Under Public API Access, click Generate API Key.
Include this key in your request headers as X-API-KEY.

Warning: Your API key is sensitive. Never share it in client-side code (e.g., plain JavaScript).

Base URL

All v1 endpoints are prefixed with:

https://mtgsl.cloud/api/v1

2. API Endpoints

All endpoints are read-only (GET).

Resource Discovery

Endpoint	Description
`GET /me`	Lists all Stores, Series, and Leagues you manage or help with.

Store & Series

Endpoint	Description
`GET /stores/:id`	Returns details about a specific Store/Organization.
`GET /series/:id`	Returns series details and associated events.
`GET /series/:id/standings`	Returns aggregated standings for the entire series (includes tiebreaks).

League (Event) Data

Endpoint	Description
`GET /leagues/:id`	Returns basic league structure.
`GET /leagues/:id/standings`	Returns current calculated standings.
`GET /leagues/:id/rounds`	Returns all matches grouped by round (week).

Resource Expansion: Use ?include=participants or ?include=matches on the league endpoint to fetch related data in one call.

3. Best Practices

Rate Limiting: 1500 requests per 15 minutes per IP.

Error Codes: 401 (Unauthorized), 403 (Forbidden/Non-GET), 404 (Not Found).

Return to MTGSL