# Tournament API

## Endpoints

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

{% embed url="<https://api.hub.crunchdao.com/swagger-ui/index.html>" %}

## Python Client

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

{% embed url="<https://github.com/crunchdao/crunch-cli/tree/master/crunch/api>" %}

### Usage

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

{% code title="Python Code" %}

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

{% endcode %}

{% hint style="info" %}
The `Client.from_env()` function will search for the `CRUNCH_API_KEY` environment variable.
{% endhint %}

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

<table><thead><tr><th width="144.84906005859375">Token Type</th><th>Header</th><th>Query Parameter</th></tr></thead><tbody><tr><td>API Key</td><td><code>Authorization: API-Key &#x3C;token></code> </td><td><code>?apiKey=&#x3C;token></code></td></tr><tr><td>Access Token</td><td><code>Authorization: Bearer &#x3C;token></code> </td><td><code>?accessToken=&#x3C;token></code></td></tr></tbody></table>

You can generate an API-Key in the [API Management section of your account](https://hub.crunchdao.com/account/api).

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

{% code title="API Error Response" %}

```json
{
    // 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"
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.crunchdao.com/technical/tournament-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.