Challonge API Docs
  1. Sample Use Cases
Challonge API Docs
  • Guides
    • Welcome
    • Changelog
    • Upgrading
      • Upgrading from v2.0 to v2.1
    • Sample Use Cases
      • Running a Two-Stage Tournament
    • Challonge Connect
      • About
      • Game Integration (beta)
      • Connect Request Signing
  • API v2.1
    • Getting Started
    • Authorization
    • Error Responses
    • Resource Scoping
    • OAuth
      • Scopes
      • Grant Request
      • Token Request
      • Refresh Token Request
      • Device Grant Authorization Request
      • Device Grant Access Token Request
    • Tournament API
      • Tournaments
        • Tournament States
        • List Tournaments
        • Create Tournament
        • Get Tournament
        • Update Tournament
        • Delete Tournament
        • Change Tournament State
      • Participants
        • List Participants
        • Create Participant
        • Get Participant
        • Update Participant
        • Delete Participant
        • Bulk Create Participants
        • Clear All Participants
        • Randomize Participants
        • Register Me
      • Matches
        • List Matches
        • Get Match
        • Update Match
        • Change Match State
      • Match Attachments
        • List Match Attachments
        • Create Match Attachment
        • Delete Match Attachment
    • Race API
      • Races
        • List Races
        • Create Race
        • Get Race
        • Update Race
        • Delete Race
        • Change Race State
      • Rounds
        • List Rounds
        • Get Round
        • Update Round
      • Elapsed Times
        • List Elapsed Times
        • Get Elapsed Time
        • Update Elapsed Time
        • Bulk Update Elapsed Times
    • Get User
      GET
    • List Communities
      GET
    • Schemas
      • MatchAttachmentModel
      • MatchAttachmentInput
      • MatchAttachmentOutput
      • MatchAttachment
      • ParticipantModel
      • ParticipantOutput
      • ParticipantInput
      • ParticipantBulkInput
      • Participant
      • TournamentModel
      • TournamentInput
      • Tournament
      • TournamentStateInput
      • CommunityModel
      • Community
      • MatchModel
      • MatchInput
      • MatchOutput
      • Match
      • MatchStateInput
      • ErrorModel
      • UserModel
      • User
      • ElapsedTimeBulkInput
      • ElapsedTimeWithID
      • ElapsedTimeOutput
      • ElaspedTimeInput
      • Timestamps
      • RelationshipLink
      • RoundOutput
      • RoundStateInput
      • RacingOutput
      • RacingInput
      • RacingStateInput
  • Bracket JSAPI v1.0
    • Getting Started
    • Broadcasted Events
    • API Actions
      • scrollToCoordinates
      • scrollToMatchIdentifier
      • setZoomScale
      • zoomToCoordinate
      • zoomToMatchIdentifier
      • loadTheme
      • filterRounds
      • loadIntegrationData
      • setBracketSettings
  • API v2.0 (deprecated)
    • About
    • Deprecated Endpoints
      • Tournament
        • findTournaments
        • createTournament
        • showTournament
        • updateTournament
        • deleteTournament
        • changeStateTournament
      • Match
        • findMatches
        • showMatch
        • updateMatch
        • changeStateTournament
      • Participant
        • findParticipants
        • createParticipant
        • showParticipant
        • updateParticipant
        • deleteParticipant
        • bulkCreateParticipant
        • clearAllParticipants
        • randomizeParticipants
      • Match Attachment
        • findMatchAttachments
        • createMatchAttachments
        • deleteMatchAttachment
      • Race
        • findRaces
        • createRace
        • showRace
        • updateRace
        • deleteRace
        • changeStateRace
      • Round
        • findRounds
        • showRound
        • updateRound
      • Elapsed Time
        • findElapsedTime
        • showElapsedTime
        • updateElapsedTime
        • bulkUpdateElapsedTime
      • User
        • findUser
        • findCommunities
    • Schemas
      • MatchAttachmentModel
      • MatchAttachmentInput
      • MatchAttachmentOutput
      • MatchAttachment
      • ParticipantModel
      • ParticipantOutput
      • ParticipantInput
      • ParticipantBulkInput
      • Participant
      • TournamentModel
      • TournamentInput
      • Tournament
      • TournamentStateInput
      • CommunityModel
      • Community
      • MatchModel
      • MatchInput
      • MatchOutput
      • Match
      • MatchStateInput
      • ErrorModel
      • UserModel
      • User
      • ElapsedTimeBulkInput
      • ElapsedTimeWithID
      • ElapsedTimeOutput
      • ElaspedTimeInput
      • Timestamps
      • RelationshipLink
      • RoundOutput
      • RoundStateInput
      • RacingOutput
      • RacingInput
      • RacingStateInput
  • API v1 (deprecated)
    • About
    • Deprecated Endpoints
      • Tournaments
        • List tournaments
        • Create a tournament
        • Get a tournament
        • Update a tournament
        • Delete a tournament
        • Process check-in results for a tournament
        • Abort check-in for a tournament
        • Start a tournament
        • Finalize a tournament
        • Reset a tournament
        • Open for predictions
      • Participants
        • List a tournament's participants
        • Create a participant
        • Bulk create participants
        • Get a participant
        • Update a participant
        • Check in a participant
        • Undo check-in for a participant
        • Delete/deactivate a participant
        • Clear/delete all participants
        • Randomize a tournament's participants
      • Matches
        • List a tournament's matches
        • Get a match
        • Update a match
        • Reopen a match
        • Mark a match as underway
        • Unmark a match as underway
      • Match Attachments
        • List a match's attachments
        • Create a match attachment
        • Get a match attachment
        • Update a match attachment
        • Delete a match attachment
  1. Sample Use Cases

