🆕API Quests
Click here to introduce our bot to your server.
Getting started
To get started, go to your Dashboard => Hype Engine ⇒ Custom Quests ⇒ Add Quest ⇒ Quest Type: API
If this is your first time, you will see a pop-up where you can request an API Key; otherwise, when you go to the Custom Quests tab, you should see your API key.
Resources & Document
API Documentation: https://api.communityone.io/v1/documentation
If you are using Cursor or any AI coding cool, simply download our openAPI JSON doc and let your AI code for you:
Our python SDK is out: https://pypi.org/project/communityone/
You should be able to integrate your quests with your Discord in 3 lines.
Javascript/Typescript SDK: https://www.npmjs.com/package/communityone!
First, Authentication:
Every server will be given a unique API key in their configuration dashboard.
You must include the API key directly in the header of every request to the API like this:
{"Authorization": "YOUR_API_KEY"}If authentication fails, the server will receive a 401 Unauthorized response. Unauthorized (401) response:
{"detail": "Invalid API key"}API Endpoints:
The base URL for all API endpoints is api.communityone.io/v1. This is the root endpoint for the CommunityOne API (version 1).
This is the list of available endpoints, more details about each can be found below:
/servers/{server_id}/custom-quests- Get all api-controlled custom quests for the discord server/servers/{server_id}/players/{discord_user_id}- Get information about a specific player/servers/{server_id}/custom-quests/{custom_quest_id}/complete- Mark a custom quest as completed for a user/servers/{server_id}/custom-quests/{custom_quest_id}/completed-members- Get all members who completed a specific quest
Example Usage
Complete a Quest - Example
This example shows how to mark a quest as completed for a Discord user
1. Gather your information, you'll need the following:
API_KEY = "YOUR_API_KEY" # Found in your CommunityOne dashboard
SERVER_ID = 123456789012345678 # Your Discord server ID
USER_ID = 987654321098765432 # The Discord user ID who completed the quest
QUEST_ID = 42 # The quest ID shown in CommunityOne dashboard
2. Set up your request:
The endpoint for marking a quest as completed is "https://api.communityone.io/v1/servers/{SERVER_ID}/custom-quests/{QUEST_ID}/complete"
Get the correct endpoint url by replacing the placeholders with your actual values like this:
URL = https://api.communityone.io/v1/servers/123456789012345678/custom-quests/42/complete
HEADERS = {
"Authorization": API_KEY
}
BODY = {
"discord_user_id": USER_ID
}
3. Make the HTTP request:
Use your programming language's HTTP client to send a POST (or GET depending on the endpoint) request with the headers and body
4. Handle the response:
The response will contain information about the completion status, see the different endpoint responses below for more details.Endpoints in detail:
GET /v1/servers/{server_id}/custom-quests
Returns a list of all custom quests and their info
Header:
Authorization: YOUR_API_KEY
Example response:
Success (200)
[
{
"custom_quest_id": 123,
"title": "Sign up at MyApp.com!",
"description": "Sign up at my application",
"external_url": "https://myapp.com/signup",
"reward_points": 100,
"reward_role_id": "1273073873503522888",
"archived": false,
"testing_mode": false
}
]GET /v1/servers/{server_id}/custom-quests/{custom_quest_id}/completed-members
Returns a list of all members who have completed a given custom quest
Header:
Authorization: YOUR_API_KEY
Example response:
Success (200)
{
"custom_quest_id": 123,
"testing_mode": false,
"members": [
{
"discord_user_id": "1273073873503522888",
"last_completed": "2024-01-20T15:30:45Z",
"times_completed": 1
},
{
"discord_user_id": "184752978928861184",
"last_completed": "2024-01-20T15:30:45Z",
"times_completed": 3
}
]
}Not Found (404)
{"detail": "Quest not found"}GET /v1/servers/{server_id}/players/{discord_user_id}/info
Returns info about a given member
Header:
Authorization: YOUR_API_KEY
Example response:
Success (200)
{
"discord_user_id": "1273073873503522888",
"discord_username": "mrbeast123",
"discord_display_name": "Mr. Beast",
"discord_avatar": "https://cdn.discordapp.com/avatars/851179040428654623/933dbdb8a7273df4820ea4d891566f47.webp"
}Not Found (404)
{"detail": "Member not found"}POST /v1/servers/{server_id}/custom-quests/{custom_quest_id}/complete
Marks a custom quest as completed for a Discord member. If the quest is one-time-only the user will see their quest completed the next time they check /quests in discord, regardless of when this happens. If not, the user will only see their quest completed if they check /quests in discord in the same day.
Header:
Authorization: YOUR_API_KEY
Content-Type: application/json
Example request:
{"discord_user_id": "1273073873503522888"}Example responses:
Success (200) - First completion
{
"success": true,
"testing_mode": false,
"message": "Quest completion event recorded successfully.",
"completed_at": "2024-01-20T15:30:45Z"
}Success (200) - Already completed today
{
"success": true,
"testing_mode": false,
"message": "Quest already completed today (UTC)",
"completed_at": "2024-01-20T15:30:45Z"
}This second response will be returned if you attempt to complete a quest for a user that has already completed it earlier today (based on UTC time). The completed_at field will contain the timestamp of the original completion.
Possible messages:
"Quest completion event recorded successfully."
"Quest already completed today (UTC)"
Bad Request (400)
{"detail": "discord_user_id must be an integer"}Possible messages:
"discord_user_id must be an integer"
"Quest is no longer active"
"Quest is not active yet"
Not Found (404)
{"detail": "Quest not found"}Unauthorized (401)
{"detail": "Invalid API key"}Testing Mode
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
Rate Limiting
All API endpoints are subject to rate limiting:
60 requests per minute per server
Rate limits are applied separately for each endpoint
Exceeding the rate limit will result in a 429 Too Many Requests response
Join Discord for questions, comments, and a little gift 
or back to CommunityOne Home
Last updated