Matches

A match is a head-to-head competition between two sides — either two individual participants or two teams. Matches are generated automatically when a tournament starts and its bracket is built.

Match lifecycle

SCHEDULED → IN_PROGRESS → PENDING_RESULT → COMPLETED
                                  └── DISPUTED → RESOLVED

Starting a match

Organizers or participants can signal that a match has begun:

POST /api/v1/matches/:id/start
Authorization: Bearer ACCESS_TOKEN

Reporting a result

After the game, a participant submits the outcome:

POST /api/v1/matches/:id/report
Authorization: Bearer USER_ACCESS_TOKEN
Content-Type: application/json

{
  "winnerId": "participant-uuid",
  "scores": [
    { "participantId": "participant-uuid", "score": 13 },
    { "participantId": "opponent-uuid", "score": 7 }
  ]
}

Confirming a result

The opposing participant confirms the reported result:

POST /api/v1/matches/:id/confirm
Authorization: Bearer OPPONENT_ACCESS_TOKEN

Once both sides confirm — or the organizer approves the result — the match moves to COMPLETED and the winner advances in the bracket.

Disputing a result

If a participant disagrees with the reported result, they can open a dispute:

POST /api/v1/matches/:id/dispute
Authorization: Bearer USER_ACCESS_TOKEN
Content-Type: application/json

{
  "reason": "The reported score is incorrect. We won 13-9, not 7-13.",
  "evidence": ["screenshot-url"]
}

Disputed matches are queued for organizer review. The organizer resolves the dispute and sets the final result.

Retrieving match details

GET /api/v1/matches/:id
X-API-Key: YOUR_API_KEY

Response includes both participants, the current score, status, and scheduled time. To get all matches for a tournament:

GET /api/v1/tournaments/:id/schedule
X-API-Key: YOUR_API_KEY

Real-time match updates

Subscribe to match events via Webhooks to receive real-time notifications:

• match.started — match has begun
• match.score_reported — a result was submitted
• match.completed — result confirmed, winner set
• match.disputed — result is under review