Running a Two-Stage Tournament

Creating a two-stage tournament#

POST /v2.1/tournaments (Create Tournament)
{
  "data": {
    "type": "Tournaments",
    "attributes": {
      "name": "Test tournament",
      "tournament_type": "single elimination",
  	"match_options": {
    	  "consolation_matches_target_rank": 3
  	},
  	"group_stage_enabled": true,
  	"group_stage_options": {
    	  "stage_type": "round robin",
    	  "group_size": 4,
    	  "participant_count_to_advance_per_group": 2
  	}
    }
  }
}

Adding participants#

Individually#

POST /v2.1/tournaments/{tournament_id}/participants (Create Participant)
{
  "data": {
    "type": "Participants",
    "attributes": {
      "name": "Player 1"
    }
  }
}

In Bulk#

POST /v2.1/tournaments/{tournament_id}/participants/bulk_add (Bulk Create Participants)
{
  "data": {
    "type": "Participants",
    "attributes": {
      "participants": [
        {
          "name": "Player 2"
        },
        {
          "name": "Player 3"
        },
        {
          "name": "Player 4"
        },
        {
          "name": "Player 5"
        },
        {
          "name": "Player 6"
        },
        {
          "name": "Player 7"
        },
        {
          "name": "Player 8"
        }
      ]
    }
  }
}

Starting the group stage#

For a group stage tournament, this starts the tournament.
PUT /v2.1/tournaments/{tournament_id}/change_state (Change Tournament State)
{
  "data": {
    "type": "TournamentState",
      "attributes": {
        "state": "start_group_stage"
      }
    }
  }
}

Fetching open matches#

GET /v2.1/tournaments/{tournament_id}/matches?state=open (List Matches)

Reporting group matches#

PUT /v2.1/tournaments/{tournament_id}/matches/{match_id} (Update Match)
This example reports a 3-1 win for participant ID 215353979.
{
  "data": {
    "type": "Match",
    "attributes": {
      "match": [
        {
          "participant_id": "215353979",
          "score_set": "3",
          "advancing": true
        },
        {
          "participant_id": "215353980",
          "score_set": "1"
        }
      ]
    }
  }
}

Finalizing the group stage#

This should be run once all group stage matches are complete.
PUT /v2.1/tournaments/{tournament_id}/change_state (Change Tournament State)
{
  "data": {
    "type": "TournamentState",
      "attributes": {
        "state": "finalize_group_stage"
      }
    }
  }
}

Starting the final stage#

PUT /v2.1/tournaments/{tournament_id}/change_state (Change Tournament State)
{
  "data": {
    "type": "TournamentState",
      "attributes": {
        "state": "start"
      }
    }
  }
}

Fetching open matches#

Same as the group stage, but matches will have null values for group_id.
GET GET /v2.1/tournaments/{tournament_id}/matches?state=open (List Matches)

Reporting final stage matches#

Same procedure as group stage matches, but matches will have null values for group_id.
PUT /v2.1/tournaments/{tournament_id}/matches/{match_id} (Update Match)

Finalizing the tournament#

Once all matches are complete, the tournament state will automatically transition to “awaiting_review”. Finalize it to wrap up and get final rank values for all participants.
PUT /v2.1/tournaments/{tournament_id}/change_state (Change Tournament State)
{
  "data": {
    "type": "TournamentState",
      "attributes": {
        "state": "finalize"
      }
    }
  }
}

Fetching participant final ranks#

GET /v2.1/tournaments/{tournament_id}/participants (List Participants)
“final_rank” will be assigned for all final stage participants. Let us know if you need this set for group stage participants and we can update the API accordingly.
Modified at 2025-11-04 17:44:12
Previous
Upgrading from v2.0 to v2.1
Next
About
Built with