Overview
The Match Lifecycle API allows you to query match information including details, rosters, and current status. Game developers with read-write access can also manage match state.
Endpoints
List Matches
POST /api/v1/game/matches
| Field | Type | Required | Description |
|---|
gameId | string | Yes | Filter by game ID (must match your approved game) |
status | string | No | Filter by status: IN_PROGRESS, COMPLETED, CANCELLED, etc. |
limit | number | No | Results per page (default: 25, max: 100) |
cursor | string | No | Pagination cursor from previous response |
{
"gameId": "call_of_duty_black_ops_7",
"status": "IN_PROGRESS",
"limit": 25
}
{
"matches": [
{
"id": "match_123",
"status": "IN_PROGRESS",
"gameMode": "hardpoint",
"bestOf": 3,
"creatorTeam": { "teamId": "team_abc", "name": "Alpha Squad" },
"acceptedTeam": { "teamId": "team_def", "name": "Beta Force" },
"creatorTeamScore": 1,
"acceptedTeamScore": 0,
"scheduledAt": null,
"startedAt": "2026-02-23T10:05:00.000Z",
"completedAt": null,
"createdAt": "2026-02-23T10:00:00.000Z"
}
],
"count": 1,
"pagination": { "cursor": "25", "hasMore": true },
"timestamp": "2026-02-23T10:30:00.000Z"
}
Get Match Details
GET /api/v1/game/matches/{matchId}
{
"id": "match_123",
"gameId": "call_of_duty_black_ops_7",
"status": "ACTIVE",
"settings": {
"teamSize": 4,
"gameMode": "hardpoint",
"map": "skidrow"
},
"teams": [
{
"teamId": "team_abc",
"name": "Alpha Squad",
"side": "home"
},
{
"teamId": "team_def",
"name": "Beta Force",
"side": "away"
}
],
"createdAt": "2026-02-23T10:00:00Z",
"startedAt": "2026-02-23T10:05:00Z"
}
Get Match Rosters
GET /api/v1/game/matches/{matchId}/rosters
{
"rosters": [
{
"teamId": "team_abc",
"players": [
{
"userId": "user_1",
"username": "PlayerOne",
"role": "captain"
},
{
"userId": "user_2",
"username": "PlayerTwo",
"role": "member"
}
]
}
]
}
Get Match Status
GET /api/v1/game/matches/{matchId}/status
{
"matchId": "match_123",
"status": "ACTIVE",
"scores": null,
"winner": null,
"completedAt": null
}
Update Match Status
PATCH /api/v1/game/matches/{matchId}/status
{
"status": "IN_PROGRESS"
}
| From | To |
|---|
READY | IN_PROGRESS |
IN_PROGRESS | COMPLETED, CANCELLED |
ACCEPTED | CANCELLED |
COMPLETED status is typically set automatically when sufficient map scores are confirmed. To complete a match, submit scores via the score submission endpoints instead of setting the status directly.
{
"success": true,
"matchId": "match_123",
"previousStatus": "READY",
"newStatus": "IN_PROGRESS",
"timestamp": "2026-02-23T10:05:00.000Z"
}
Submit Player Stats
POST /api/v1/game/matches/{matchId}/player-stats
mapIndex.
Request Body (JSON):
{
"mapIndex": 0,
"playerStats": {
"userId1": { "kills": 25, "deaths": 15, "assists": 5 },
"userId2": { "kills": 18, "deaths": 20, "assists": 8 }
}
}
{
"success": true,
"mapIndex": 0,
"action": "updated"
}
Permissions
| Endpoint | Required Permission |
|---|
| List matches | game.lifecycle: read |
| Get match details | game.lifecycle: read |
| Get match rosters | game.lifecycle: read |
| Get match status | game.lifecycle: read |
| Update match status | game.lifecycle: read-write |
| Submit player stats | game.scores: write |
