Skip to documentation
AdQuestDocs

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.

Quest
{
  "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
}
FieldTypeMeaning
idintegerQuest ID. Use it in the other quest routes.
namestringQuest title.
typestringFormat key: video, banner, survey, quiz, visit, event, profile, referral, streak, custom or multi_step.
type_namestringDisplay name of the format.
visibilitystringWhether the quest is private to your platform or on the network.
token_rewardinteger or nullTokens this participant earns.
token_reward_totalinteger or nullTotal reward before the participant and AdQuest split it.
reward_unitobject or absentWhite Label publisher quests only: { code, label, icon_url } of the unit the reward is paid in. Absent means AdQuest tokens.
reward_is_maxboolean or absenttrue when token_reward is the most the quest can pay (video watched fully, every streak day).
gift_reward, gift_reward_expires_atobject or null, string or nullOptional gift attached to the quest, and when it expires.
statusstringactive, or in_progress for an auto-start quest this participant has not completed (the widget shows Continue).
auto_startbooleantrue 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.
screenstringThe widget screen that renders this quest.
content, cover, redirect_url, mediamixedQuest text or media URL, cover image, destination link and media details.
display_durationinteger or nullSeconds a banner must be shown. Banner quests only.
start_date, end_datestring or nullWhen the quest runs.
completedbooleanWhether this participant already completed it. Needs external_user_id.
completion_conditionobjectWhat the participant must do. Flags such as requires_timer and requires_question.
proofobjectThe evidence this format needs. Present only when the runtime supports the format.
availability, lock_reasonstring or absentPresent only when this participant cannot start the quest: availability is locked and lock_reason is ATTEMPTS_EXHAUSTED (every allowed attempt was used).

List quests

GET/platform/quests

Returns 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).

ParameterInTypeDescription
external_user_idquerystringYour ID for the user. Sets completed on each quest.
X-AdQuest-Participant-TokenheaderstringThe participant token. Optional here. It adds per-user state such as completed.
Request, cURL
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.

Response 200
{
  "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

GET/platform/quests/{questId}

Returns one quest.

Authentication: Public API key (X-AdQuest-Platform-Key).

ParameterInTypeDescription
questId requiredpathintegerQuest ID.
external_user_idquerystringYour ID for the user. Sets completed.
X-AdQuest-Participant-TokenheaderstringThe participant token. Optional here. It adds per-user state such as completed.
Request, cURL
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.

Response 200
{
  "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.

Response 404
{
  "status": false,
  "code": "QUEST_NOT_FOUND",
  "message": "Quest not found",
  "data": null
}

Start a quest

POST/platform/quests/{questId}/start

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

ParameterInTypeDescription
questId requiredpathintegerQuest ID.
X-AdQuest-Participant-Token requiredheaderstringThe 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 requiredbodystringYour ID for the user. Max 255 characters.
watch_durationbodyintegerSeconds, 1 to 600.
Request, cURL
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.

Response 200
{
  "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

POST/platform/quests/{questId}/click

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

ParameterInTypeDescription
questId requiredpathintegerQuest ID.
X-AdQuest-Participant-Token requiredheaderstringThe 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 requiredbodystringYour ID for the user. Max 255 characters.
Request, cURL
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.

Response 200
{
  "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.

POST/platform/quests/{questId}/view

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

ParameterInTypeDescription
questId requiredpathintegerQuest ID.
X-AdQuest-Participant-Token requiredheaderstringThe 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 requiredbodystringYour ID for the user. Max 255 characters.
Request, cURL
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.

Response 200
{
  "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.

Response 422
{
  "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.

Something unclear, missing or wrong here? Tell us