# API Quests

> **Click** [**here**](https://discord.com/oauth2/authorize?client_id=1069423090225918082\&permissions=275146722545\&integration_type=0\&scope=applications.commands+bot\&redirect_uri=https%3A%2F%2Fcommunityone.io%2Fdashboard%2Fbot-auth-complete%2F%3Fsource%3Dgitbook\&response_type=code) **to introduce our bot to your server.**

### Getting started

You can find documentations on custom quests here: [https://api.communityone.io/v1/documentation#tag/Custom-Quests](https://api.communityone.io/v1/documentation#tag/Custom-Quests)

### 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](https://communityone.io/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





{% hint style="info" %}
Join [Discord](https://discord.gg/communityone) for questions, comments, and a little gift <img src="https://fonts.gstatic.com/s/e/notoemoji/latest/1f381/512.gif" alt="🎁" data-size="line"> or back to [CommunityOne Home](https://communityone.io/)
{% endhint %}

