Quests API
List quests, read one, start it and record views and clicks.
On this page
The quest object
Every quest route that returns a quest uses the same object. Format-specific fields (event_rule, profile_rule, referral_rule, streak_rule, custom_rule) are filled only for that format.
{
"id": 23,
"name": "Watch our intro video",
"type": "video",
"type_name": "Video",
"visibility": "private",
"platform_id": 7,
"token_reward": 10,
"token_reward_total": 12,
"gift_reward": null,
"gift_reward_expires_at": null,
"status": "active",
"auto_start": false,
"screen": "watch",
"content": "https://cdn.example.com/intro.mp4",
"cover": "https://cdn.example.com/cover.jpg",
"redirect_url": null,
"display_duration": null,
"start_date": "2026-01-01",
"end_date": "2026-03-01",
"completed": false,
"completion_condition": {
"requires_timer": true,
"requires_question": true,
"requires_click": false,
"requires_event": false,
"requires_profile": false,
"requires_referral": false,
"requires_streak": false,
"requires_custom": false,
"answer_mode": null
},
"event_rule": null,
"profile_rule": null,
"referral_rule": null,
"streak_rule": null,
"custom_rule": null,
"media": {
"type": "video",
"url": "https://cdn.example.com/intro.mp4",
"cover": "https://cdn.example.com/cover.jpg"
},
"proof": {
"type": "watch_answer",
"version": 1,
"media": "video",
"timed": true
},
"reward_unit": null,
"reward_is_max": true
}| Field | Type | Meaning |
|---|---|---|
| id | integer | Quest ID. Use it in the other quest routes. |
| name | string | Quest title. |
| type | string | Format key: video, banner, survey, quiz, visit, event, profile, referral, streak, custom or multi_step. |
| type_name | string | Display name of the format. |
| visibility | string | Whether the quest is private to your platform or on the network. |
| token_reward | integer or null | Tokens this participant earns. |
| token_reward_total | integer or null | Total reward before the participant and AdQuest split it. |
| reward_unit | object or absent | White Label publisher quests only: { code, label, icon_url } of the unit the reward is paid in. Absent means AdQuest tokens. |
| reward_is_max | boolean or absent | true when token_reward is the most the quest can pay (video watched fully, every streak day). |
| gift_reward, gift_reward_expires_at | object or null, string or null | Optional gift attached to the quest, and when it expires. |
| status | string | active, or in_progress for an auto-start quest this participant has not completed (the widget shows Continue). |
| auto_start | boolean | true when the quest starts on its own: Custom, Referral and Multi-step quests are started by the participant session, Reach a target quests count from launch. |
| screen | string | The widget screen that renders this quest. |
| content, cover, redirect_url, media | mixed | Quest text or media URL, cover image, destination link and media details. |
| display_duration | integer or null | Seconds a banner must be shown. Banner quests only. |
| start_date, end_date | string or null | When the quest runs. |
| completed | boolean | Whether this participant already completed it. Needs external_user_id. |
| completion_condition | object | What the participant must do. Flags such as requires_timer and requires_question. |
| proof | object | The evidence this format needs. Present only when the runtime supports the format. |
| availability, lock_reason | string or absent | Present only when this participant cannot start the quest: availability is locked and lock_reason is ATTEMPTS_EXHAUSTED (every allowed attempt was used). |
List quests
/platform/questsReturns the quests this platform can show, newest first. Pass external_user_id to mark the ones the user has already completed.
Authentication: Public API key (X-AdQuest-Platform-Key).
| Parameter | In | Type | Description |
|---|---|---|---|
external_user_id | query | string | Your ID for the user. Sets completed on each quest. |
X-AdQuest-Participant-Token | header | string | The participant token. Optional here. It adds per-user state such as completed. |
curl "https://api.adquest.io/api/v1/platform/quests" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 The list of quests. effective_locale is the language the quests were chosen for.
{
"status": true,
"code": "OK",
"message": "Platform quests",
"effective_locale": "en",
"data": [
{
"id": 23,
"name": "Watch our intro video",
"type": "video",
"type_name": "Video",
"visibility": "private",
"platform_id": 7,
"token_reward": 10,
"token_reward_total": 12,
"gift_reward": null,
"gift_reward_expires_at": null,
"status": "active",
"auto_start": false,
"screen": "watch",
"content": "https://cdn.example.com/intro.mp4",
"cover": "https://cdn.example.com/cover.jpg",
"redirect_url": null,
"display_duration": null,
"start_date": "2026-01-01",
"end_date": "2026-03-01",
"completed": false,
"completion_condition": {
"requires_timer": true,
"requires_question": true,
"requires_click": false,
"requires_event": false,
"requires_profile": false,
"requires_referral": false,
"requires_streak": false,
"requires_custom": false,
"answer_mode": null
},
"event_rule": null,
"profile_rule": null,
"referral_rule": null,
"streak_rule": null,
"custom_rule": null,
"media": {
"type": "video",
"url": "https://cdn.example.com/intro.mp4",
"cover": "https://cdn.example.com/cover.jpg"
},
"proof": {
"type": "watch_answer",
"version": 1,
"media": "video",
"timed": true
}
}
]
}Get a quest
/platform/quests/{questId}Returns one quest.
Authentication: Public API key (X-AdQuest-Platform-Key).
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
external_user_id | query | string | Your ID for the user. Sets completed. |
X-AdQuest-Participant-Token | header | string | The participant token. Optional here. It adds per-user state such as completed. |
curl "https://api.adquest.io/api/v1/platform/quests/23" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"200 The quest.
{
"status": true,
"code": "OK",
"message": "Quest details",
"data": {
"id": 23,
"name": "Watch our intro video",
"type": "video",
"type_name": "Video",
"visibility": "private",
"platform_id": 7,
"token_reward": 10,
"token_reward_total": 12,
"gift_reward": null,
"gift_reward_expires_at": null,
"status": "active",
"auto_start": false,
"screen": "watch",
"content": "https://cdn.example.com/intro.mp4",
"cover": "https://cdn.example.com/cover.jpg",
"redirect_url": null,
"display_duration": null,
"start_date": "2026-01-01",
"end_date": "2026-03-01",
"completed": false,
"completion_condition": {
"requires_timer": true,
"requires_question": true,
"requires_click": false,
"requires_event": false,
"requires_profile": false,
"requires_referral": false,
"requires_streak": false,
"requires_custom": false,
"answer_mode": null
},
"event_rule": null,
"profile_rule": null,
"referral_rule": null,
"streak_rule": null,
"custom_rule": null,
"media": {
"type": "video",
"url": "https://cdn.example.com/intro.mp4",
"cover": "https://cdn.example.com/cover.jpg"
},
"proof": {
"type": "watch_answer",
"version": 1,
"media": "video",
"timed": true
},
"reward_unit": null,
"reward_is_max": true
}
}404 The quest does not exist or is not available to this platform.
{
"status": false,
"code": "QUEST_NOT_FOUND",
"message": "Quest not found",
"data": null
}Start a quest
/platform/quests/{questId}/startStarts a quest for a participant. For timed quests (video and banner) the response tells you how long the participant has to watch. Video, banner, survey, quiz, visit and multi-step quests hold an attempt: the response carries reservation_id, attempt, attempts_left (null when unlimited), expires_at and timing. Video and banner quests can be started again after a failed attempt; every other format allows one attempt unless AdQuest changes the limit.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
external_user_id required | body | string | Your ID for the user. Max 255 characters. |
watch_duration | body | integer | Seconds, 1 to 600. |
curl -X POST https://api.adquest.io/api/v1/platform/quests/23/start \
-H "Content-Type: application/json" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
-d '{ "external_user_id": "player-42" }'200 The quest was started, or the participant's open attempt was resumed. display_duration and expires_in (seconds) are included for video and banner quests only. attempts_left is 0 when a failed attempt cannot be started again. For a format that holds no attempt (event, profile, referral, streak, custom), an already completed quest also returns this status with status false and data.completed true. Do not grant a reward.
{
"status": true,
"code": "OK",
"message": "Quest started",
"data": {
"quest_id": 23,
"display_duration": 15,
"expires_in": 15
}
}404 QUEST_NOT_FOUND. The quest does not exist, is not available, or needs a capability your client did not declare (quiz, multi_step).
409 The attempt cannot start. data.code says why: QUEST_ALREADY_COMPLETED (data.completed is true; do not grant a reward), QUEST_PROCESSING (a submission is being paid), ATTEMPTS_EXHAUSTED (no attempts left), RESTART_TOO_SOON or QUEST_BUSY (retry after data.retry_after seconds; QUEST_BUSY can also come as 429), QUEST_BUDGET_EXHAUSTED, QUEST_CAPACITY_EXHAUSTED or QUEST_FUNDS_EXHAUSTED. PROFILE_ALREADY_COMPLETE for a profile quest.
422 A field failed validation. For a format that holds no attempt, an exhausted budget is also 422 with data.code QUEST_BUDGET_EXHAUSTED.
429 QUEST_BUSY from the start gate: too many starts at once. Retryable, like the 409 QUEST_BUSY: retry after data.retry_after seconds.
Record a click
/platform/quests/{questId}/clickRecords that the participant clicked the quest’s media. Send it only when a real click happens.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
external_user_id required | body | string | Your ID for the user. Max 255 characters. |
curl -X POST https://api.adquest.io/api/v1/platform/quests/23/click \
-H "Content-Type: application/json" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
-d '{ "external_user_id": "player-42" }'200 The click was recorded. Also returned with this status: the participant already completed this quest. status is false and data.completed is true.
{
"status": true,
"code": "OK",
"message": "Quest click recorded",
"data": {
"quest_id": 23,
"clicked_at": "2026-01-01T12:00:00.000Z"
}
}404 QUEST_NOT_FOUND.
Record that a participant saw a quest. First viewed_at sticks.
/platform/quests/{questId}/viewRecords that the participant saw the quest. The first view is kept. Later calls keep the same viewed_at.
Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.
| Parameter | In | Type | Description |
|---|---|---|---|
questId required | path | integer | Quest ID. |
X-AdQuest-Participant-Token required | header | string | The participant token minted by your backend (POST /platform/participant-sessions). Required: it is the participant's identity. A body external_user_id is optional and must match it (403 PARTICIPANT_MISMATCH); a missing or invalid token is 401 PARTICIPANT_AUTH_REQUIRED. |
external_user_id required | body | string | Your ID for the user. Max 255 characters. |
curl -X POST https://api.adquest.io/api/v1/platform/quests/23/view \
-H "Content-Type: application/json" \
-H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
-H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
-d '{ "external_user_id": "player-42" }'200 The view was recorded.
{
"status": true,
"code": "OK",
"message": "Quest view recorded",
"data": {
"quest_id": 23
}
}404 QUEST_NOT_FOUND.
422 A field failed validation, for example a missing external_user_id.
{
"status": false,
"code": "VALIDATION_ERROR",
"message": "The external user id field is required.",
"data": {
"external_user_id": [
"The external user id field is required."
]
}
}Evidence and completion
Questions, progress, visits, growth status, completion and stats are on the Quest actions page.