Quest actions API

Returns the question and its options for a video, banner or survey quest. The quest must have been started for this user.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl "https://api.adquest.batriders.ir/api/v1/platform/quests/23/question" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"

{
  "status": true,
  "code": "OK",
  "message": "Quest question",
  "data": {
    "id": 5,
    "title": "What did the video explain?",
    "input_type": "choice",
    "is_required": true,
    "options": [
      {
        "id": 11,
        "title": "How to start"
      },
      {
        "id": 12,
        "title": "How to pay"
      }
    ],
    "questions": []
  }
}

Records watch evidence for a timed quest. Send it while the participant is really watching.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl -X POST https://api.adquest.batriders.ir/api/v1/platform/quests/23/progress \
  -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", "watch_duration": 8 }'

{
  "status": true,
  "code": "OK",
  "message": "Quest progress recorded",
  "data": {
    "quest_id": 23,
    "elapsed_seconds": 8,
    "required_seconds": 15
  }
}

Adds a measured amount to a quest that completes when a progress target is reached.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl -X POST https://api.adquest.batriders.ir/api/v1/platform/quests/23/metrics \
  -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",
  "event_id": "evt_1001",
  "amount": 5,
  "occurred_at": "2026-01-01T12:00:00Z"
}'

Records that the participant followed the link of a visit quest and returns the destination. Visit quests only.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl "https://api.adquest.batriders.ir/api/v1/platform/quests/23/visit" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"

{
  "status": true,
  "code": "OK",
  "message": "Visit attributed",
  "data": {
    "quest_id": 23,
    "redirect_url": "https://example.com/offer",
    "clicked_at": "2026-01-01T12:00:00.000Z"
  }
}

Sends an event your app or server observed, such as a purchase, for event and custom quests.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl -X POST https://api.adquest.batriders.ir/api/v1/platform/quests/23/events \
  -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",
  "event_id": "evt_1001",
  "event_name": "purchase_completed"
}'

{
  "status": true,
  "code": "OK",
  "message": "Event accepted",
  "data": {
    "quest_id": 23,
    "event_id": "evt_1001",
    "event_name": "purchase_completed",
    "duplicate": false,
    "verified_at": "2026-01-01T12:00:00.000Z"
  }
}

Credits the inviter when a new user arrives with their referral code. Referral quests only.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl -X POST https://api.adquest.batriders.ir/api/v1/platform/quests/23/referrals \
  -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-77", "referral_code": "ADA123" }'

Answers the current question of the participant's attempt, in order and before its deadline. The last answer submits the attempt: it is accepted (202) and settled asynchronously; poll the completion status. Needs a reservation (the quest was started with reservations enabled). A request naming an earlier reservation_id is refused with 409 STALE_RESERVATION and changes nothing. A retry of the accepted final answer returns 202 (still processing) or the settled outcome, even after the attempt's deadline; it never creates a second submission.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl -X POST https://api.adquest.batriders.ir/api/v1/platform/quests/23/answer \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
  -d '{ "question_id": 5 }'

{
  "status": true,
  "code": "OK",
  "message": "Answer recorded",
  "data": {
    "state": "reserved",
    "correct": true,
    "answered_count": 1,
    "ask_order": [
      5,
      6
    ],
    "question_due_at": "2026-11-07T10:00:22+00:00"
  }
}

{
  "status": true,
  "code": "ACCEPTED",
  "message": "Answer accepted",
  "data": {
    "state": "processing",
    "reservation_id": "0f4f6c52-3c7d-4d6e-9d0f-6f9d3f1d2a11",
    "settlement_status": "pending",
    "quest_id": 23
  }
}

Returns where the participant stands on a profile, referral, streak or custom quest.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl "https://api.adquest.batriders.ir/api/v1/platform/quests/23/growth-status" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"

Submits the participant’s evidence. AdQuest checks it on the server and, when it is valid, settles the reward.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl -X POST https://api.adquest.batriders.ir/api/v1/platform/quests/23/complete \
  -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",
  "question_id": 5,
  "user_input": "11"
}'

{
  "status": true,
  "code": "OK",
  "message": "Quest completed successfully",
  "data": {
    "status": true,
    "quest_id": 23,
    "completed_at": "2026-01-01T12:00:00.000Z",
    "tokens_awarded": 10,
    "token_reward": 10
  }
}

Where the participant's attempt stands: reserved, processing, settled, rejected or expired, with the settlement status and the tokens awarded once settled.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl "https://api.adquest.batriders.ir/api/v1/platform/quests/23/completion" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"

{
  "status": true,
  "code": "OK",
  "message": "Completion status",
  "data": {
    "quest_id": 23,
    "state": "settled",
    "reservation_id": "0f4f6c52-3c7d-4d6e-9d0f-6f9d3f1d2a11",
    "settlement_status": "success",
    "tokens_awarded": 7,
    "reason": null,
    "expires_at": null,
    "completed_at": "2026-11-07T10:00:41+00:00"
  }
}

