Stats Cache Manager - API Contract

GET /api/v1/stats-cache/api/v1/stats-cache/:cache_key

Inspect a cache entry by key — returns metadata and TTL (not the cached payload)

Public

Response Example

{
  "cache_key": "coordinator_stats:coord_4f8a21:last_30_days",
  "exists": true,
  "created_at": "2026-03-25T14:02:11Z",
  "expires_at": "2026-03-25T14:17:11Z",
  "ttl_seconds": 720,
  "type": "CoordinatorStatsSummary"
}

DELETE /api/v1/stats-cache/api/v1/stats-cache/:cache_key

Invalidate a single cache entry by key

Public

Response Example

{
  "cache_key": "coordinator_stats:coord_4f8a21:last_30_days",
  "invalidated": true
}

DELETE /api/v1/stats-cache/api/v1/stats-cache/coordinator/:coordinator_id

Invalidate all cache entries associated with a coordinator (e.g. after data update)

Public

Response Example

{
  "coordinator_id": "coord_4f8a21",
  "invalidated_count": 5,
  "invalidated_keys": [
    "coordinator_stats:coord_4f8a21:last_7_days",
    "coordinator_stats:coord_4f8a21:last_30_days",
    "coordinator_stats:coord_4f8a21:last_90_days",
    "coordinator_stats:coord_4f8a21:activity_breakdown:last_30_days",
    "coordinator_stats:coord_4f8a21:peer_roster:last_30_days"
  ]
}

GET /api/v1/stats-cache/api/v1/stats-cache

List all active cache entries with metadata (admin/debug use)

Public

Response Example

{
  "data": [
    {
      "cache_key": "coordinator_stats:coord_4f8a21:last_30_days",
      "type": "CoordinatorStatsSummary",
      "coordinator_id": "coord_4f8a21",
      "created_at": "2026-03-25T14:02:11Z",
      "expires_at": "2026-03-25T14:17:11Z",
      "ttl_seconds": 720
    },
    {
      "cache_key": "personal_stats:mentor_b2c91a:last_30_days",
      "type": "PersonalStatsSummary",
      "coordinator_id": null,
      "created_at": "2026-03-25T13:55:40Z",
      "expires_at": "2026-03-25T14:10:40Z",
      "ttl_seconds": 180
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 31
  }
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}