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
  • Optional field: generate_auto_highlight (true|false, default true)
  • Optional field: resolution_id (must be sent together with fps_id)
  • Optional field: fps_id (must be sent together with resolution_id)
  • 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" \
  -F "generate_auto_highlight=true" \
  -F "resolution_id=1" \
  -F "fps_id=1"

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")},
            data={
                "generate_auto_highlight": "true",
                "resolution_id": "1",
                "fps_id": "1",
            },
        )
    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",
  "auto_highlight_skip_reason": null,
  "auto_highlight_skip_message": null,
  "auto_highlight_estimated_credit": 0.1,
  "auto_highlight_current_credit": 20.0
}

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)
  • generate_auto_highlight=true for your user-demo link
  • both resolution_id and fps_id are present and valid
  • the account has enough credit for the requested render settings
  • highlight options are available
  • auto-build has enough kill data

Otherwise it is false.

When upload-time auto generation is skipped, the response includes:

  • auto_highlight_skip_reason
  • auto_highlight_skip_message
  • auto_highlight_estimated_credit / auto_highlight_current_credit when cost was computed

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"}