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


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@api.challonge.com/v1/... 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://api.challonge.com/v1/tournaments.xml or https://api.challonge.com/v1/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 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-)

Javascript

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: 2013-10-17