Returns engagement counts for one quest on your platform.

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

curl "https://api.adquest.batriders.ir/api/v1/platform/quests/23/stats" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"

{
  "status": true,
  "code": "OK",
  "message": "Quest stats",
  "data": {
    "id": 23,
    "name": "Watch our intro video",
    "seen_count": 120,
    "clicked_count": 40,
    "answered_count": 54,
    "engagement_rate": 45
  }
}

Where the participant's manual_review submission stands: pending, approved, rejected or expired. Approval completes the quest and settles the reward without a second request; an approved review that is still settling retries here. A rejected or expired review may be resubmitted through the complete endpoint while can_resubmit is true. Returns status none before any submission.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl "https://api.adquest.batriders.ir/api/v1/platform/quests/23/review" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"

{
  "status": true,
  "code": "OK",
  "message": "Custom review status",
  "data": {
    "id": 41,
    "status": "rejected",
    "attempt": 1,
    "evidence": "receipt-123",
    "approved_at": null,
    "rejected_at": "2026-11-08T09:12:00+00:00",
    "reject_reason": "Receipt is unreadable",
    "expires_at": "2026-11-22T09:00:00+00:00",
    "settled_at": null,
    "can_resubmit": true,
    "settlement_status": null
  }
}

State of the participant's multi-step execution: the definition version it is bound to, every step with its status (pending, in_review, verified, rejected) and availability, whether all required steps are verified, and the settlement status of the parent quest. Returns 409 NOT_STARTED before start. Disabled (404 MULTI_STEP_DISABLED) unless the multi-step feature flag is on.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl "https://api.adquest.batriders.ir/api/v1/platform/quests/23/execution" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"

{
  "status": true,
  "code": "OK",
  "message": "Execution state",
  "data": {
    "quest_id": 23,
    "execution_id": 7,
    "steps_version": 1,
    "ordering": "sequential",
    "state": "reserved",
    "steps": [
      {
        "step_key": "buy",
        "position": 1,
        "format": "custom",
        "required": true,
        "status": "verified",
        "attempts": 1,
        "available": true
      }
    ],
    "steps_complete": false,
    "settlement_status": "none",
    "unsettled_reason": null,
    "tokens_awarded": null
  }
}

Status of one step of the execution, including the latest manual review (never expected answers or callback URLs). When the owner or the platform's activity definition set a host deep link, config carries action_url (https or an app scheme) and an optional action_label; the SDK only navigates to it and the host app still proves the step.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl "https://api.adquest.batriders.ir/api/v1/platform/quests/23/steps/buy" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN"

{
  "status": true,
  "code": "OK",
  "message": "Execution state",
  "data": {
    "quest_id": 23,
    "execution_id": 7,
    "steps_version": 1,
    "ordering": "sequential",
    "state": "reserved",
    "steps": [
      {
        "step_key": "buy",
        "position": 1,
        "format": "custom",
        "required": true,
        "status": "verified",
        "attempts": 1,
        "available": true
      }
    ],
    "steps_complete": false,
    "settlement_status": "none",
    "unsettled_reason": null,
    "tokens_awarded": null
  }
}

Ask the server to verify a step. The server decides: a body of completed:true is ignored. action=start starts a timed (video/banner) step, action=click records a visit click, evidence/answers/evidence_type carry survey answers or manual-review proof. Server-attested events are sent to POST /events with step_key and a v2 signature (v2.eventId.eventName.questId.participantId.timestamp.stepKey.stepsVersion.executionId, HMAC-SHA256). When the last required step is verified the parent is admitted for settlement without another request; poll the execution or completion for the result.

Authentication: Public API key (X-AdQuest-Platform-Key) and participant token (X-AdQuest-Participant-Token). Both are required.

curl -X POST https://api.adquest.batriders.ir/api/v1/platform/quests/23/steps/buy/evidence \
  -H "Content-Type: application/json" \
  -H "X-AdQuest-Platform-Key: YOUR_PUBLIC_API_KEY" \
  -H "X-AdQuest-Participant-Token: PARTICIPANT_TOKEN" \
  -d '{  }'

{
  "status": true,
  "code": "OK",
  "message": "Execution state",
  "data": {
    "quest_id": 23,
    "execution_id": 7,
    "steps_version": 1,
    "ordering": "sequential",
    "state": "reserved",
    "steps": [
      {
        "step_key": "buy",
        "position": 1,
        "format": "custom",
        "required": true,
        "status": "verified",
        "attempts": 1,
        "available": true
      }
    ],
    "steps_complete": false,
    "settlement_status": "none",
    "unsettled_reason": null,
    "tokens_awarded": null
  }
}