GetPaird API

Usage & rate limits

The GetPaird API is free. It exposes read-only, public tournament data — exactly what the public live pages show, never more. All endpoints share one base URL:

https://getpaird.io/api/v1

A machine-readable OpenAPI 3.0 description of the API is available (no key needed) — point your client generator at it:

https://getpaird.io/api/v1/openapi.json

Authentication

Every tournament endpoint requires an API key. Keys are free: create one from your account page (up to 5 active keys, revocable at any time). The key is shown once at creation — store it like a password.

Send the key in the Authorization header — either raw or as a Bearer token, both are accepted:

curl https://getpaird.io/api/v1/tournaments/my-tournament-slug/standings \
  -H "Authorization: YOUR_API_KEY"

# equivalent:
curl https://getpaird.io/api/v1/tournaments/my-tournament-slug/standings \
  -H "Authorization: Bearer YOUR_API_KEY"

An invalid or missing key returns 401 with the body below. Keys are personal: never ship one in client-side code or a public repository.

{ "error": "Invalid API key" }

What a key can reach

A key is scoped to the public API and nothing else. It is read-only and cannot touch the account that created it — no profile, no private decklists, no organizer or judge action. Used on any other endpoint it returns 403:

{ "error": "This API key is restricted to the public API. Only /api/v1/tournaments endpoints are available to developer keys." }

Your first call

The tournament identifier is the slug from its public page: for getpaird.io/tournaments/my-event, the slug is my-event. Start with this — no key needed — just to confirm the API answers you:

https://getpaird.io/api/v1/tournaments/YOUR-SLUG/standings

Opened directly in a browser it must return 401 {"error":"Invalid API key"}. That response is the good news — the server answered and is only telling you the key is missing. Now add the key:

curl -H "Authorization: YOUR_API_KEY" \
  https://getpaird.io/api/v1/tournaments/YOUR-SLUG/standings

If it does not work

Never put a key in a web page or any code that runs in a browser — it is readable by every visitor. Keep it on a server or in a bot.

Managing your keys

On the account API-keys page you can set an optional expiry when you create a key, see each key's recent request count, and revoke any key instantly. If a key stops working with a 403 saying it is suspended, it was disabled for abuse — write to [email protected]. GetPaird records per-key usage (endpoints, volume, error and throttle rates) to keep the API healthy; no IP address is stored.

Attribution

Any project using the API must include a visible credit and link back to GetPaird. By using the API you agree to this requirement and to using the data in a way that respects players (no scraping for spam, no re-identification attempts on anonymized players).

<p>Data provided by
  <a href="https://getpaird.io" target="_blank">GetPaird</a>
</p>

Search tournaments. Two modes: TID mode (a list of known tournament slugs, any public status — follow an event live) or query mode (filters; completed tournaments only). Returns up to 25 tournaments, most recent first, each with standings and optional round data.

Request body

Example

curl -X POST https://getpaird.io/api/v1/tournaments \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "game": "Magic: The Gathering",
    "format": "Modern",
    "last": 30,
    "columns": ["name", "wins", "draws", "losses", "archetype"],
    "rounds": true
  }'

[
  {
    "TID": "modern-mayhem-12",
    "tournamentName": "Modern Mayhem #12",
    "game": "Magic: The Gathering",
    "format": "Modern",
    "startDate": 1752303600,
    "swissNum": 5,
    "topCut": 8,
    "eventData": {
      "city": "Lyon",
      "country": "France",
      "address": "12 Rue des Jeux",
      "latitude": 45.7640430,
      "longitude": 4.8356590,
      "headerImage": "https://getpaird.io/storage/..."
    },
    "standings": [
      { "standing": 1, "name": "Alice", "wins": 6, "draws": 0, "losses": 1, "archetype": "Burn" }
    ],
    "rounds": [
      { "round": 1, "tables": [ { "table": 1, "players": [...], "winner": "Alice", "winner_id": 1041, "winner_games": 2, "loser_games": 1, "status": "Completed" } ] }
    ]
  }
]

Full tournament data in one response: metadata, standings and every published round.

{
  "data": {
    "tid": "modern-mayhem-12",
    "name": "Modern Mayhem #12",
    "game": "Magic: The Gathering",
    "format": "Modern",
    "startDate": 1752303600
  },
  "standings": [ ... ],   // same rows as /standings
  "rounds": [ ... ]       // same shape as /rounds
}

