Challonge Premier
Hide ads + Support us
Close this ad

Challonge API v1 Documentation

The Challonge API expands tournament creation and control to the programmatic level. You can create tournaments on the fly and report scores directly from your application. This allows you to define score reporting permissions that fit your user model, and provide a more seamless tournament experience for your users.

The API is accessible over a secure connection at


All interactions with the API require a Challonge account with a verified email address and API key. We support HTTP basic authentication. Username = your Challonge username, Password = your API key. Many clients format these requests as: Or, if you prefer, you can just pass your API key as parameter api_key to all method calls.

Response Formats

XML or JSON The extension in your request indicates your desired response. e.g. or

Response Codes

The following HTTP response codes are issued by the API. All other codes are the result of a request not reaching the application.

  • 200 - OK
  • 401 - Unauthorized (Invalid API key or insufficient permissions)
  • 404 - Object not found within your account scope
  • 422 - Validation error(s) for create or update method

Validation Errors

Requests that complete but have validation errors or other issues will return an array of error messages and status code 422. e.g.:

<?xml version="1.0" encoding="UTF-8"?>
  <error>Name can't be blank</error>
  <error>URL can't be blank</error>
{"errors":["Name can't be blank","URL can't be blank"]}

REST API Methods


Index GET tournaments
Create POST tournaments
Show GET tournaments/:tournament
Update PUT tournaments/:tournament
Destroy DELETE tournaments/:tournament
Process Check-ins POST tournaments/:tournament/process_check_ins
Abort Check-in POST tournaments/:tournament/abort_check_in
Start POST tournaments/:tournament/start
Finalize POST tournaments/:tournament/finalize
Reset POST tournaments/:tournament/reset


Index GET tournaments/:tournament/participants
Create POST tournaments/:tournament/participants
Bulk Add POST tournaments/:tournament/participants/bulk_add
Show GET tournaments/:tournament/participants/:participant_id
Update PUT tournaments/:tournament/participants/:participant_id
Check In POST tournaments/:tournament/participants/:participant_id/check_in
Destroy DELETE tournaments/:tournament/participants/:participant_id
Randomize POST tournaments/:tournament/participants/randomize


Index GET tournaments/:tournament/matches
Show GET tournaments/:tournament/matches/:match_id
Update PUT tournaments/:tournament/matches/:match_id

Match Attachments

Index GET tournaments/:tournament/matches/:match_id/attachments
Create POST tournaments/:tournament/matches/:match_id/attachments
Show GET tournaments/:tournament/matches/:match_id/attachments/:attachment_id
Update PUT tournaments/:tournament/matches/:match_id/attachments/:attachment_id
Destroy DELETE tournaments/:tournament/matches/:match_id/attachments/:attachment_id

Language Specific Libraries & Examples



A Ruby gem provided by us that greatly eases integration with the Challonge API



PHP wrapper class for the Challonge API that utilizes cURL and SimpleXML (author: Tony Drake)



Python bindings for the Challonge API (author: russ-)


Challonge jQuery Plugin

Easily embed Challonge brackets in your website using jQuery

API Update and Availability Notices

We strongly encourage API users to join the Challonge API Google Group for all API-related notices.

Last Updated: 2014-07-28