Official Python SDK for interacting with the CommunityOne API. This SDK provides both synchronous and asynchronous methods to interact with CommunityOne's API endpoints.
CommunityOne is a platform that helps Discord communities grow and engage their members through quests, rewards, and gamification.
You can install the package using pip:
pip install communityonefromcommunityoneimportCommunityOneSDK# Initialize the SDK with your server ID and API keysdk=CommunityOneSDK(server_id=YOUR_SERVER_ID, api_key="YOUR_API_KEY")
# Get all custom questscustom_quests=sdk.get_custom_quests()
# Get player informationplayer_info=sdk.get_player_info(discord_user_id="DISCORD_USER_ID")
# Complete a custom questresult=sdk.complete_custom_quest(custom_quest_id="CUSTOM_QUEST_ID", discord_user_id="DISCORD_USER_ID")
# Get completed members for a questcompleted_members=sdk.get_completed_members(custom_quest_id="CUSTOM_QUEST_ID")
# Get global leaderboardleaderboard=sdk.get_global_leaderboard()
# Check whether members were flagged as suspicious accountssuspicious=sdk.check_suspicious_accounts(user_ids=["DISCORD_USER_ID"])
# Get activity insights for membersinsights=sdk.get_member_insights(user_ids=["DISCORD_USER_ID"])
# Get the outcomes recorded for an invite codeoutcomes=sdk.get_invite_outcomes(invite_code="INVITE_CODE")The SDK also provides async methods for all operations:
importasynciofromcommunityoneimportCommunityOneSDKasyncdefmain():
sdk=CommunityOneSDK(server_id=YOUR_SERVER_ID, api_key="YOUR_API_KEY")
# Get custom quests asynchronouslycustom_quests=awaitsdk.get_custom_quests_async()
# Get player information asynchronouslyplayer_info=awaitsdk.get_player_info_async("DISCORD_USER_ID")
# Complete a custom quest asynchronouslyresult=awaitsdk.complete_custom_quest_async(custom_quest_id="CUSTOM_QUEST_ID", discord_user_id="DISCORD_USER_ID")
# Get completed members asynchronouslycompleted_members=awaitsdk.get_completed_members_async(custom_quest_id="CUSTOM_QUEST_ID")
# Get global leaderboard asynchronouslyleaderboard=awaitsdk.get_global_leaderboard_async()
# Check suspicious accounts asynchronouslysuspicious=awaitsdk.check_suspicious_accounts_async(user_ids=["DISCORD_USER_ID"])
# Get member insights asynchronouslyinsights=awaitsdk.get_member_insights_async(user_ids=["DISCORD_USER_ID"])
# Get invite outcomes asynchronouslyoutcomes=awaitsdk.get_invite_outcomes_async(invite_code="INVITE_CODE")
# Run the async codeasyncio.run(main())get_custom_quests(): Get all custom quests for the serverget_player_info(discord_user_id): Get information about a playercomplete_custom_quest(custom_quest_id, discord_user_id): Mark a custom quest as completedget_completed_members(custom_quest_id): Get all members who completed a questget_global_leaderboard(): Get global leaderboard for the servercheck_suspicious_accounts(user_ids): Check whether members were flagged as suspicious accountsget_member_insights(user_ids): Get activity insights for membersget_invite_outcomes(invite_code): Get the outcomes recorded for an invite code
get_custom_quests_async(): Get all custom quests for the server asynchronouslyget_player_info_async(discord_user_id): Get player information asynchronouslycomplete_custom_quest_async(custom_quest_id, discord_user_id): Complete a quest asynchronouslyget_completed_members_async(custom_quest_id): Get completed members asynchronouslyget_global_leaderboard_async(): Get global leaderboard asynchronouslycheck_suspicious_accounts_async(user_ids): Check suspicious accounts asynchronouslyget_member_insights_async(user_ids): Get member insights asynchronouslyget_invite_outcomes_async(invite_code): Get invite outcomes asynchronously
The analytics methods return point-in-time data and require the server to be on the Analytics Premium Level 3 tier. Servers on any other tier get a 403.
check_suspicious_accounts(user_ids) accepts between 1 and 100 Discord user IDs and returns one result per requested ID, in the same order as the request. Requesting more or fewer IDs raises a ValueError before the request is sent.
suspicious=sdk.check_suspicious_accounts(user_ids=["1273073873503522888", "851179040428654623"])
forresultinsuspicious["results"]:
ifresult["flagged"]:
print(result["user_id"], result["flagged_reason"], result["join_date"])A user ID with no suspicious activity is clean, not unknown: it comes back with flagged set to False and every other field set to None. flagged_reason is an open string (currently GROUP_JOIN, JOIN_RIGHT_AFTER_CREATION, RANDOM_USERNAME or SCAMLIKE_CHAT) that may gain new values, and it can be None even when flagged is True.
get_member_insights(user_ids) takes the same 1-100 user IDs and returns per-member activity data such as msg_count, days_present, wpm and most_active_channel_name.
insights=sdk.get_member_insights(user_ids=["1273073873503522888"])
forresultininsights["results"]:
ifresult["found"]:
print(result["username"], result["msg_count"], result["most_active_channel_name"])Here absence genuinely means "no data available", so check found rather than assuming a member is inactive. Requesting unknown IDs is not an error. member_type (MODERATOR or REGULAR_MEMBER) is also an open string.
get_invite_outcomes(invite_code) returns the outcomes for a single invite code as a flat object. The invite code is URL-encoded for you.
outcomes=sdk.get_invite_outcomes(invite_code="abcd1234")
print(outcomes["total_users"], outcomes["total_suspicious_users"])An invite code with no recorded outcomes returns a 404, which surfaces as the usual requests.HTTPError (or aiohttp.ClientResponseError for the async method). This is an expected outcome rather than a fault, so handle it explicitly if you may query codes that were never used:
importrequeststry:
outcomes=sdk.get_invite_outcomes(invite_code="abcd1234")
exceptrequests.HTTPErroraserror:
iferror.response.status_code==404:
outcomes=Noneelse:
raiseInvite codes are only unique within a server, since a released vanity code can later be claimed by a different server, so scope any cached results by server ID.
Discord IDs are sent and returned as strings to avoid precision loss. int values are accepted and coerced with str(). The user_id echoed back in a response is numerically normalized, so an input of "0007" returns as "7" — match results to inputs by array position, or normalize your inputs first.
CommunityOne allows you to test the full quest completion workflow in your application without affecting production quests data, helping you verify quest functionality before releasing it to your community. When a quest is in testing mode:
- The quest won't be visible to regular Discord server members
- No code changes needed! - use the same SDK methods for testing and production quests (the API automatically routes to our internal test environment)
How to enable:
- Go to your server's CommunityOne dashboard
- Navigate to Hype Engine > Custom Quests
- Click the Edit button on your quest
- Enable testing mode
All API endpoints are subject to rate limiting:
- 60 requests per minute per server for the quest and leaderboard endpoints
- 120 requests per minute per server for the analytics endpoints
- Rate limits are applied separately for each endpoint
- Exceeding the rate limit will result in a 429 Too Many Requests response
- Python 3.7 or higher
- requests>=2.25.0
- aiohttp>=3.8.0
This project is licensed under the MIT License - see the LICENSE file for details.