Team events add isTeamEvent, teamSize and teamTags (the ordered per-seat labels) to data.

Links

Every payload carries links so you never build a getpaird.io URL by hand. /info (and full data) carry a `urls` object (web page, live view, results, and the API self-link) plus an `event` object when the tournament belongs to a multi-tournament event. Each standings row and each round-table player carries a `profileUrl` (the player's public profile, null for an anonymized account or a team) and, once the event is completed and the list published, a `decklistUrl` to the public snapshot. The player endpoint adds `urls.tournament`.

"urls": {
  "web":     "https://getpaird.io/tournaments/my-event",
  "live":    "https://getpaird.io/tournaments/my-event/live",
  "results": "https://getpaird.io/tournaments/my-event/results",
  "api":     "https://getpaird.io/api/v1/tournaments/my-event/info"
},
"event": { "name": "Spring Weekend", "slug": "spring-weekend",
           "urls": { "web": "https://getpaird.io/events/spring-weekend" } }

// on a standings row / a round-table player:
"profileUrl":  "https://getpaird.io/meta/players/alice",
"decklistUrl": "https://getpaird.io/tournaments/my-event/lists/421"

Tournament metadata, schedule and location.

The phase pipeline

`phases` describes how the event is actually run — a Swiss into a Top 8, a draft into constructed, a Swiss into an EDH Top Pod. Each phase carries its structure (`kind`, plus the raw `type` / `mode` / `eliminationMode`), the `cut` of players kept entering it (or `cutMinPoints` for a points-threshold cut, e.g. a Day-1 cut at 21 points), its planned `rounds`, `bestOf`, `status`, and its OWN `scoring` + `tiebreakerOrder` (so a phase that scores differently from the one before it is not flattened away). `swissNum` counts only true Swiss rounds (null when there is no Swiss phase); `topCut` is the size of the cut OUT of Swiss (the first elimination phase). Both are kept as convenience scalars.

"phases": [
  { "sequence": 1, "name": "Swiss", "kind": "swiss", "type": "swiss",
    "mode": "constructed", "eliminationMode": null, "cut": null,
    "rounds": 5, "bestOf": 3, "status": "completed", "decklistsOpen": false,
    "scoring": { "system": "match_points", "winPoints": 3, ... },
    "tiebreakerOrder": [ { "key": "omw", "label": "OMW%", "format": "pct" }, ... ] },
  { "sequence": 2, "name": "Top 8", "kind": "single_elimination",
    "type": "single_elimination", "mode": "constructed", "cut": 8,
    "rounds": 3, "bestOf": 3, "status": "active", ... }
]

// kind ∈ swiss | single_elimination | double_elimination | round_robin |
//        swiss_top_cut | draft | multiplayer_swiss | multiplayer_elimination

Current standings as a flat array. Once a top cut has started, the order folds the bracket results in (champion first); the Swiss tiebreaker percentages are preserved on each row. Returns an empty array while the organizer has hidden standings.

Precision, and which tiebreakers you get

The four percentages are returned with 4 decimals because that is exactly how the platform stores them: the standings columns are decimal(5,4). Returning more digits would invent precision the database does not hold. Do not reconstruct the ranking by comparing these floats yourself — the official order is the "standing" field, computed server-side with an epsilon so that a true tie falls through to the next tiebreaker instead of being decided by floating-point noise.

The four flat fields are kept for TopDeck compatibility, but every configured tiebreaker — not just these four — is now exposed. Each standings row carries a `tiebreakers` array in the exact order that decides rank; and /info advertises that order once, in `tiebreakerOrder`, alongside a `scoring` block (points per win/draw/loss/bye and the tiebreaker floor). So a Buchholz event, an OppAvgMP event or a multiplayer pod event is fully reproducible too.

// on /info
"tiebreakerOrder": [
  { "key": "omw",  "label": "OMW%",             "format": "pct" },
  { "key": "gw",   "label": "GW%",              "format": "pct" },
  { "key": "de",   "label": "Direct Encounter", "format": "pairwise" }
],
"scoring": { "system": "match_points", "winPoints": 3, "drawPoints": 1,
             "lossPoints": 0, "byePoints": 3, "tiebreakerFloor": 0.3333 }

// each standings row, in the SAME order:
"tiebreakers": [
  { "key": "omw", "label": "OMW%", "format": "pct",      "value": 0.6122 },
  { "key": "gw",  "label": "GW%",  "format": "pct",      "value": 0.8 },
  { "key": "de",  "label": "Direct Encounter", "format": "pairwise", "value": null }
]

A `pairwise` tiebreaker (Direct Encounter) decides ties head-to-head, so it has no per-row number — its value is null but the entry is always present. Format is one of pct, int, dec2 or pairwise. Still: do not re-derive the order from these values, "standing" is authoritative (a true tie falls through to the next tiebreaker with an epsilon the client cannot reproduce).

[
  {
    "standing": 1,
    "name": "Alice",
    "id": 1041,
    "points": 18,
    "wins": 6, "losses": 1, "draws": 0, "byes": 1,
    "winRate": 0.8571,
    "opponentWinRate": 0.6122,
    "gameWinRate": 0.8,
    "opponentGameWinRate": 0.55,
    "archetype": "Burn",
    "decklist": "// Mainboard\n4 Lightning Bolt\n...",
    "deckObj": { "Mainboard": { "Lightning Bolt": 4 }, "Sideboard": { ... } }
  }
]

Player details and full match record for one tournament. The id is the per-tournament player id from standings and round tables. Unlike standings rows, wins here EXCLUDE byes (byes are reported separately) — a bye is not a played match.

On team events this is the player's own board record: each entry is the board they played, never the team-level match (which is scored in boards won, not games).

{
  "id": 1041,
  "name": "Alice",
  "standing": 1,
  "points": 18,
  "winRate": 0.8571,
  "wins": 5, "losses": 1, "draws": 0, "byes": 1,
  "gamesPlayed": 14, "gamesWon": 11, "gamesLost": 3, "gamesDrawn": 0,
  "matches": [
    {
      "round": 1,
      "phase": 1,                 // the phase sequence (groups colliding stage labels)
      "table": 4,
      "result": "win",            // win | loss | draw | bye | pending
      "gamesWon": 2, "gamesLost": 1, "gamesDrawn": 0,
      "opponent": { "name": "Bob", "id": 1042 }
    },
    {
      "round": 2,
      "phase": 1,
      "table": "Byes",
      "result": "bye",
      "gamesWon": 0, "gamesLost": 0, "gamesDrawn": 0,
      "opponent": null
    }
  ],
  "archetype": "Burn",
  "leader": null,                 // commander / leader card name(s) on leader-based games
  "decklist": "// Mainboard\n4 Lightning Bolt\n...",
  "deckObj": { ... }
}

On multiplayer (pod) tournaments a match carries an opponents array instead of opponent, and game counts reflect pod results (1 per pod).

Every round the organizer has published, in play order, each with its tables and results. Swiss rounds are numbered; elimination rounds — including EDH multiplayer top cuts — carry a stage label ("Quarterfinals", "Semifinals", "Finals", "Grand Final", ...). Each round also carries `phase` (its sequence in the pipeline), `phaseName`, and `stage` (the same human label), so you can group rounds by phase. Rounds whose pairings are not yet published are omitted.

[
  {
    "round": 1,
    "phase": 1,
    "phaseName": "Swiss",
    "stage": "Round 1",
    "tables": [
      {
        "table": 1,
        "players": [ { "name": "Alice", "id": 1041 }, { "name": "Bob", "id": 1042 } ],
        "winner": "Alice",
        "winner_id": 1041,
        "winner_games": 2,
        "loser_games": 1,
        "status": "Completed"
      },
      {
        "table": "Byes",
        "players": [ { "name": "Chloe", "id": 1043 } ],
        "status": "Bye"
      }
    ]
  },
  { "round": "Quarterfinals", "phase": 2, "phaseName": "Top 8", "stage": "Quarterfinals", "tables": [ ... ] }
]

Multiplayer (EDH / pod) tournaments list every pod as one table with its full seating; game scores are null and the winner is the pod winner. A multiplayer top cut labels its rounds Finals / Semifinals / Quarterfinals like a 1v1 bracket. Team events list one table per board (seat), tagged with the seat label — in the Swiss rounds and, since 2026-08-16, in the top cut as well. A team-trio round-robin phase still pairs team representatives with no boards and lists one team-vs-team row (the two team names as the sides).

The tables of the latest published round only, as a flat array — no round wrapper. Same table shape as /rounds. The cheapest way to poll a live event.

[
  { "table": 1, "players": [ ... ], "winner": null, "winner_id": null, "winner_games": null, "loser_games": null, "status": "Active" },
  { "table": "Byes", "players": [ { "name": "Chloe", "id": 1043 } ], "status": "Bye" }
]

The full roster — registered players, dropped players and waitlist entries — with contact info. Requires that your account holds a staff role on the tournament (a stranger's key gets 403). Because it is your own event, it works on your private and draft tournaments too, and it is never cached.

[
  { "uid": 88, "name": "Alice", "email": "[email protected]", "status": "player", "standing": 1 },
  { "uid": 91, "name": "Bob", "email": "[email protected]", "status": "dropped", "standing": null },
  { "uid": 93, "name": "Wendy", "email": "[email protected]", "status": "waitlist",
    "waitlistStatus": "waiting", "waitlistPosition": 1, "joinedAt": 1752300000 }
]

The tournaments your account manages. Defaults to those with a future start date; pass ?filter=all to include in-progress and past events. Each entry carries tid, name, game, format, startDate, endDate, status, location, headerImage, registeredCount, capacity and urls.

[
  {
    "tid": "weekly-modern-14",
    "name": "Weekly Modern #14",
    "game": "Magic: The Gathering",
    "format": "Modern",
    "startDate": 1752303600,
    "endDate": null,
    "status": "Not Started",
    "location": { "name": "The Game Store", "city": "Lyon", "country": "France" },
    "headerImage": "https://getpaird.io/storage/...",
    "registeredCount": 18,
    "capacity": 32
  }
]

Decklists feed (no key required)

Separate from the tournament API, GetPaird also exposes the public deck library as an unauthenticated read-only feed (60 requests per minute per IP). It mirrors the public /decks discovery page.

Note: this feed predates the tournament API and keeps its own response conventions (data / meta envelope, Laravel-style validation errors).

Setup & access

Register an HTTPS endpoint on your account webhooks page and pick which event types you want (or all of them). Each endpoint gets a whsec_… signing secret, shown once. Your endpoint then receives events for every tournament where your account holds a staff role — so if you organize your own events you are already set, and to build tools for another organizer, have them add your account to their event staff.

Endpoint and staff-role changes take effect within about a minute. Every payload carries the tid, so you can also route or ignore tournaments in your own code.

The event envelope

Every delivery is a POST with the same top-level shape. Write one handler for the envelope, then switch on type. Object shapes inside data match the REST API. Decklists are never included in webhook payloads — fetch the REST API when you need them.

Request headers

X-GetPaird-Event:      round.published        # the event type, for routing before parsing
X-GetPaird-Event-Id:   evt_57c9cdee7de1…      # same as the payload id
X-GetPaird-Signature:  t=1751500800000,v1=5f8a…  # see "Verifying signatures"
User-Agent:            GetPaird-Webhooks/1.0

{
  "id": "evt_57c9cdee7de1de4f4a0dc332494846be",
  "type": "round.published",
  "created": 1751500800000,
  "apiVersion": "2026-08",
  "tid": "weekly-cedh-14",
  "tournament": { "name": "Weekly cEDH", "game": "Magic: The Gathering", "format": "Commander Multiplayer" },
  "data": { "...": "event-specific, see below" }
}

Event types

player id and standings ids are per-tournament registration ids — the same ids the REST API uses. Byes appear as a final table with table: "Byes".

Verifying signatures

Every delivery is signed with your endpoint's whsec_… secret. The X-GetPaird-Signature header is t=<ms>,v1=<hex>. v1 is an HMAC-SHA256, hex encoded, computed over the timestamp and the RAW request body joined with a period: `${t}.${rawBody}`. Compute the same and compare with a constant-time check. Verify over the exact bytes received — do not re-serialize parsed JSON — so enable raw-body capture on your webhook route.

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  if (!parts.v1) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`).digest('hex');
  const a = Buffer.from(parts.v1), b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery & retries

Respond with any 2xx within 10 seconds; anything else (including timeouts and redirects) is a failed attempt. Acknowledge fast, then process asynchronously. Failed deliveries are retried with exponential backoff (starting ~30s, capping ~10 min). Delivery is at-least-once — deduplicate on id — and order is not guaranteed, so use created to order events. After 50 consecutive failures an endpoint is auto-disabled and you are emailed; fix your receiver and re-enable it from your webhooks page. URLs must be HTTPS on a publicly resolvable host; redirects are not followed. The delivery log keeps the last attempts for about 30 days.

Use "Send test" on your webhooks page to fire a signed ping and verify your handler end to end — delivered even while an endpoint is paused.