docs/codabench-upload-api.md

Codabench Competition Bundle Upload Script

This document describes the upload utility, which transfers a Codabench competition bundle ZIP file to a Codabench instance through the Codabench REST API. We provide this utility so that a validated bundle can be published without manual interaction with the Codabench web interface.

The script performs the following steps automatically:

1. Authenticate with Codabench
2. Create a competition bundle dataset
3. Upload the ZIP file
4. Finalize the upload
5. Wait for the competition to be created

Requirements

The utility depends on one third-party package, which can be installed as follows:

pip install python-dotenv

Configuration is supplied through a .env file with the following contents:

CODABENCH_BASE_URL=https://www.codabench.org
CODABENCH_TOKEN=your_token_here  # optional; omit to authenticate with --username/--password

The CODABENCH_TOKEN entry is optional; when it is omitted, the script obtains a token from the username and password supplied on the command line.

Usage

The following invocation authenticates with an API token read from .env:

python -m autocodabench.upload.codabench_api competition_bundle.zip

Alternatively, the script accepts a username and password, from which it obtains a token at runtime:

python -m autocodabench.upload.codabench_api \
  --username USERNAME \
  --password PASSWORD \
  competition_bundle.zip

A self-hosted or otherwise non-default Codabench instance can be targeted by overriding the base URL:

python -m autocodabench.upload.codabench_api \
  --base-url https://your-codabench-instance.org \
  competition_bundle.zip