# Gaming Stats API — Valorant

> A reusable, self-hostable Valorant stats API for tracked Riot IDs.

Base URL: http://api.aniketraj.me/custom/valorant
Version: 3.8.3

## What it does
- refreshes tracked stats from tracker.gg through Apify
- refreshes profile data from HenrikDev and enriches card/title assets with Valorant API
- stores one snapshot per tracked Riot ID on disk
- serves cached snapshot data through an authenticated API
- never scrapes tracker.gg during request handling

## Authentication
All http://api.aniketraj.me/custom/valorant/stats routes require an API key in the X-API-Key request header.

Example:
  X-API-Key: your-key-here

Missing or invalid key returns:
  401 { "error": "Invalid or missing API key" }

## Tracked usernames
Only configured Riot IDs are available.

Tracked usernames:
- Spider31415#6921

If a user is not configured:
  404 { "error": "User not tracked" }

If a tracked user does not have a snapshot yet:
  404 { "error": "Tracked user has no cached snapshot yet" }

## Request model
Endpoint:
  POST /stats/:username

Path parameter:
  username = URL-encoded Riot ID
  Example: Spider31415%236921

Body shape:
{
  "playlist": "competitive",
  "modules": {
    "profile": {},
    "agents": {},
    "maps": { "playlist": "unrated", "limit": 3 },
    "rank": {},
    "totalPlaytime": {}
  }
}

Rules:
- playlist must be competitive or unrated
- modules is required and must be an object
- valid modules are profile, rank, agents, maps, totalPlaytime
- profile is not playlist-scoped
- rank is Henrik-backed and is returned from the competitive response branch for compatibility
- totalPlaytime always comes from the shared snapshot
- limit must be a positive integer

## Response shape
{
  "username": "Spider31415#6921",
  "playlist": "competitive",
  "cachedAt": "2026-05-19T10:00:00.000Z",
  "nextRefreshAt": "2026-05-21T10:00:00.000Z",
  "status": "ok",
  "sources": {
    "henrik": {
      "status": "ok",
      "lastRefreshedAt": "2026-05-20T12:15:00.000Z"
    }
  },
  "data": {
    "profile": {
      "accountLevel": 514,
      "region": "ap",
      "card": {
        "id": "67d7faa4-4b40-e16a-1c54-0f9b41919849",
        "name": "VCT x SEN Card",
        "displayIcon": "https://...",
        "smallArt": "https://...",
        "wideArt": "https://...",
        "largeArt": "https://..."
      },
      "title": {
        "id": "ae54c1ce-42b9-3dc1-5e91-6c9e9161b01a",
        "name": "Gnarly Title",
        "displayText": "Gnarly"
      }
    },
    "rank": {},
    "agents": [],
    "maps": [],
    "totalPlaytime": {}
  }
}

Agent artwork fields:
  icon, displayIconSmall, portrait, portraitV2, bustPortrait,
  killfeedPortrait, minimapPortrait, background,
  homeScreenPromoTileImage, roleIcon, abilityIcons[]

Map artwork fields:
  displayIcon, splash, listViewIcon, listViewIconTall, backgroundImage,
  stylizedBackgroundImage, premierBackgroundImage

## Refresh model
- default refresh interval: 48 hours
- built-in scheduler enabled: yes
- tracker refresh command: npm run refresh:snapshots
- Henrik profile/rank refresh command: npm run refresh:profiles

## Player visibility requirement
Tracked players need a public tracker.gg profile, or their stats cannot be scraped.

Current verified flow:
1. Open an incognito/private browser window.
2. Sign in to the correct Riot account.
3. Open your Valorant profile on tracker.gg.
4. Check “I acknowledge signing in makes my profile public to all users”.
5. Click “Sign in with Riot”.
6. Enter credentials manually and finish the flow.