Tournament API

How to use the API to interact with the website.

Endpoints

Most endpoints are documented in the Swagger UI, which is available here:

Swagger UIapi.hub.crunchdao.com

Python Client

The crunch-cli offer an API client to easily use do action on the platform:

crunch-cli/crunch/api at master · crunchdao/crunch-cliGitHub

Usage

The following code export the all the leaderboards from the ADIA Lab Structural Break competition:

Python Code

import crunch

client = crunch.api.Client.from_env()

competition = client.competitions.get("structural-break")
round_ = competition.rounds.get(1)
phase = round_.phases.submission

for crunch_ in phase.crunches:
    if not crunch_.published:
        continue

    df = competition.leaderboards.get_default(crunch=crunch_).as_dataframe()
    df.to_csv(f"{crunch_.number}.csv", index=False)

The Client.from_env() function will search for the CRUNCH_API_KEY environment variable.

Features

• Fluent syntax

• Frequently used routines

• Typing

• Maintained by us and always up-to-date

• Error classes, for easier try-except

Authentication

There are multiple ways to authenticate:

Token Type	Header	Query Parameter
API Key	Authorization: API-Key <token>	?apiKey=<token>
Access Token	Authorization: Bearer <token>	?accessToken=<token>

You can generate an API-Key in the API Management section of your account.

Error

Any message that does not return a 2XX or 3XX error code is considered an error.

All errors are formatted in the following way:

API Error Response

{
    // A unique code, always in UPPER AND SNAKE_CASE
    "code": "SUBMISSION_NOT_FOUND",

    // A message, that often, contains more details
    "message": "submission not found",

    // More properties that provide additional context
    "submissionNumber": 123,
    "projectName": "my-model"
}