StatForge API Integration Guide

Base URL

https://api-statforge.fiberhostingservices.com

Authentication

All requests require your API key:

Authorization: Bearer YOUR_API_KEY

• Keys are scoped per application and environment.
• Sandbox and production are fully separate.
• Never expose API keys in frontend/browser code.

What your API key allows

Typical read scopes:

• read:players
• read:matches
• read:leaderboards

With these, your application can:

• Read verified match results
• Read player match history
• Read leaderboards

Your key cannot:

• Modify outcomes
• Access internal detection or review systems

Integration flow (important)

To use StatForge correctly, follow this order:

1. Link your players
2. Register expected matches
3. StatForge verifies matches
4. Read verified results

1. Link your players

Map your users to StatForge players with POST /api/v1/players/link.

{
  "externalPlayerId": "user_123",
  "personaId": "1007224402596"
}

This allows:

• Match results to include your user IDs
• Consistent identity mapping across your system

2. Register expected matches

Before a match starts, register it with POST /api/v1/matches/expected.

{
  "externalMatchId": "round1-match4",
  "tournamentId": 21,
  "scheduledStart": "2026-04-25T04:00:00Z",
  "expectedTeamSize": 4,
  "teamA": {
    "teamId": 1,
    "players": [
      { "personaId": "1003925665087" }
    ]
  },
  "teamB": {
    "teamId": 2,
    "players": [
      { "personaId": "1007224402596" }
    ]
  }
}

Why this matters

• Recognize matches when they occur
• Automatically group players into teams
• Reduce manual verification work
• Improve accuracy of results

Cancel an expected match

POST /api/v1/matches/expected/{id}/cancel

{
  "cancelReason": "Scrim rescheduled by organizer"
}

Cancelling an expected match prevents it from being matched or verified.

3. Read verified data

Matches

• GET /api/matches
• GET /api/matches/{id}

Leaderboards

• GET /api/leaderboards/verified
• GET /api/leaderboards/verified/teams

Optional filters: ?tournamentId=21, ?scrimId=23

Players (verified data)

• GET /api/v1/players
• GET /api/v1/players/{id}
• GET /api/v1/players/{id}/matches

Quick start

Fetch leaderboard

curl -s "https://api-statforge.fiberhostingservices.com/api/leaderboards/verified" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fetch matches

curl -s "https://api-statforge.fiberhostingservices.com/api/matches" \
  -H "Authorization: Bearer YOUR_API_KEY"

Match structure (simplified)

{
  "matchID": 6,
  "status": "verified",
  "teamAName": "Daddy Dragons",
  "teamBName": "Iron Legion",
  "scoreTeamA": 1,
  "scoreTeamB": 0,
  "winnerTeamName": "Daddy Dragons",
  "hasTeamCorrelation": true,
  "participants": [
    {
      "personaId": "1007224402596",
      "externalPlayerId": "user_123",
      "result": "loss",
      "kills": 7,
      "deaths": 3
    }
  ]
}

Important behavior

• Team vs non-team matches: when hasTeamCorrelation=true, render team scoreboards; otherwise treat as player-outcome match.
• Data is authoritative: verified matches are final, outcomes do not change after verification, and leaderboards update automatically.

Errors and environments

• 401 Unauthorized → invalid API key
• 403 Forbidden → missing scope / route access denied
• 404 Not found → resource does not exist
• Sandbox → isolated test environment
• Production → live verified data

Product boundary (important)

StatForge exposes verified data only.

The following are not part of the public API:

• detection pipelines
• candidate matches
• internal review systems
• raw tracker data

Summary

StatForge is a verification layer:

• One match → one record
• One outcome → trusted everywhere
• One API → consistent across systems