{"id":24719,"library":"topk-sdk","title":"TopK SDK","description":"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.","status":"active","version":"0.8.1","language":"python","source_language":"en","source_url":"https://github.com/topk-io/topk-sdk-python","tags":["sdk","leaderboard","rankings","topk"],"install":[{"cmd":"pip install topk-sdk","lang":"bash","label":"Install via pip"}],"dependencies":[],"imports":[{"note":"The package is imported as 'topk', not 'topk_sdk'.","wrong":"from topk_sdk import TopKClient","symbol":"TopKClient","correct":"from topk import TopKClient"},{"note":"Exception classes are in the exceptions submodule.","wrong":"from topk import TopKError","symbol":"TopKError","correct":"from topk.exceptions import TopKError"}],"quickstart":{"code":"import os\nfrom topk import TopKClient\n\nclient = TopKClient(\n    api_key=os.environ.get('TOPK_API_KEY', ''),\n    project_id=os.environ.get('TOPK_PROJECT_ID', '')\n)\n\n# Upsert a score\nresponse = client.upsert_score(\n    leaderboard='global',\n    user_id='user123',\n    score=1000\n)\nprint(response)\n\n# Get leaderboard\nleaderboard = client.get_leaderboard(leaderboard='global', limit=10)\nprint(leaderboard)","lang":"python","description":"Initialize client with env vars, upsert a score, and retrieve the top 10 leaderboard."},"warnings":[{"fix":"Use keyword arguments: TopKClient(api_key='...', project_id='...') instead of TopKClient('...', '...').","message":"In version 0.6.0, the client initialization changed from positional arguments to keyword-only parameters.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Call methods directly without await; they return immediately.","message":"The SDK only supports asynchronous methods? No — all methods are synchronous by default. There is no async support currently.","severity":"gotcha","affected_versions":"all"},{"fix":"Verify the leaderboard name in your TopK dashboard and use identical casing.","message":"The 'leaderboard' parameter in upsert_score and get_leaderboard is case-sensitive and must match exactly what was created in the TopK dashboard.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Uninstall any conflicting packages: pip uninstall topk topk_sdk. Then install topk-sdk: pip install topk-sdk. Import as 'from topk import TopKClient'.","cause":"Installed the wrong package (e.g., 'topk' from PyPI is a different library) or imported topk_sdk instead of topk.","error":"AttributeError: module 'topk' has no attribute 'TopKClient'"},{"fix":"Use keyword arguments: TopKClient(api_key='...', project_id='...').","cause":"Using old positional argument style for TopKClient.","error":"TypeError: __init__() takes 1 positional argument but 3 were given"},{"fix":"Check your TOPK_API_KEY and TOPK_PROJECT_ID environment variables. Ensure the API key is active in the TopK dashboard.","cause":"Invalid or expired API key, or the API key does not have access to the project.","error":"topk.exceptions.TopKError: (403) Forbidden"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}