Рекламне оголошення
Рекламне оголошення

Check out Challonge Connect, our new Tournament API Devkit for your Game, Website, or App.

Learn More ×
Рекламне оголошення

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:[email protected]/v1/... Or, if you prefer, you can just pass your API key as parameter api_key to all method calls.

API methods with GET request types are permitted for any tournament, whether belonging to you or not. All other API methods are scoped to tournaments that you either own or have admin access to.

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 - you may also set your request headers to accept application/json, text/xml or application/xml

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
  • 406- Requested format is not supported - request JSON or XML only
  • 422- Validation error(s) for create or update method
  • 500- Something went wrong on our end. If you continually receive this, please contact us.

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.:

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

REST API Methods

Please note, two-stage tournaments are not yet supported by our public API. They'll be available in V2 along with 3+ participant per match support.

Tournaments

Позиція GET Retrieve a set of tournaments created with your account.
Створити POST Create a new tournament.
Показати GET Retrieve a single tournament record created with your account.
Оновити PUT Update a tournament's attributes.
Знищити DELETE Deletes a tournament along with all its associated records. There is no undo, so use with care!
Процес реєстрації POST

This should be invoked after a tournament's check-in window closes before the tournament is started.

  1. Marks participants who have not checked in as inactive.
  2. Moves inactive participants to bottom seeds (ordered by original seed).
  3. Transitions the tournament state from 'checking_in' to 'checked_in'
NOTE: Checked in participants on the waiting list will be promoted if slots become available.
Скасувати участь у турнірі POST

When your tournament is in a 'checking_in' or 'checked_in' state, there's no way to edit the tournament's start time (start_at) or check-in duration (check_in_duration). You must first abort check-in, then you may edit those attributes.

  1. Makes all participants active and clears their checked_in_at times.
  2. Transitions the tournament state from 'checking_in' or 'checked_in' to 'pending'
Почати POST Start a tournament, opening up first round matches for score reporting. The tournament must have at least 2 participants.
Завершити POST Finalize a tournament that has had all match scores submitted, rendering its results permanent.
Скинути POST Reset a tournament, clearing all of its scores and attachments. You can then add/remove/edit participants before starting the tournament again.
Відкрийте для встановлення результатів прогнозів POST Sets the state of the tournament to start accepting predictions. Your tournament's 'prediction_method' attribute must be set to 1 (exponential scoring) or 2 (linear scoring) to use this option. Note: Once open for predictions, match records will be persisted, so participant additions and removals will no longer be permitted.

Participants

Позиція GET Retrieve a tournament's participant list.
Створити POST Add a participant to a tournament (up until it is started).
Масове додавання POST Bulk add participants to a tournament (up until it is started). If an invalid participant is detected, bulk participant creation will halt and any previously added participants (from this API request) will be rolled back.
Показати GET Retrieve a single participant record for a tournament.
Оновити PUT Update the attributes of a tournament participant.
Реєстрація POST Checks a participant in, setting checked_in_at to the current time.
Відмінити реєстрацію POST Marks a participant as having not checked in, setting checked_in_at to nil.
Знищити DELETE If the tournament has not started, delete a participant, automatically filling in the abandoned seed number. If tournament is underway, mark a participant inactive, automatically forfeiting his/her remaining matches.
Очистити DELETE Deletes all participants in a tournament. (Only allowed if tournament hasn't started yet)
Згенерувати випадково POST Randomize seeds among participants. Only applicable before a tournament has started.

Matches

Позиція GET Retrieve a tournament's match list.
Показати GET Retrieve a single match record for a tournament.
Оновити PUT Update/submit the score(s) for a match.
Перевідкрити POST Перевідкриває матч, помічений як закінчений, автоматично скидуючи матчі після нього.
Відмітити як у процесі POST Sets "underway_at" to the current time and highlights the match in the bracket
Зняти відмітку як у процесі POST Clears "underway_at" and unhighlights the match in the bracket

Match Attachments

Позиція GET Retrieve a match's attachments.
Створити POST Add a file, link, or text attachment to a match. NOTE: The associated tournament's "accept_attachments" attribute must be true for this action to succeed.
Показати GET Retrieve a single match attachment record.
Оновити PUT Update the attributes of a match attachment.
Знищити DELETE Delete a match attachment.

Language Specific Libraries & Examples

Ruby

challonge-ruby-gem

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-)

Perl

WWW-Challonge

Perl Module for interfacing the Challonge API (author: Alex Kerr)

API Update and Availability Notices

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

API Changelog

Рекламне оголошення