Challonge API 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 https://challonge.com/api/

Authentication

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: https://username:password@challonge.com/api/... 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. https://challonge.com/api/tournaments.xml or https://challonge.com/api/tournaments.json

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 - Invalid API key
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"?>
<errors>
  <error>Name can't be blank</error>
  <error>URL can't be blank</error>
</errors>

{"errors":["Name can't be blank","URL can't be blank"]}

REST API Methods

Tournaments

index	GET	tournaments
create	POST	tournaments
show	GET	tournaments/:tournament
update	PUT	tournaments/:tournament
destroy	DELETE	tournaments/:tournament
start	POST	tournaments/:tournament/start
finalize	POST	tournaments/:tournament/finalize
reset	POST	tournaments/:tournament/reset

Participants

index	GET	tournaments/:tournament/participants
create	POST	tournaments/:tournament/participants
show	GET	tournaments/:tournament/participants/:participant_id
update	PUT	tournaments/:tournament/participants/:participant_id
destroy	DELETE	tournaments/:tournament/participants/:participant_id
randomize	GET	tournaments/:tournament/participants/randomize

Matches

index	GET	tournaments/:tournament/matches
show	GET	tournaments/:tournament/matches/:match_id
update	PUT	tournaments/:tournament/matches/:match_id

Language Specific Libraries & Examples

Ruby

challonge-api

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

PHP

challonge-php

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

Python

pychallonge

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

API Update and Availability Notices

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

Last Updated: 2013-02-26