API.md

HTTP API and Web UI Usage

This project includes an HTTP server binary named api_server.

It keeps the original bulk_download logic unchanged. The server exposes:

• a Web control panel at / and /ui
• JSON APIs under /health and /jobs

Start locally

cargo build --release --bin bulk_download --bin api_server
./target/release/api_server

Default address:

http://localhost:7860

Change port:

API_PORT=8080 ./target/release/api_server

If api_server cannot find bulk_download, set it explicitly:

BULK_DOWNLOAD_BIN=./target/release/bulk_download \
BULK_DOWNLOAD_WORKDIR=. \
./target/release/api_server

Web UI

Open:

http://localhost:7860/

The page lets you:

• submit a trading date in YYYYMMDD format
• choose concurrency
• enable or disable forced re-download
• view job status
• inspect final stdout / stderr log tails

JSON API endpoints

Health check

curl http://localhost:7860/health

Create a download job

curl -X POST http://localhost:7860/jobs \
  -H 'Content-Type: application/json' \
  -d '{"date":20260224,"concurrent":50,"force":false}'

Response example:

{
  "job_id": "job-20260425080000-1",
  "status": "running",
  "status_url": "/jobs/job-20260425080000-1"
}

Request fields:

• date: trading date in YYYYMMDD format.
• concurrent: concurrency, default is 50.
• force: force re-download, default is false.

Get one job status

curl http://localhost:7860/jobs/job-20260425080000-1

Statuses:

• running
• succeeded
• failed

The response includes stdout_tail and stderr_tail for the final logs.

List all jobs

curl http://localhost:7860/jobs

Hugging Face Spaces notes

Use a Docker Space and expose port 7860.

ClickHouse should be external for Hugging Face Spaces. The existing docker-compose.yml will not automatically start as a multi-container service inside a Docker Space.