Quickstart

This quickstart uses only the Public API and working request examples.

Prerequisites

  • Public API token (rk_live_...)
  • demo file (.dem)
  • curl + jq

Set these environment variables:

export BASE_URL="https://highlights-api.rankacy.com"
export TOKEN="rk_live_..."
export DEMO_FILE="/absolute/path/to/match.dem"

1) First API request

curl -sS "$BASE_URL/api/public/v1/demos?limit=5&offset=0" \
  -H "Authorization: Bearer $TOKEN" | jq

2) Upload demo

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

echo "$UPLOAD_RESPONSE" | jq
export DEMO_ID=$(echo "$UPLOAD_RESPONSE" | jq -r '.demo_id')

Notes from upload response:

  • was_already_processed_successfully=true means this content hash was already SUCCESS before this call.
  • user_demo_assignment tells whether this call newly linked the demo to your user.
  • generate_auto_highlight request field controls auto TOP5 generation for this user-demo link (default true).
  • Upload-time auto TOP5 generation needs generate_auto_highlight=true plus resolution_id and fps_id together.
  • Auto-generated TOP5 highlights created from upload processing always store show_tick=false.

3) Poll demo status

curl -sS "$BASE_URL/api/public/v1/demos/$DEMO_ID" \
  -H "Authorization: Bearer $TOKEN" | jq

Possible demo states:

  • NEW
  • PROCESSING
  • SUCCESS
  • FAILED

4) Read parsed kills and players

KILLS_RESPONSE=$(curl -sS -G "$BASE_URL/api/public/v1/demos/$DEMO_ID/kills" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=0")

echo "$KILLS_RESPONSE" | jq
export DEMO_KILL_ID=$(echo "$KILLS_RESPONSE" | jq -r '.items[0].demo_kill_id // empty')
export DEMO_KILL_TICK=$(echo "$KILLS_RESPONSE" | jq -r '.items[0].tick // empty')
export DEMO_KILL_ATTACKER_STEAM_ID=$(echo "$KILLS_RESPONSE" | jq -r '.items[0].attacker_steam_id // empty')

curl -sS "$BASE_URL/api/public/v1/demos/$DEMO_ID/players" \
  -H "Authorization: Bearer $TOKEN" | jq

5) Query highlight options and cost

curl -sS "$BASE_URL/api/public/v1/highlights/resolutions" \
  -H "Authorization: Bearer $TOKEN" | jq

curl -sS "$BASE_URL/api/public/v1/highlights/fps" \
  -H "Authorization: Bearer $TOKEN" | jq

curl -sS "$BASE_URL/api/public/v1/highlights/cost?resolution_id=1&fps_id=1" \
  -H "Authorization: Bearer $TOKEN" | jq

curl -sS "$BASE_URL/api/public/v1/me/credit" \
  -H "Authorization: Bearer $TOKEN" | jq

6) Queue highlight jobs

Standard:

HIGHLIGHT_RESPONSE=$(curl -sS -X POST "$BASE_URL/api/public/v1/highlights" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"demo_id\":$DEMO_ID,\"resolution_id\":1,\"fps_id\":1,\"title\":\"Quickstart auto\",\"show_tick\":true}")

echo "$HIGHLIGHT_RESPONSE" | jq
export HIGHLIGHT_ID=$(echo "$HIGHLIGHT_RESPONSE" | jq -r '.highlight_id // empty')

Read highlight detail (including containers + events):

if [ -n "${HIGHLIGHT_ID:-}" ]; then
  curl -sS "$BASE_URL/api/public/v1/highlights/$HIGHLIGHT_ID" \
    -H "Authorization: Bearer $TOKEN" | jq
fi

Optional cleanup:

if [ -n "${HIGHLIGHT_ID:-}" ]; then
  curl -sS -X DELETE "$BASE_URL/api/public/v1/highlights/$HIGHLIGHT_ID" \
    -H "Authorization: Bearer $TOKEN" | jq
fi

By ticks:

if [ -n "$DEMO_KILL_TICK" ] && [ -n "$DEMO_KILL_ATTACKER_STEAM_ID" ]; then
  curl -sS -X POST "$BASE_URL/api/public/v1/highlights/by-ticks" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"demo_id\":$DEMO_ID,\"ticks\":[{\"start_tick\":$DEMO_KILL_TICK,\"end_tick\":$DEMO_KILL_TICK,\"steam_id\":\"$DEMO_KILL_ATTACKER_STEAM_ID\"}],\"resolution_id\":1,\"fps_id\":1,\"show_tick\":true}" | jq
fi

By kill (when kill data exists):

if [ -n "$DEMO_KILL_ID" ]; then
  curl -sS -X POST "$BASE_URL/api/public/v1/highlights/by-kill" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"demo_id\":$DEMO_ID,\"demo_kill_ids\":[$DEMO_KILL_ID],\"resolution_id\":1,\"fps_id\":1,\"show_tick\":true}" | jq
fi

7) Read account transactions

curl -sS "$BASE_URL/api/public/v1/me/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN" | jq

Primary integration example for developers

Use the local FastAPI integration app that talks to DEV: