🆕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:

1. Go to your server's CommunityOne dashboard

2. Navigate to Hype Engine > Custom Quests

3. Click the Edit button on your quest

4. 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