TopK SDK

0.8.1 verified Fri May 01 auth: no python

Official Python SDK for TopK.io, a real-time rankings and leaderboard API. Version 0.8.1 supports Python >=3.9. Active development with frequent releases.

pip install topk-sdk

Common errors

error AttributeError: module 'topk' has no attribute 'TopKClient' ↓

cause Installed the wrong package (e.g., 'topk' from PyPI is a different library) or imported topk_sdk instead of topk.

fix

Uninstall any conflicting packages: pip uninstall topk topk_sdk. Then install topk-sdk: pip install topk-sdk. Import as 'from topk import TopKClient'.

error TypeError: __init__() takes 1 positional argument but 3 were given ↓

cause Using old positional argument style for TopKClient.

fix

Use keyword arguments: TopKClient(api_key='...', project_id='...').

error topk.exceptions.TopKError: (403) Forbidden ↓

cause Invalid or expired API key, or the API key does not have access to the project.

fix

Check your TOPK_API_KEY and TOPK_PROJECT_ID environment variables. Ensure the API key is active in the TopK dashboard.

Warnings

breaking In version 0.6.0, the client initialization changed from positional arguments to keyword-only parameters. ↓

fix Use keyword arguments: TopKClient(api_key='...', project_id='...') instead of TopKClient('...', '...').

gotcha The SDK only supports asynchronous methods? No — all methods are synchronous by default. There is no async support currently. ↓

fix Call methods directly without await; they return immediately.

gotcha The 'leaderboard' parameter in upsert_score and get_leaderboard is case-sensitive and must match exactly what was created in the TopK dashboard. ↓

fix Verify the leaderboard name in your TopK dashboard and use identical casing.

Imports

TopKClient
wrong
```
from topk_sdk import TopKClient
```
correct
```
from topk import TopKClient
```
The package is imported as 'topk', not 'topk_sdk'.
TopKError
wrong
```
from topk import TopKError
```
correct
```
from topk.exceptions import TopKError
```
Exception classes are in the exceptions submodule.

Quickstart

Initialize client with env vars, upsert a score, and retrieve the top 10 leaderboard.

import os
from topk import TopKClient

client = TopKClient(
    api_key=os.environ.get('TOPK_API_KEY', ''),
    project_id=os.environ.get('TOPK_PROJECT_ID', '')
)

# Upsert a score
response = client.upsert_score(
    leaderboard='global',
    user_id='user123',
    score=1000
)
print(response)

# Get leaderboard
leaderboard = client.get_leaderboard(leaderboard='global', limit=10)
print(leaderboard)