{"openapi":"3.1.0","info":{"title":"AdQuest partner API","version":"1.0.0","description":"The routes your app and backend call. Guides: https://dashboard.adquest.io/docs"},"servers":[{"url":"https://api.adquest.io/api/v1"}],"paths":{"/server/activities":{"post":{"tags":["Server"],"operationId":"ingestServerActivities","summary":"Report activities","description":"Reports facts from your server once, as they happen: trades, deposits, KYC, signups. Do not name quests: AdQuest works out which quests each fact completes and settles them. Up to 500 items and 512 KB per request. Send your Secret Key as X-AdQuest-Platform-Secret; signing with X-AdQuest-Signature is an optional alternative. Served by the serving plane, and only once activities are enabled for the environment (otherwise the route does not exist). Each item is answered on its own, so retry only the items whose result is retryable.","security":[{"PlatformKey":[],"PlatformSecret":[]},{"PlatformKey":[],"ServerSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["activities"],"properties":{"activities":{"description":"The facts, at most 500.","example":[{"id":"trd_9f31","type":"trade.completed","user":"user_123","occurred_at":1763459990,"entity_id":"BTC-IRR"}],"type":"array","maxItems":500,"items":{"type":"object","required":["id","type","user","occurred_at"],"properties":{"id":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9_.:-]{1,128}$","description":"Your unique id for this fact: letters, digits, _ . : and - only. Sending it again is a no-op; the same id with a different body is ID_REUSED.","example":"trd_9f31"},"type":{"type":"string","description":"A registered activity type (dashboard: your platform > Activities).","example":"trade.completed"},"user":{"type":"string","maxLength":255,"description":"Your user id (external_user_id). No participant token is needed.","example":"user_1234"},"occurred_at":{"type":"integer","description":"Unix seconds when it happened on your side (for a state: when the user reached it). At most 60 s in the future; an event at most 7 days old.","example":1763459990},"amount_minor":{"type":"string","description":"Integer minor units, when the activity has an amount.","example":"2000000"},"currency":{"type":"string","description":"ISO 4217, when the activity has an amount.","example":"IRR"},"entity_id":{"type":"string","maxLength":128,"description":"What the fact is about (market, product), when the activity has one.","example":"BTC-IRR"},"reverses":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$","description":"The id of the fact this one reverses, for a reversal activity (a refund)."},"referral_code":{"type":"string","pattern":"^[A-Za-z0-9]{1,32}$","description":"For a signup: the inviter's code (from ?adquest_ref=). Letters and digits, up to 32."},"state":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$","description":"For a state activity: the value reached, such as verified. Letters, digits, _ . and -, up to 64."}}}}}}}}},"responses":{"200":{"description":"data.results has one entry per item, in order: status accepted, duplicate or rejected (with code and retryable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Activities received","data":{"results":[{"id":"trd_9f31","status":"accepted"},{"id":"trd_9f30","status":"duplicate"},{"id":"x_1","status":"rejected","code":"UNKNOWN_ACTIVITY_TYPE"}]}}}}},"401":{"description":"SERVER_AUTH_REQUIRED (wrong public key or Secret Key), or SIGNATURE_INVALID / SIGNATURE_EXPIRED when you sign instead (more than 5 minutes off)."},"403":{"description":"ACTIVITIES_NOT_CONFIGURED: no activity is registered for your platform yet."},"413":{"description":"BATCH_TOO_LARGE: more than 500 items or 512 KB."},"422":{"description":"INVALID_BODY: the body is not {\"activities\": [...]} with at least one item."},"503":{"description":"ACTIVITY_CONFIG_UNAVAILABLE: retryable, nothing was stored. Resend the batch shortly."}},"x-served-by":"serving","x-docs":{"page":"api/server-routes","id":"report-activities","order":2}}},"/server/fulfillments/{id}/acknowledge":{"parameters":[{"name":"id","in":"path","required":true,"description":"Fulfillment ID from the fulfillment.requested webhook.","schema":{"type":"integer"},"example":12}],"post":{"tags":["Server"],"operationId":"acknowledgeServerFulfillment","summary":"Acknowledge a fulfillment","description":"You delivered the reward of a fulfillment.requested webhook. Final: it can no longer be rejected. Repeating the same external_reference is safe. On a referral quest the webhook payload carries referral_role (inviter | invitee): one fulfillment per rewarded side, and with pay_each_invite one per invite for the inviter (with referral_payout_id and unit_no). The payload amount is a whole number for AdQuest tokens and the exact decimal string (\"0.25\") for a reward in your own unit. If the activity that earned an unpaid reward is reversed (an activity with `reverses`), AdQuest cancels it and sends fulfillment.canceled (fulfillment_id, reason_code activity_reversed, amount, asset, quest_id, external_user_id, referral_role) to every webhook that receives fulfillment.requested; acknowledging or rejecting it then answers 409 FULFILLMENT_CONFLICT. An acknowledged reward is never canceled.","security":[{"PlatformKey":[],"PlatformSecret":[]},{"PlatformKey":[],"ServerSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["external_reference"],"properties":{"external_reference":{"type":"string","maxLength":190,"description":"Your own reference for the delivered reward.","example":"order-8841"}}}}}},"responses":{"200":{"description":"data has id, status, external_reference and rejection_reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Fulfillment acknowledged","data":{"id":12,"status":"acknowledged","external_reference":"order-8841","rejection_reason":null}}}}},"401":{"description":"SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret."},"404":{"description":"FULFILLMENT_NOT_FOUND."},"409":{"description":"FULFILLMENT_CONFLICT: already rejected, or acknowledged with another reference."}},"x-docs":{"page":"api/server-routes","id":"server-acknowledge-fulfillment","order":3}}},"/server/fulfillments/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Fulfillment ID from the fulfillment.requested webhook.","schema":{"type":"integer"},"example":12}],"post":{"tags":["Server"],"operationId":"rejectServerFulfillment","summary":"Reject a fulfillment","description":"You refused the reward after your own review. Final: it cannot be acknowledged afterwards, and an acknowledged one cannot be rejected. The participant's history shows it as rejected. Nothing returns to the quest's budget: a reward you fulfil moved no AdQuest money. A fulfillment.rejected webhook echoes it. Repeating the same reason_code is safe. A canceled fulfillment answers 409 FULFILLMENT_CONFLICT.","security":[{"PlatformKey":[],"PlatformSecret":[]},{"PlatformKey":[],"ServerSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason_code"],"properties":{"reason_code":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_]+$","description":"Your reason, lowercase letters, digits and _.","example":"kyc_failed"}}}}}},"responses":{"200":{"description":"data has id, status (rejected) and rejection_reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Fulfillment rejected","data":{"id":12,"status":"rejected","external_reference":null,"rejection_reason":"kyc_failed"}}}}},"401":{"description":"SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret."},"404":{"description":"FULFILLMENT_NOT_FOUND."},"409":{"description":"FULFILLMENT_CONFLICT: already acknowledged, or rejected with another reason."}},"x-docs":{"page":"api/server-routes","id":"server-reject-fulfillment","order":4}}},"/server/fulfillments":{"get":{"tags":["Server"],"operationId":"listServerFulfillments","summary":"List fulfillments","description":"Your platform's fulfillments, newest first. amount is a whole number for AdQuest tokens and lottery prizes, and the exact decimal string (\"0.5\") for a reward in your own unit (USDT, TOMAN...), the same as in the webhook.","security":[{"PlatformKey":[],"PlatformSecret":[]},{"PlatformKey":[],"ServerSignature":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"pending, delivered, acknowledged, rejected, failed or terminal_failed.","schema":{"type":"string"}},{"name":"created_from","description":"Only fulfillments created at or after this time.","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_to","description":"Only fulfillments created before this time.","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"after","in":"query","required":false,"description":"The `next` value of the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 200. Default 50.","schema":{"type":"integer"}}],"responses":{"200":{"description":"data.data has id, kind, status, amount, asset, quest_id, external_user_id, external_reference, rejection_reason and the timestamps; data.next is the next page cursor or null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"OK","data":{"data":[{"id":12,"kind":"quest_reward","status":"delivered","amount":100,"asset":"TRX","quest_id":42,"external_user_id":"user_123","external_reference":null,"rejection_reason":null,"created_at":"2026-11-18T10:00:00+00:00","acknowledged_at":null,"rejected_at":null}],"next":null}}}}},"401":{"description":"SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret."}},"x-docs":{"page":"api/server-routes","id":"server-list-fulfillments","order":5}}},"/server/referral-codes":{"post":{"tags":["Server"],"operationId":"registerServerReferralCodes","summary":"Register your referral codes","description":"Your own referral codes, for referral Quests whose code source is the platform. Each participant holds one code; a code is unique on your platform and moves to the participant it is sent for last. Users AdQuest has not seen are created. Send codes of users who never opened the widget here; participant-sessions also takes referral_code. Register a code before a signup reports it.","security":[{"PlatformKey":[],"PlatformSecret":[]},{"PlatformKey":[],"ServerSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["codes"],"properties":{"codes":{"type":"array","minItems":1,"maxItems":500,"description":"Up to 500 pairs of your user id and that user's code.","example":[{"user":"55120","code":"ALI2024"}],"items":{"type":"object","required":["user","code"],"properties":{"user":{"type":"string","maxLength":255,"description":"Your user id (external_user_id).","example":"55120"},"code":{"type":"string","pattern":"^[A-Za-z0-9]{1,32}$","description":"1-32 letters or digits, stored upper-case.","example":"ALI2024"}}}}}},"example":{"codes":[{"user":"55120","code":"ALI2024"},{"user":"55121","code":"SARA77"}]}}}},"responses":{"200":{"description":"data.results answers each item in order: assigned (with referral_code), or rejected with code INVALID_USER, INVALID_REFERRAL_CODE or DUPLICATE_IN_BATCH (a user or code twice in one request; neither is applied).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Referral codes received","data":{"results":[{"user":"55120","status":"assigned","referral_code":"ALI2024"},{"user":"55121","status":"rejected","code":"INVALID_REFERRAL_CODE"}]}}}}},"401":{"description":"SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED."},"422":{"description":"VALIDATION_ERROR: codes is not a list of 1-500 items."}},"x-docs":{"page":"api/server-routes","id":"server-referral-codes","order":9}}},"/server/quests":{"get":{"tags":["Server"],"operationId":"listServerQuests","summary":"List quests","description":"Your platform's quests with status, dates, budget and the activity rules each one counts. Referral quests also carry `referral` (reward_target inviter|invitee|both, pay_each_invite, min_attributions, code_source, activity_type, qualify_activity_type (null when the signup alone counts), and inviter_amount / invitee_amount: what one unit pays each side, as decimals; each side's fulfillment carries its own amount); null on other types. `reward` is what one unit pays (one completion, or one invite on a per-invite referral): amount, unit, caps and whether the platform pays it (paid_by_platform).","security":[{"PlatformKey":[],"PlatformSecret":[]},{"PlatformKey":[],"ServerSignature":[]}],"parameters":[{"name":"updated_since","description":"Only quests changed at or after this time.","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"after","in":"query","required":false,"description":"The `next` value of the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 200. Default 50.","schema":{"type":"integer"}}],"responses":{"200":{"description":"data.data has id, title, type, status, starts_at, ends_at, token_reward, token_reward_total, reward_is_max, reward_unit, asset, budget, settled_completions, activity_rules and updated_at; data.next is the next page cursor or null. type is the stored type name, which is the format key except for surveys (market_research). token_reward is what the participant receives and token_reward_total the gross, both for the whole quest (for per-unit rewards the full amount; reward_is_max marks an up-to amount). reward_unit is your own unit ({code, label, icon_url}) or null for AdQuest tokens; asset is the value fulfillment.requested carries for this quest (the unit code, or ADQ_TOKEN).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"OK","data":{"data":[{"id":42,"title":"Make 3 trades","type":"event","status":"active","starts_at":"2026-11-18T00:00:00+00:00","ends_at":"2026-11-30T23:59:59+00:00","token_reward":10,"token_reward_total":10,"reward_is_max":false,"reward_unit":{"code":"DKC","label":"Coins","icon_url":null},"asset":"DKC","budget":"1000000.00","settled_completions":17,"activity_rules":[{"format":"event","activity_type":"trade.completed","metric":"count","operator":"gte","target":3,"enrollment":"auto","live_from":1763424000,"live_until":1764547199}],"reward":{"amount":"10","unit":"USDT","unit_label":"Tether","metric":"completion","max_units":null,"max_amount":null,"paid_by_platform":true},"referral":null,"updated_at":"2026-11-18T09:00:00+00:00"}],"next":null}}}}},"401":{"description":"SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret."}},"x-docs":{"page":"api/server-routes","id":"server-list-quests","order":6}}},"/server/reconciliation":{"get":{"tags":["Server"],"operationId":"serverReconciliation","summary":"Reconciliation","description":"Per UTC day and asset: how many rewards were requested and how many (and how much) are in each state. At most 93 days. Amounts of your own units are exact decimal strings; AdQuest tokens are whole numbers.","security":[{"PlatformKey":[],"PlatformSecret":[]},{"PlatformKey":[],"ServerSignature":[]}],"parameters":[{"name":"from","description":"First UTC day, inclusive.","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-11-01"},{"name":"to","in":"query","required":true,"description":"Exclusive.","schema":{"type":"string","format":"date"},"example":"2026-11-08"}],"responses":{"200":{"description":"data.days has one entry per day and asset with requested and per-status count and amount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Reconciliation","data":{"from":"2026-11-17","to":"2026-11-18","days":[{"day":"2026-11-17","asset":"TRX","requested":{"count":3,"amount":300},"acknowledged":{"count":2,"amount":200},"rejected":{"count":1,"amount":100}}]}}}}},"401":{"description":"SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret."},"422":{"description":"RANGE_TOO_LONG or invalid dates."}},"x-docs":{"page":"api/server-routes","id":"server-reconciliation","order":7}}},"/server/activities/{activityId}":{"parameters":[{"name":"activityId","in":"path","required":true,"description":"Your id of the fact.","schema":{"type":"string"},"example":"trd_9f31"}],"get":{"tags":["Server"],"operationId":"showServerActivity","summary":"Show an activity","description":"What AdQuest stored for one fact you reported, for support and debugging.","security":[{"PlatformKey":[],"PlatformSecret":[]},{"PlatformKey":[],"ServerSignature":[]}],"responses":{"200":{"description":"data has id, type, user, occurred_at, received_at, amount_minor, currency, entity_id, referral_code, state, reverses and reversed_at.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Activity","data":{"id":"trd_9f31","type":"trade.completed","user":"user_123","occurred_at":"2026-11-18T09:59:50+00:00","received_at":"2026-11-18T09:59:51+00:00","amount_minor":null,"currency":null,"entity_id":"BTC-IRR","referral_code":null,"state":null,"reverses":null,"reversed_at":null}}}}},"401":{"description":"SERVER_AUTH_REQUIRED, SIGNATURE_INVALID or SIGNATURE_EXPIRED. Sign the request with your event signing secret, or send the platform secret."},"404":{"description":"ACTIVITY_NOT_FOUND."}},"x-docs":{"page":"api/server-routes","id":"server-show-activity","order":8}}},"/platform/participant-sessions":{"post":{"tags":["Platform delivery"],"operationId":"createParticipantSession","summary":"Create a participant session using the host-selected SDK language","description":"Creates a short-lived participant token for one user of your platform. Call this from your backend only, after you have verified who the user is. It also starts the platform's live auto-start custom quests for this user, once, after the session is saved; that never delays or fails the response.","security":[{"PlatformSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_user_id":{"type":"string","maxLength":255,"description":"Your own stable ID for the user. Max 255 characters.","example":"player-42"},"display_name":{"type":"string","maxLength":255,"description":"Name shown to the participant. Max 255 characters.","example":"Ada"},"username":{"type":"string","maxLength":255,"description":"Max 255 characters. Used by profile quests."},"email":{"type":"string","maxLength":255,"description":"Max 255 characters. Used by profile quests and for the winner email."},"phone":{"type":"string","maxLength":32,"description":"Max 32 characters. Used by profile quests."},"avatar_url":{"type":"string","maxLength":2048,"description":"Max 2048 characters."},"locale":{"type":"string","description":"Language of the widget: en or fa, region tags such as en-US accepted. Invalid values fall back to English and are never rejected.","example":"en-US"},"country_code":{"type":"string","description":"Participant’s reward country as an ISO 3166-1 alpha-2 code, such as IR. Null or empty clears it. An unassigned code returns 422.","example":"IR"},"timezone":{"type":"string","maxLength":64,"description":"IANA timezone. Max 64 characters."},"host_context":{"type":"object","description":"Version 1 host profile context. Max 8192 encoded bytes."},"location":{"type":"object","description":"Location permission context, such as {\"status\":\"granted\",\"latitude\":35.6892,\"longitude\":51.389}."},"push":{"type":"object","description":"Push permission context, such as {\"status\":\"granted\",\"token\":\"push-token\"}."},"capabilities":{"type":"object","description":"Permission map. Each of profile, location, push and custom is granted, denied or unavailable."},"referral_code":{"type":"string","pattern":"^[A-Za-z0-9]{1,32}$","description":"This participant's own referral code on your platform, for referral Quests whose code source is the platform. Stored upper-case; moves from any other participant. Omitted or empty keeps the stored code.","example":"ALI2024"}},"required":["external_user_id"]}}}},"responses":{"200":{"description":"The session was created. Return participant_token and its expiry to that user’s frontend. The token lasts 15 minutes.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ParticipantSession"}}}]},"example":{"status":true,"code":"OK","message":"Participant session created","data":{"participant_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.EXAMPLE.SIGNATURE","expires_at":"2026-10-24T12:49:08+00:00","expires_in":900,"platform_user":{"id":1,"external_user_id":"player-42","display_name":"Ada","avatar_url":null,"country_code":null,"country_name":null,"eligibility_country_code":"IR","eligibility_country_source":"platform"},"eligibility":{"locale":"en","timezone":null,"location_permission":"unavailable","push_permission":"unavailable","profile_permission":"unavailable","has_display_name":true,"has_avatar":false,"has_username":false,"has_locale":true,"has_timezone":false,"has_email":false,"has_phone":false,"completeness_percent":28},"locale_resolution":{"requested":"en","effective":"en","source":"host"}}}}}},"401":{"description":"The Secret Key is missing or wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"status":false,"code":"PARTICIPANT_AUTH_REQUIRED","message":"Platform secret is required","data":{"code":"PARTICIPANT_AUTH_REQUIRED"}}}}},"422":{"description":"A field failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"status":false,"code":"VALIDATION_ERROR","message":"country_code must be an assigned ISO 3166-1 alpha-2 code","data":null}}}},"429":{"description":"Too many session requests. Back off and retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"},"example":{"status":false,"message":"Too many session requests","data":{"code":"RATE_LIMITED"}}}}}},"x-docs":{"page":"api/participant-sessions","id":"create-participant-session","order":0},"x-example-verified":true}},"/platform/quests":{"get":{"tags":["Platform delivery"],"operationId":"listPlatformQuests","summary":"List quests","description":"Returns the quests this platform can show, newest first. Pass external_user_id to mark the ones the user has already completed.","security":[{"PlatformKey":[]}],"parameters":[{"name":"external_user_id","in":"query","required":false,"description":"Your ID for the user. Sets completed on each quest.","schema":{"type":"string"}},{"name":"X-AdQuest-Participant-Token","in":"header","required":false,"description":"The participant token. Optional here. It adds per-user state such as completed.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"The list of quests. effective_locale is the language the quests were chosen for.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"effective_locale":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Quest"}}}}]},"example":{"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}}]}}}}},"x-docs":{"page":"api/quests","id":"list-quests","order":0}}},"/platform/quests/{questId}":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"get":{"tags":["Platform delivery"],"operationId":"getPlatformQuest","summary":"Get a quest","description":"Returns one quest.","security":[{"PlatformKey":[]}],"parameters":[{"name":"external_user_id","in":"query","required":false,"description":"Your ID for the user. Sets completed.","schema":{"type":"string"}},{"name":"X-AdQuest-Participant-Token","in":"header","required":false,"description":"The participant token. Optional here. It adds per-user state such as completed.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"The quest.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quest"}}}]},"example":{"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":{"description":"The quest does not exist or is not available to this platform.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"status":false,"code":"QUEST_NOT_FOUND","message":"Quest not found","data":null}}}}},"x-docs":{"page":"api/quests","id":"get-quest","order":1},"x-example-verified":true}},"/platform/quests/{questId}/start":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"post":{"tags":["Platform delivery"],"operationId":"startPlatformQuest","summary":"Start a quest","description":"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.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_user_id":{"type":"string","maxLength":255,"description":"Your ID for the user. Max 255 characters.","example":"player-42"},"watch_duration":{"type":"integer","description":"Seconds, 1 to 600."}},"required":["external_user_id"]}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Quest started","data":{"quest_id":23,"display_duration":15,"expires_in":15}}}}},"404":{"description":"QUEST_NOT_FOUND. The quest does not exist, is not available, or needs a capability your client did not declare (quiz, multi_step)."},"409":{"description":"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":{"description":"A field failed validation. For a format that holds no attempt, an exhausted budget is also 422 with data.code QUEST_BUDGET_EXHAUSTED."},"429":{"description":"QUEST_BUSY from the start gate: too many starts at once. Retryable, like the 409 QUEST_BUSY: retry after data.retry_after seconds."}},"x-docs":{"page":"api/quests","id":"start-quest","order":2}}},"/platform/quests/{questId}/click":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"post":{"tags":["Platform delivery"],"operationId":"clickPlatformQuest","summary":"Record a click","description":"Records that the participant clicked the quest’s media. Send it only when a real click happens.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_user_id":{"type":"string","maxLength":255,"description":"Your ID for the user. Max 255 characters.","example":"player-42"}},"required":["external_user_id"]}}}},"responses":{"200":{"description":"The click was recorded. Also returned with this status: the participant already completed this quest. status is false and data.completed is true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Quest click recorded","data":{"quest_id":23,"clicked_at":"2026-01-01T12:00:00.000Z"}}}}},"404":{"description":"QUEST_NOT_FOUND."}},"x-docs":{"page":"api/quests","id":"click-quest","order":3}}},"/platform/quests/{questId}/view":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"post":{"tags":["Platform delivery"],"operationId":"viewPlatformQuest","summary":"Record that a participant saw a quest. First viewed_at sticks.","description":"Records that the participant saw the quest. The first view is kept. Later calls keep the same viewed_at.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_user_id":{"type":"string","maxLength":255,"description":"Your ID for the user. Max 255 characters.","example":"player-42"}},"required":["external_user_id"]}}}},"responses":{"200":{"description":"The view was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Quest view recorded","data":{"quest_id":23}}}}},"404":{"description":"QUEST_NOT_FOUND."},"422":{"description":"A field failed validation, for example a missing external_user_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"status":false,"code":"VALIDATION_ERROR","message":"The external user id field is required.","data":{"external_user_id":["The external user id field is required."]}}}}}},"x-docs":{"page":"api/quests","id":"view-quest","order":4}}},"/platform/quests/{questId}/progress":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"post":{"tags":["Platform delivery"],"operationId":"progressPlatformQuest","summary":"Record watch progress","description":"Records watch evidence for a timed quest. Send it while the participant is really watching.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_user_id":{"type":"string","maxLength":255,"description":"Your ID for the user. Max 255 characters.","example":"player-42"},"watch_duration":{"type":"number","description":"Seconds watched so far.","example":8}},"required":["external_user_id"]}}}},"responses":{"200":{"description":"The progress was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Quest progress recorded","data":{"quest_id":23,"elapsed_seconds":8,"required_seconds":15}}}}},"404":{"description":"QUEST_NOT_FOUND. The quest does not exist or is not available."},"422":{"description":"The evidence was rejected. data.reason says why. If the quest is already completed, data.completed is true."}},"x-docs":{"page":"api/quest-actions","id":"record-progress","order":1},"x-example-verified":true}},"/platform/quests/{questId}/visit":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"get":{"tags":["Platform delivery"],"operationId":"visitPlatformQuest","summary":"Attribute a visit","description":"Records that the participant followed the link of a visit quest and returns the destination. Visit quests only.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"external_user_id","in":"query","required":true,"description":"Your ID for the user. May also be sent in the body.","schema":{"type":"string"}},{"name":"referrer_external_user_id","in":"query","required":false,"description":"The user who shared the link, if any.","schema":{"type":"string"}},{"name":"redirect","in":"query","required":false,"description":"Send 1 to receive an HTTP redirect to the destination instead of JSON.","schema":{"type":"string"}},{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"The visit was attributed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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"}}}}},"400":{"description":"NOT_VISIT_QUEST. The quest is not a visit quest."},"401":{"description":"PARTICIPANT_AUTH_REQUIRED. external_user_id is missing."},"404":{"description":"QUEST_NOT_FOUND. The quest does not exist or is not available."}},"x-docs":{"page":"api/quest-actions","id":"visit","order":3}}},"/platform/quests/{questId}/question":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"get":{"tags":["Platform delivery"],"operationId":"getPlatformQuestQuestion","summary":"Get the question","description":"Returns the questions and their options for a video, banner, survey or quiz quest. The quest must have been started for this user. A video or banner quest can ask up to 10 graded questions.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"external_user_id","in":"query","required":true,"description":"Your ID for the user.","schema":{"type":"string"}},{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"The first question, plus questions with every question of the attempt. For an attempt held by AdQuest, ask_order lists the question ids in the order they are asked (a missed graded question again at the end) and due_at is the current deadline. Also returned with this status: status is false when external_user_id is missing, the quest was not started or its timer expired, or the quest has no question. The message says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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":[]}}}}},"404":{"description":"QUEST_NOT_FOUND. The quest does not exist or is not available."}},"x-docs":{"page":"api/quest-actions","id":"get-question","order":0}}},"/platform/quests/{questId}/complete":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"post":{"tags":["Platform delivery"],"operationId":"completePlatformQuest","summary":"Complete a quest","description":"Submits the participant’s evidence. AdQuest checks it on the server and, when it is valid, settles the reward. For a quest held as an attempt (video, banner, survey, quiz, visit), name the attempt with reservation_id or the X-AdQuest-Reservation header. A client that declares the async_complete capability gets 202 while the reward is paid; poll the completion status. Graded questions sent here all at once get no second chance: send them one by one to the answer route for that.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Send as an HTTP header. A repeated key returns the earlier completion and never pays twice.","schema":{"type":"string"}},{"name":"X-AdQuest-Reservation","in":"header","required":false,"description":"The reservation_id returned by start. The same as the reservation_id body field.","schema":{"type":"string"}},{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_user_id":{"type":"string","maxLength":255,"description":"Your ID for the user. Max 255 characters.","example":"player-42"},"question_id":{"type":"integer","description":"Required for video and banner quests, and for surveys when answers is not sent.","example":5},"user_input":{"type":"string","description":"The option the participant chose. Required together with question_id.","example":"11"},"answers":{"type":"array","items":{},"description":"Survey only. One entry per answered question, each with its question_id."},"delivery_token":{"type":"string","description":"Token you received when the quest started."},"watch_duration":{"type":"number","description":"Seconds watched."},"reservation_id":{"type":"string","maxLength":64,"description":"The reservation_id returned by start, for a quest held as an attempt. A request naming an earlier attempt is refused."},"evidence_type":{"type":"string","description":"Custom quests: url_callback or manual_review. Must match the quest's evidence type."},"evidence":{"type":"string","description":"Custom quests with manual_review: the participant's proof, up to 2000 characters."}},"required":["external_user_id"]}}}},"responses":{"200":{"description":"The quest was completed. tokens_awarded is the participant’s share. Also returned with this status: status false when the evidence was not enough (data.reason, such as timer_expired, click_required or visit_too_short) or a graded answer was wrong (ANSWER_REJECTED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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}}}}},"202":{"description":"ACCEPTED, for a client that declares async_complete: the submission was accepted and is being paid. data.settlement_status is pending. Poll the completion status."},"401":{"description":"PARTICIPANT_AUTH_REQUIRED. The participant token is missing or invalid."},"403":{"description":"PREVIEW_READONLY. A theme preview cannot complete quests."},"404":{"description":"QUEST_NOT_FOUND. The quest does not exist or is not available."},"409":{"description":"IDEMPOTENCY_KEY_REUSED (the key was used for another request), NOT_STARTED, STALE_RESERVATION (an earlier attempt was named), or MULTI_STEP_REQUIRED (a multi-step quest with required steps still open)."},"422":{"description":"Validation failed, the evidence was rejected, or the quest settles itself. STREAK_SETTLES_ITSELF: a streak day counts from the activities your server reports; ACTIVITY_GOAL_NOT_MET: an event Quest completes when its activity goal is met."},"503":{"description":"RETRYABLE_CONFLICT or SETTLEMENT_PENDING. Nothing was lost: retry with the same Idempotency-Key."}},"x-docs":{"page":"api/quest-actions","id":"complete-quest","order":7},"x-example-verified":true}},"/platform/quests/{questId}/answer":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"post":{"tags":["Platform delivery"],"operationId":"answerPlatformQuest","summary":"Answer one question","description":"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.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question_id":{"type":"integer","description":"The current question.","example":5},"option_id":{"type":"integer","description":"The chosen option (choice questions)."},"free_text":{"type":"string","description":"The answer (free-text questions)."},"reservation_id":{"type":"string","description":"The reservation_id returned by start (or the X-AdQuest-Reservation header). Required: an answer must name its attempt, and it must be the current one (409 STALE_RESERVATION otherwise, 422 RESERVATION_REQUIRED when missing)."}},"required":["question_id"]}}}},"responses":{"200":{"description":"The answer was recorded; the next question's deadline is in the data. correct is false when a video or banner quiz question was missed for the first time: the attempt goes on and the question is asked once more after the others (ask_order lists the question ids in the order they are asked). A second miss on it ends the attempt (ANSWER_REJECTED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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"}}}}},"202":{"description":"The final answer was accepted. The attempt is processing: capacity and budget stay reserved until settlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"ACCEPTED","message":"Answer accepted","data":{"state":"processing","reservation_id":"0f4f6c52-3c7d-4d6e-9d0f-6f9d3f1d2a11","settlement_status":"pending","quest_id":23}}}}},"409":{"description":"RESERVATION_EXPIRED, WRONG_QUESTION, STALE_RESERVATION or TOO_EARLY."},"422":{"description":"The answer is not valid for the question."}},"x-docs":{"page":"api/quest-actions","id":"answer-question","order":6}}},"/platform/quests/{questId}/review":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"get":{"tags":["Platform delivery"],"operationId":"getPlatformQuestReview","summary":"Check a manual review","description":"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.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"The latest review for the participant. settlement_status is pending or settled once approved, otherwise null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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}}}}}},"x-docs":{"page":"api/quest-actions","id":"get-review","order":9}}},"/platform/quests/{questId}/completion":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"get":{"tags":["Platform delivery"],"operationId":"getPlatformQuestCompletion","summary":"Check a completion","description":"Where the participant's attempt stands: reserved, processing, settled, rejected or expired, with the settlement status and the tokens awarded once settled.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"The attempt's state. settlement_status is success, pending, failed or none.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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"}}}}}},"x-docs":{"page":"api/quest-actions","id":"get-completion","order":8}}},"/platform/balance":{"get":{"tags":["Wallet"],"operationId":"getParticipantBalance","summary":"Get the token balance","description":"Returns the participant’s current token balance.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"responses":{"200":{"description":"The balance.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TokenBalance"}}}]},"example":{"status":true,"code":"OK","message":"Participant token balance","data":{"tokens":120,"platform_user_id":55,"external_user_id":"player-42"}}}}},"401":{"description":"PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid."}},"x-docs":{"page":"api/rewards","id":"get-balance","order":0}}},"/platform/quests/{questId}/growth-status":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"get":{"tags":["Platform delivery"],"operationId":"readGrowthStatus","summary":"Read growth status","description":"Returns where the participant stands on an event, profile, referral, streak or custom quest. A referral's `referral` block also carries role (inviter | invitee: invited to this quest, with no invites of their own) and inviter_reward / invitee_reward, what one unit pays each side as decimals.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"external_user_id","in":"query","required":true,"description":"Your ID for the user. May also be sent in the body.","schema":{"type":"string"}},{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"data.type is the quest format. An event quest adds data.progress (current, target, unit) and data.activity, counted from the activities your server reports. A profile quest adds data.profile with the completeness check. A referral quest adds data.referral: code, code_source (adquest or platform), invite_link (null with platform codes), attributed_count, min_attributions, reward_target, can_complete, pay_each_invite, paid_units (invites paid so far; 0 unless pay_each_invite), max_units (the most invites that can be paid, or null when nothing caps it) and history, whose items carry payout_unit (the paid invite number, or null). Streak and custom quests add their own state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"PARTICIPANT_AUTH_REQUIRED. external_user_id is missing."},"404":{"description":"QUEST_NOT_FOUND. The quest does not exist or is not available."}},"x-docs":{"page":"api/quest-actions","id":"growth-status","order":6}}},"/platform/quests/{questId}/stats":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"get":{"tags":["Platform delivery"],"operationId":"readQuestStats","summary":"Read quest stats","description":"Returns engagement counts for one quest on your platform.","security":[{"PlatformKey":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":false,"description":"The participant token. Optional here. It adds per-user state such as completed.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"seen_count is participants who started the quest, clicked_count those who clicked, and answered_count those who completed it. engagement_rate is completed ÷ started as a percentage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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}}}}},"404":{"description":"QUEST_NOT_FOUND. The quest does not exist or is not available."}},"x-docs":{"page":"api/quest-actions","id":"quest-stats","order":8}}},"/platform/balance/history":{"get":{"tags":["Platform delivery"],"operationId":"getBalanceHistory","summary":"Get the balance history","description":"Returns the participant’s token transactions, newest first, as a paginated list.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"per_page","in":"query","required":false,"description":"Items per page. Defaults to 15.","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer"}}],"responses":{"200":{"description":"A paginated list. data holds the page of transactions with the pagination fields (current_page, last_page, per_page, total).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid."}},"x-docs":{"page":"api/rewards","id":"balance-history","order":1}}},"/platform/lotteries":{"get":{"tags":["Platform delivery"],"operationId":"listLotteries","summary":"List lotteries","description":"Returns the lotteries visible to this platform and participant country, with active ones first.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"filter","in":"query","required":false,"description":"active (default), upcoming, completed or all.","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"Items per page. Defaults to 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"A page of lotteries.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PlainEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"lotteries":{"type":"array","items":{"$ref":"#/components/schemas/Lottery"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}]},"example":{"status":true,"message":"Lotteries list","data":{"lotteries":[{"id":4,"name":"Weekly draw","description":"Win a gift card.","locale":"en","requested_locale":"en","source_locale":"en","is_fallback":false,"availability":{"policy_type":"global","policy_version":1,"eligibility":"eligible","warning":false,"countries":[]},"visibility":"public","entry_cost_tokens":20,"max_entries_per_participant":5,"starts_at":"2026-01-01T00:00:00+00:00","ends_at":"2026-01-08T00:00:00+00:00","lifecycle_status":"active","media_url":null,"prize_count":3,"participants_count":128,"hottest_position":1,"my_entry_count":2,"winners_count":null}],"pagination":{"current_page":1,"last_page":1,"per_page":20,"total":1}}}}}},"401":{"description":"PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid."}},"x-docs":{"page":"api/rewards","id":"list-lotteries","order":2},"x-example-verified":true}},"/platform/lotteries/{lotteryId}":{"parameters":[{"name":"lotteryId","in":"path","required":true,"description":"Lottery ID.","schema":{"type":"integer"},"example":4}],"get":{"tags":["Platform delivery"],"operationId":"getLottery","summary":"Get a lottery","description":"Returns one lottery with its prizes and the participant’s own entries.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"responses":{"200":{"description":"The lottery with its prizes and the participant’s own entry count.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PlainEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"lottery":{"allOf":[{"$ref":"#/components/schemas/Lottery"},{"type":"object","properties":{"awards":{"type":"array","items":{"type":"object"}},"my_entry_count":{"type":"integer"},"remaining_entries":{"type":"integer"}}}]}}}}}]},"example":{"status":true,"message":"Lottery details","data":{"lottery":{"id":4,"name":"Weekly draw","description":"Win a gift card.","locale":"en","requested_locale":"en","source_locale":"en","is_fallback":false,"availability":{"policy_type":"global","policy_version":1,"eligibility":"eligible","warning":false,"countries":[]},"visibility":"public","entry_cost_tokens":20,"max_entries_per_participant":5,"starts_at":"2026-01-01T00:00:00+00:00","ends_at":"2026-01-08T00:00:00+00:00","lifecycle_status":"active","media_url":null,"prize_count":3,"participants_count":128,"hottest_position":1,"awards":[{"id":1,"name":"Gift card","description":null,"locale":"en","requested_locale":"en","source_locale":"en","is_fallback":false,"type":"digital","count":3,"priority":1}],"my_entry_count":0,"remaining_entries":5}}}}}},"404":{"description":"LOTTERY_NOT_FOUND in data.code. The lottery does not exist or is not visible to this platform.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"},"example":{"status":false,"message":"Lottery not found","data":{"code":"LOTTERY_NOT_FOUND"}}}}}},"x-docs":{"page":"api/rewards","id":"get-lottery","order":3},"x-example-verified":true}},"/platform/lotteries/{lotteryId}/enter":{"parameters":[{"name":"lotteryId","in":"path","required":true,"description":"Lottery ID.","schema":{"type":"integer"},"example":4}],"post":{"tags":["Platform delivery"],"operationId":"enterLottery","summary":"Enter a lottery","description":"Spends tokens to buy entries. Send a unique idempotency_key for each purchase and reuse it when you retry after an uncertain response, so the participant is never charged twice.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entry_count":{"type":"integer","description":"How many entries to buy, 1 to 100.","example":2},"idempotency_key":{"type":"string","maxLength":191,"description":"Unique key for this purchase attempt. Max 191 characters.","example":"enter-4-player-42-001"}},"required":["entry_count","idempotency_key"]}}}},"responses":{"200":{"description":"The entries were purchased.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"},"example":{"status":true,"message":"Lottery entries purchased","data":{"purchase":{"id":301,"lottery_id":4,"entry_count":2,"unit_cost_tokens":20,"total_cost_tokens":40,"status":"completed","ticket_numbers":["1G2736","K7Q3X9"]},"eligibility_snapshot":{"country_code":"IR","country_source":"platform","eligibility_status":"eligible","availability_policy_version":1}}}}}},"401":{"description":"PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid."},"403":{"description":"PREVIEW_READONLY. A theme preview cannot enter lotteries."},"404":{"description":"LOTTERY_NOT_FOUND in data.code. The lottery does not exist or is not visible to this platform.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"},"example":{"status":false,"message":"Lottery not found","data":{"code":"LOTTERY_NOT_FOUND"}}}}},"409":{"description":"DUPLICATE_PURCHASE. The idempotency_key was already used for a different lottery or a different participant. Use a new key for each purchase attempt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"},"example":{"status":false,"message":"Duplicate purchase request","data":{"code":"DUPLICATE_PURCHASE"}}}}},"422":{"description":"Validation failed, or the purchase was refused. data.code says why, for example INSUFFICIENT_TOKENS, LOTTERY_CLOSED or ENTRY_LIMIT_REACHED."}},"x-docs":{"page":"api/rewards","id":"enter-lottery","order":4},"x-example-verified":true}},"/platform/lotteries/{lotteryId}/entries":{"parameters":[{"name":"lotteryId","in":"path","required":true,"description":"Lottery ID.","schema":{"type":"integer"},"example":4}],"get":{"tags":["Platform delivery"],"operationId":"listEntries","summary":"List my entries","description":"Returns the participant’s entries and purchases for one lottery.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"responses":{"200":{"description":"data has entries, purchases and entry_count.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"}}}},"401":{"description":"PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid."},"404":{"description":"LOTTERY_NOT_FOUND in data.code. The lottery does not exist or is not visible to this platform.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"},"example":{"status":false,"message":"Lottery not found","data":{"code":"LOTTERY_NOT_FOUND"}}}}}},"x-docs":{"page":"api/rewards","id":"my-entries","order":5}}},"/platform/lotteries/{lotteryId}/results":{"parameters":[{"name":"lotteryId","in":"path","required":true,"description":"Lottery ID.","schema":{"type":"integer"},"example":4}],"get":{"tags":["Platform delivery"],"operationId":"getLotteryResults","summary":"Get lottery results","description":"Returns the winners once the lottery is completed. Before that, winners is an empty list.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"responses":{"200":{"description":"data has lifecycle_status and winners. Winners are returned only when lifecycle_status is completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"},"example":{"status":true,"message":"Lottery results unavailable","data":{"lifecycle_status":"active","winners":[]}}}}},"404":{"description":"LOTTERY_NOT_FOUND in data.code. The lottery does not exist or is not visible to this platform.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"},"example":{"status":false,"message":"Lottery not found","data":{"code":"LOTTERY_NOT_FOUND"}}}}}},"x-docs":{"page":"api/rewards","id":"lottery-results","order":6}}},"/platform/lottery-tickets":{"get":{"tags":["Platform delivery"],"operationId":"listMyTickets","summary":"List my tickets","description":"Returns every ticket code the participant holds, one group per draw, the draw they entered most recently first.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"responses":{"200":{"description":"The participant’s ticket codes grouped by draw.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PlainEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"lotteries":{"type":"array","items":{"type":"object","properties":{"lottery_id":{"type":"integer"},"name":{"type":"string"},"ends_at":{"type":["string","null"],"format":"date-time"},"lifecycle_status":{"type":"string"},"tickets":{"type":"array","items":{"type":"object","properties":{"ticket_number":{"type":"string","example":"1G2736"},"has_won":{"type":"boolean"}}}}}}}}}}}]},"example":{"status":true,"message":"My lottery tickets","data":{"lotteries":[{"lottery_id":4,"name":"Weekly draw","ends_at":"2026-02-01T00:00:00+00:00","lifecycle_status":"active","tickets":[{"ticket_number":"1G2736","has_won":false},{"ticket_number":"K7Q3X9","has_won":false}]}]}}}}},"401":{"description":"PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid."}},"x-docs":{"page":"api/rewards","id":"my-tickets","order":7}}},"/platform/lottery-claims":{"get":{"tags":["Platform delivery"],"operationId":"listClaims","summary":"List my claims","description":"Returns the prizes the participant has won, newest first.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"responses":{"200":{"description":"The participant’s claims. Each claim also has an eligibility_snapshot.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PlainEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"claims":{"type":"array","items":{"$ref":"#/components/schemas/LotteryClaim"}}}}}}]},"example":{"status":true,"message":"My lottery claims","data":{"claims":[{"id":91,"lottery_id":4,"lottery_name":"Weekly draw","status":"pending","award_name":"Gift card","award_type":"gift","submitted_at":null,"fulfilled_at":null,"claim_expires_at":"2026-02-01T00:00:00+00:00"}]}}}}},"401":{"description":"PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid."}},"x-docs":{"page":"api/rewards","id":"my-claims","order":8}}},"/platform/lottery-claims/{claimId}":{"parameters":[{"name":"claimId","in":"path","required":true,"description":"Claim ID from the claims list.","schema":{"type":"integer"},"example":91}],"post":{"tags":["Platform delivery"],"operationId":"submitClaim","summary":"Submit a claim","description":"Submits the winner’s claim details. The fields the payload needs depend on the prize and the claim form.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"The claim details the prize requires.","example":{"email":"ada@example.com","name":"Ada"}}},"required":["payload"]}}}},"responses":{"200":{"description":"The claim was submitted. data.claim is the updated claim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"}}}},"401":{"description":"PARTICIPANT_AUTH_REQUIRED in data.code. The participant token is missing or invalid."},"403":{"description":"PREVIEW_READONLY. A theme preview cannot submit claims."},"404":{"description":"CLAIM_NOT_AVAILABLE. The claim does not belong to this participant."},"422":{"description":"Validation failed, or the claim is closed or expired. data.code says why."}},"x-docs":{"page":"api/rewards","id":"submit-claim","order":9}}},"/platform/config":{"get":{"tags":["Platform delivery"],"operationId":"getPlatformConfig","summary":"Get platform config","description":"Returns the published branding and configuration for the platform that owns the API key.","security":[{"PlatformKey":[]}],"responses":{"200":{"description":"The platform’s name and published theme.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Platform config","data":{"name":"Subway Sample","theme":{"colors":{"primary":"#FB6514"}},"public_id":"63e1528f-0214-439e-b233-a9b99c54fb77"}}}}}},"x-docs":{"page":"api/platform","id":"platform-config","order":0}}},"/platform/public-config/{publicId}":{"parameters":[{"name":"publicId","in":"path","required":true,"description":"The platform’s UUID, from your Embed URL.","schema":{"type":"string"},"example":"63e1528f-0214-439e-b233-a9b99c54fb77"}],"get":{"tags":["Platform delivery"],"operationId":"getPublicConfig","summary":"Get public config","description":"Returns the same configuration by the platform’s public ID. The hosted embed uses it to load your branding. No credentials are needed.","security":[],"responses":{"200":{"description":"The platform’s name and published theme. The response is never cached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"}}}},"404":{"description":"The ID is not a UUID, or no accepted and active platform has it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainEnvelope"},"example":{"status":false,"message":"Platform not found","data":null}}}}},"x-docs":{"page":"api/platform","id":"public-config","order":1}}},"/platform/lottery-claims/{claimId}/contact":{"parameters":[{"name":"claimId","in":"path","required":true,"description":"Claim ID from the lottery.winner webhook.","schema":{"type":"integer"},"example":91}],"post":{"tags":["Platform delivery"],"operationId":"postWinnerContact","summary":"Post a winner’s contact","description":"Sends AdQuest the winner’s email after a lottery.winner webhook, so AdQuest can notify them. Call it only for the winner of that claim. A platform that tells its winners itself (notifies_lottery_winners on the platform) does not need it: the lottery.winner webhook carries lottery_name, award_name, award_type, award_description, claim_expires_at and claim_screen (claims: the SDK screen where the winner registers the prize, opened with the widget's navigate or the embed's adquest:init / adquest:navigate view), and AdQuest sends no email; there email and display_name are optional, and an email sent anyway is still mailed.","security":[{"PlatformSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_user_id":{"type":"string","maxLength":255,"description":"Your ID for the winner. Max 255 characters.","example":"player-42"},"email":{"type":"string","maxLength":255,"description":"The winner’s email. Max 255 characters. Required unless your platform notifies its winners itself.","example":"ada@example.com"},"display_name":{"type":"string","maxLength":255,"description":"The winner’s name. Max 255 characters.","example":"Ada"}},"required":["external_user_id"]}}}},"responses":{"200":{"description":"The contact was received.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"status":true,"code":"OK","message":"Winner contact received","data":{"claim_id":91,"notified":true}}}}},"401":{"description":"The Secret Key is missing or wrong."},"403":{"description":"The platform is not accepted and active."},"404":{"description":"CLAIM_NOT_AVAILABLE."},"429":{"description":"RATE_LIMITED. Too many contact requests."}},"x-docs":{"page":"api/server-routes","id":"winner-contact","order":0}}},"/platform/quests/{questId}/execution":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23}],"get":{"tags":["Platform delivery"],"operationId":"getPlatformQuestExecution","summary":"Read a multi-step execution","description":"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. Returns 404 MULTI_STEP_DISABLED when multi-step quests are off for the environment, and 503 MULTI_STEP_DISABLED when attempt holds (reservations) are off.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"The execution state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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}}}}}},"x-docs":{"page":"api/quest-actions","id":"get-execution","order":10}}},"/platform/quests/{questId}/steps/{key}":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23},{"name":"key","in":"path","required":true,"description":"Step key.","schema":{"type":"string"},"example":"buy"}],"get":{"tags":["Platform delivery"],"operationId":"getPlatformQuestStep","summary":"Read one step","description":"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.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"The execution state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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}}}}}},"x-docs":{"page":"api/quest-actions","id":"get-step","order":11}}},"/platform/quests/{questId}/steps/{key}/evidence":{"parameters":[{"name":"questId","in":"path","required":true,"description":"Quest ID.","schema":{"type":"integer"},"example":23},{"name":"key","in":"path","required":true,"description":"Step key.","schema":{"type":"string"},"example":"buy"}],"post":{"tags":["Platform delivery"],"operationId":"submitPlatformQuestStepEvidence","summary":"Submit step evidence","description":"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. Condition and streak steps are met by the activities your server reports to POST /server/activities. When the last required step is verified the parent is admitted for settlement without another request; poll the execution or completion for the result.","security":[{"PlatformKey":[],"ParticipantToken":[]}],"parameters":[{"name":"X-AdQuest-Participant-Token","in":"header","required":true,"description":"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.","schema":{"type":"string"},"example":"PARTICIPANT_TOKEN"}],"responses":{"200":{"description":"The execution state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"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}}}}},"202":{"description":"Evidence accepted for asynchronous review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"409":{"description":"STEP_OUT_OF_ORDER, STEP_NOT_STARTED, RESERVATION_EXPIRED, NOT_STARTED or QUEST_PROCESSING.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The server could not verify the step from the evidence (CLICK_REQUIRED, TIMER_NOT_FINISHED, CUSTOM_EVIDENCE_MISSING, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-docs":{"page":"api/quest-actions","id":"submit-step-evidence","order":12},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["start","click"],"description":"start begins a timed (video/banner) step; click records the click of a visit step. Omit to submit evidence."},"evidence":{"type":"string","maxLength":2000,"description":"Proof text for a manual_review step (max 2000 characters)."},"evidence_type":{"type":"string","description":"Evidence type the step expects (must match the step configuration)."},"answers":{"type":"array","items":{"type":"object"},"description":"Survey answers: [{question_id, user_input}]."}}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"PlatformKey":{"type":"apiKey","in":"header","name":"X-AdQuest-Platform-Key","description":"Publisher platform API key (aqk_...). Accepts active keys and previous keys within the rotation grace window."},"PlatformSecret":{"type":"apiKey","in":"header","name":"X-AdQuest-Platform-Secret","description":"Secret Key (aqs_) for server-to-server calls such as creating participant sessions. Keep it on your server. Distinct from PlatformKey."},"ServerSignature":{"type":"apiKey","in":"header","name":"X-AdQuest-Signature","description":"t=<unix seconds>,v1=<lowercase hex HMAC-SHA256 of t + \".\" + the raw request body, with your event signing secret>, sent with X-AdQuest-Platform-Key. Optional: an alternative to X-AdQuest-Platform-Secret. Rejected when t is more than 300 s off."},"ParticipantToken":{"type":"apiKey","in":"header","name":"X-AdQuest-Participant-Token","description":"Participant token (a JWT) from a participant session. It expires after 15 minutes. Refresh it through your backend."}},"schemas":{"Envelope":{"type":"object","required":["status","code","message","data"],"properties":{"status":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"},"data":{},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"Error":{"type":"object","required":["status","code","message"],"properties":{"status":{"const":false},"code":{"type":"string"},"message":{"type":"string"},"data":{},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"PlainEnvelope":{"type":"object","description":"Envelope used by lottery, claim and public-config routes. It has no top-level code. Read data.code on errors.","required":["status","message","data"],"properties":{"status":{"type":"boolean"},"message":{"type":"string"},"data":{}}},"Pagination":{"type":"object","properties":{"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}},"ParticipantSession":{"type":"object","required":["participant_token","expires_in"],"properties":{"participant_token":{"type":"string","description":"A signed JWT. Send it as X-AdQuest-Participant-Token."},"expires_in":{"type":"integer","description":"Seconds until the token expires. Always 900 (15 minutes).","example":900},"expires_at":{"type":"string","format":"date-time"},"locale_resolution":{"type":"object","properties":{"requested":{"type":"string"},"effective":{"type":"string"},"source":{"type":"string"}}},"platform_user":{"type":"object","properties":{"id":{"type":"integer"},"external_user_id":{"type":"string"},"display_name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"country_code":{"type":["string","null"]},"country_name":{"type":["string","null"]},"eligibility_country_code":{"type":["string","null"]},"eligibility_country_source":{"type":["string","null"]}}},"eligibility":{"type":"object","description":"What the participant has shared, used by profile quests."}}},"TokenBalance":{"type":"object","properties":{"tokens":{"type":"integer"},"platform_user_id":{"type":"integer"},"external_user_id":{"type":"string"}}},"Quest":{"type":"object","description":"A quest as returned to participants. Format-specific rule fields are filled only for that format.","properties":{"id":{"type":"integer"},"name":{"type":"string"},"type":{"type":"string","description":"Format key: video, banner, survey, quiz, visit, event, profile, referral, streak, custom or multi_step."},"type_name":{"type":"string"},"visibility":{"type":"string"},"platform_id":{"type":["integer","null"]},"token_reward":{"type":["integer","null"],"description":"Tokens this participant earns."},"token_reward_total":{"type":["integer","null"],"description":"Total reward before the participant and AdQuest split it."},"gift_reward":{"type":["object","null"]},"gift_reward_expires_at":{"type":["string","null"]},"status":{"type":"string","enum":["active","in_progress"],"description":"active, or in_progress for an auto-start quest the participant has not completed: the participant session started it (custom, referral, multi_step) or it counts from launch (event)."},"auto_start":{"type":"boolean","description":"True when the quest starts on its own (White Label custom, referral and multi_step quests, event quests with enrollment auto); the widget shows Continue, and start resumes the running attempt."},"screen":{"type":"string","description":"The widget screen that renders this quest."},"content":{"type":["string","null"]},"cover":{"type":["string","null"]},"redirect_url":{"type":["string","null"]},"display_duration":{"type":["integer","null"],"description":"Seconds a banner must be shown. Banner quests only."},"start_date":{"type":["string","null"]},"end_date":{"type":["string","null"]},"completed":{"type":"boolean","description":"Whether this participant already completed the quest. Needs external_user_id."},"completion_condition":{"type":"object","description":"What the participant must do. Flags: requires_timer, requires_question, requires_click, requires_event, requires_profile, requires_referral, requires_streak, requires_custom, and answer_mode."},"event_rule":{"type":["object","null"]},"profile_rule":{"type":["object","null"]},"referral_rule":{"type":["object","null"]},"streak_rule":{"type":["object","null"]},"custom_rule":{"type":["object","null"]},"media":{"type":"object","description":"The quest media: type, url and cover."},"proof":{"type":"object","description":"The evidence this format needs (type, version, media, timed). Present only when the runtime supports the format."},"reward":{"type":"object"},"reward_unit":{"type":["object","null"],"description":"The platform's own reward unit when the owner fulfils the reward; null means AdQuest tokens.","properties":{"code":{"type":"string"},"label":{"type":"string"},"icon_url":{"type":["string","null"]}}},"reward_is_max":{"type":"boolean","description":"True when token_reward is the most a participant can earn (per-second, per-question and similar metrics), not a fixed amount."},"availability":{"type":"string","enum":["locked"],"description":"Present only when the participant cannot start this quest: 'locked' with a lock_reason. Needs external_user_id."},"lock_reason":{"type":"string","enum":["ATTEMPTS_EXHAUSTED"],"description":"Why the quest is locked. ATTEMPTS_EXHAUSTED: every allowed attempt was used without completing it; a start is refused with ATTEMPTS_EXHAUSTED."}}},"Lottery":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"locale":{"type":"string"},"requested_locale":{"type":"string"},"source_locale":{"type":"string"},"is_fallback":{"type":"boolean"},"availability":{"type":"object","description":"Whether this participant may see and enter the lottery, by country policy.","properties":{"policy_type":{"type":"string"},"policy_version":{"type":"integer"},"eligibility":{"type":"string"},"warning":{"type":"boolean"},"countries":{"type":"array","items":{"type":"string"}}}},"visibility":{"type":"string"},"entry_cost_tokens":{"type":"integer"},"max_entries_per_participant":{"type":"integer"},"starts_at":{"type":["string","null"]},"ends_at":{"type":["string","null"]},"lifecycle_status":{"type":"string"},"media_url":{"type":["string","null"]},"prize_count":{"type":"integer"},"participants_count":{"type":"integer"},"hottest_position":{"type":["integer","null"],"description":"The platform marked this draw hottest: it leads the rewards tab as a hero card, in this order (1 first). Null when not marked. Marked open draws come first in the list."},"my_entry_count":{"type":"integer","description":"Tickets the calling participant holds in this lottery (0 without a participant). Detail and list."},"winners_count":{"type":["integer","null"],"description":"Winners of a completed lottery; null while it has not finished. List only."}}},"LotteryClaim":{"type":"object","properties":{"id":{"type":"integer"},"lottery_id":{"type":"integer"},"lottery_name":{"type":["string","null"]},"status":{"type":"string"},"award_name":{"type":["string","null"]},"award_type":{"type":["string","null"]},"submitted_at":{"type":["string","null"]},"fulfilled_at":{"type":["string","null"]},"claim_expires_at":{"type":["string","null"]},"eligibility_snapshot":{"type":["object","null"]}}}}}}