Demo Upload Flow

This page describes what happens from upload to terminal state.

Upload endpoint

POST /api/public/v1/demos/upload

  • Content type: multipart/form-data
  • Required field: file
  • Allowed extension(s): configured by PUBLIC_API_ALLOWED_DEMO_EXTENSIONS (default .dem)
  • Max size: PUBLIC_API_MAX_UPLOAD_BYTES (default 536870912 = 512 MB)

cURL

curl -X POST "$BASE_URL/api/public/v1/demos/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@$DEMO_FILE"

Example env:

export BASE_URL="https://highlights-api.rankacy.com"
export TOKEN="rk_live_..."

Python (httpx)

import httpx

base_url = "https://highlights-api.rankacy.com"
token = "rk_live_..."
file_path = "/absolute/path/to/match.dem"

with httpx.Client(timeout=120) as client:
    with open(file_path, "rb") as f:
        resp = client.post(
            f"{base_url}/api/public/v1/demos/upload",
            headers={"Authorization": f"Bearer {token}"},
            files={"file": ("match.dem", f, "application/octet-stream")},
        )
    resp.raise_for_status()
    print(resp.json())

Status lifecycle

Upload response:

{
  "demo_id": 52,
  "status": "queued",
  "auto_highlight_requested": false,
  "was_already_processed_successfully": false,
  "user_demo_assignment": "newly_assigned"
}

Processing lifecycle:

  • upload accepted -> demo row created or reused
  • worker picks demo -> PROCESSING
  • terminal state -> SUCCESS or FAILED

Detail endpoint:

GET /api/public/v1/demos/{demo_id}

Duplicate upload behavior

If the uploaded content hash already exists:

  • the existing demo is linked to your user if needed
  • status may return existing state (new, processing, success, failed)
  • was_already_processed_successfully is true when the existing demo is already SUCCESS
  • user_demo_assignment tells link state:
  • newly_assigned when this upload created the link
  • already_assigned when the link already existed

Auto "TOP 5 highlight" behavior

auto_highlight_requested can become true when:

  • uploaded file matches an already processed demo (SUCCESS)
  • your user was newly linked to that demo
  • highlight options are available
  • auto-build has enough kill data

Otherwise it is false.

Failure examples

Empty file:

{"detail": "Uploaded file is empty"}

Too large:

{"detail": "Uploaded file exceeds 536870912 bytes limit"}

Unsupported extension:

{"detail": "Unsupported demo file extension"}