> For the complete documentation index, see [llms.txt](https://docs.kibotu.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kibotu.ai/documentation/api-reference/quests.md).

# Quests

## Get All Quests

Query for all the quests that are currently active in game.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/eligible`

**`Request Body` - Empty**

**`Response Body`**

```
{ 
    list: [
        {
            occasionId: ObjectId,
            game: ObjectId,
            enabled: true,
            name: String,
            targetFilter: {},
            from: Date,
            to: Date,
            countryCodesArray: [String],
            collectibleIconImage: String (URL),            
            milestones: [
                {
                    order: Number,
                    prizeTitle: String,
                    prizeImage: String (URL),
                    prizeSku: String,
                    goal: Number,
                    goalImage: String (URL),
                }
            ],
            triggers: {
                // First processing `state`
                state: {
                    // event triggers quest activation (from a list)
                    welcome: [{
                        eventName: String,
                        eventValue: Number,
                    }],
                    // event triggers progress steps (item collected, step++)
                    progress: [{
                        eventName: String,
                        eventValue: Number,
                    }],
                    // event triggers progress finalization (could be the same as progress, but could be different, like finishing a world)
                    finish: [{
                        eventName: String,
                        eventValue: Number,
                    }]
                },
                // Then processing `ui`
                ui: {
                    // event triggers showing a modal for welcome state
                    welcome: [{
                        eventName: String,
                        eventValue: Number,
                    }],
                    // event triggers showing a modal for progress state
                    progress: [{
                        eventName: String,
                        eventValue: Number,
                    }],
                    // event triggers showing a modal for finish state
                    finish: [{
                        eventName: String,
                        eventValue: Number,
                    }]
                }
            },
            graphics: {
                welcome: {
                    background: String (URL),
                    titleImage: String (URL),
        
                    base: String (URL),
                    preview: String (URL),
                },
                progress: {
                    background: String (URL),
                    titleImage: String (URL),
        
                    base: String (URL),
                    preview: String (URL),
                },
                finish: {
                    background: String (URL),
                    titleImage: String (URL),
        
                    base: String (URL),
                    preview: String (URL),
                },
            }
        }
    ] 
}
```

## Start Quest

Start the quest participation for the current player.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/start`

**`Request parameters`**

* questId - The \_id of a quest is returned in the list of quests from the [Get All Quests](#get-all-quests) endpoint.

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body` - Empty on Success (http 200)**

## Get Player's Active Quest

Gets the quest that the current player is currently participating in.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/active`

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body` - Identical to the Quest object listed in the** [**Get All Quests** ](#get-all-quests)**response, with an additional property**

```
{
    progress: Number
}
```

## Add Progress in Quest

Tracks the current player's progress in a specific quest.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/trigger`

**`Request parameters`**

* questId - The \_id of a quest is returned from the [Get Player's Active Quest](#get-players-active-quest) endpoint.

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body` - on Success (http 200)**

```
{
    newValue: Number
}
```

## Finish Quest

Calculates whether the current player has won or lost this quest.

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/finish`

**`Request parameters`**

* questId - The \_id of a quest is returned from the [Get Player's Active Quest](#get-players-active-quest) endpoint.

**`Request Body`**

<pre><code><strong>{
</strong>    playerId: String
}
</code></pre>

**`Response Body` - Returns the latest milestone the player has achieved in this quest.**

```
{
    order: Number,
    prizeTitle: String,
    prizeImage: String (URL),
    prizeSku: String,
    goal: Number,
    goalImage: String (URL),
}
```

## Dismiss Quest

Removes the quest from the current player's [Active Quests](#get-players-active-quest) list (at the moment list is limited to 1).

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/finalize`

**`Request parameters`**

* questId - The \_id of a quest is returned from the [Get Player's Active Quest](#get-players-active-quest) endpoint.

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body`  - Empty on Success (http 200)**

## Verify Quest Prize

You will find this useful for server to server integration, when you want to verify the eligible prize of a finished quest (before committing the transaction of giving the prize)

<mark style="color:green;">`POST`</mark> `https://api.kibotu.ai/quests/:questId/verify-prize`

**`Request parameters`**

* questId - The \_id of a quest is returned from the [Get Player's Active Quest](#get-players-active-quest) endpoint.

**`Request Body`**

```
{
    playerId: String
}
```

**`Response Body`  - Returns the eligible prize for the player (http 200)**

```
{
    prizeSku: String
}
```