Overview
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.
Getting Started
API Root URL
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.
You can generate one on the 'Password / API Key' tab of your account settings page.
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 |
| publish | POST | tournaments/publish/:tournament |
| start | POST | tournaments/start/:tournament |
| reset | POST | tournaments/reset/:tournament |
• 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 | POST | 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 Upgrade Notices
We'll maintain backward compatibility as much as possible with new API releases, but some changes may require action on your part. To receive notices about API releases ahead of time, contact us and we'll add you to the notification list. We'll also tweet all API releases (twitter.com/challonge)
