# AdQuest

> AdQuest lets your signed-in users complete quests and earn tokens that they spend on lotteries, inside your own app. This is the documentation for developers who integrate it and for publishers who run it from the dashboard.

Every page is also available as Markdown: add `.md` to its address. The API contract is OpenAPI 3.1.

## Machine-readable

- [All documentation in one file](https://dashboard.adquest.batriders.ir/llms-full.txt): every page as Markdown
- [OpenAPI contract](https://dashboard.adquest.batriders.ir/openapi.json): the partner API, with parameters, auth and examples
- [Using the docs with AI agents](https://dashboard.adquest.batriders.ir/docs/ai-agents.md): rules to give your agent

## Developers

Integrate AdQuest into your app with the SDK or the API.

### Get started

- [Introduction](https://dashboard.adquest.batriders.ir/docs.md): AdQuest puts quests inside your app. Your signed-in users complete short tasks, earn tokens and spend them on lotteries, without leaving your product or creating another account.
- [How AdQuest works](https://dashboard.adquest.batriders.ir/docs/how-it-works.md): Who does what, which credential lives where, and which integration method to choose.
- [Keys and environments](https://dashboard.adquest.batriders.ir/docs/environments.md): The four values you get from the publisher, where each one goes in your app, and how to keep them safe.
- [Quickstart](https://dashboard.adquest.batriders.ir/docs/quickstart.md): Show your first quest to a signed-in user: one backend route and one widget.
- [Quickstart: iframe or WebView](https://dashboard.adquest.batriders.ir/docs/quickstart-embed.md): Show your first quest in the hosted embed, from any website, with one backend route and a few lines of JavaScript.
- [Complete example: Next.js](https://dashboard.adquest.batriders.ir/docs/examples.md): A session route, a widget with token refresh, and a signed webhook receiver for a Next.js app.

### Build

- [Authentication](https://dashboard.adquest.batriders.ir/docs/authentication.md): The credentials AdQuest uses, which request each one goes on, and where it may be stored.
- [Participant sessions](https://dashboard.adquest.batriders.ir/docs/participant-sessions.md): Connect your app’s signed-in user to an AdQuest participant without exposing your private secret.
- [React & Next.js](https://dashboard.adquest.batriders.ir/docs/react.md): Add the ready-made quest and rewards widget to a React 18+ application.
- [Hosted iframe & WebView](https://dashboard.adquest.batriders.ir/docs/embed.md): Use the hosted SDK on any website or inside a native application.
- [Headless JavaScript](https://dashboard.adquest.batriders.ir/docs/headless.md): Build your own interface with the typed client and use the public API for format-specific completion evidence.
- [Tokens, lotteries & claims](https://dashboard.adquest.batriders.ir/docs/rewards.md): Read participant balances, enter lotteries and manage claims using authenticated server results.
- [Webhooks](https://dashboard.adquest.batriders.ir/docs/webhooks.md): Receive signed server notifications and reconcile outcomes in your own backend.
- [Multi-step quests](https://dashboard.adquest.batriders.ir/docs/multi-step-quests.md): A participant finishes several steps and is paid once. What your app sends, what AdQuest decides, and how to read progress.

### Quest evidence

- [Quest evidence overview](https://dashboard.adquest.batriders.ir/docs/quest-evidence.md): How each quest format collects proof, and the shared request helper the examples use.
- [Video evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/video.md): API type: video. Reward attention followed by a comprehension check.
- [Time-link / banner evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/time-link.md): API type: banner. Display a timed creative and ask a completion question.
- [Survey evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/survey.md): API type: survey. Collect structured responses without a media watch timer.
- [Quiz evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/quiz.md): API type: quiz. Graded questions with no media; each answer is checked on the server.
- [Visit evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/visit.md): API type: visit. Attribute a visit to your destination URL.
- [Event evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/event.md): API type: event. Verify a signup, purchase, install or another named product event.
- [Profile evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/profile.md): API type: profile. Reward a participant for completing approved profile attributes.
- [Referral evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/referral.md): API type: referral. Connect an invite code to a distinct participant’s qualifying action.
- [Streak evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/streak.md): API type: streak. Own-platform only. Your backend reports each day through a generated callback URL.
- [Custom evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/custom.md): API type: custom. Own-platform only. Define an outcome using an allowlisted evidence model.
- [Multi-step evidence](https://dashboard.adquest.batriders.ir/docs/quest-evidence/multi-step.md): API type: multi_step. Own-platform only. One reward after every required step is verified.

### Go live

- [Test & go live](https://dashboard.adquest.batriders.ir/docs/launch.md): Walk through the full lifecycle in the environment you intend to launch.
- [Troubleshooting](https://dashboard.adquest.batriders.ir/docs/troubleshooting.md): Trace integration failures from platform configuration through participant settlement.

### API reference

- [API reference](https://dashboard.adquest.batriders.ir/docs/api-reference.md): Base URL, authentication, headers and response format shared by every public AdQuest route.
- [Participant sessions API](https://dashboard.adquest.batriders.ir/docs/api/participant-sessions.md): Create a participant token for one of your signed-in users. Backend only.
- [Quests API](https://dashboard.adquest.batriders.ir/docs/api/quests.md): List quests, read one, start it and record views and clicks.
- [Quest actions API](https://dashboard.adquest.batriders.ir/docs/api/quest-actions.md): Send the evidence each quest format needs, then complete the quest.
- [Rewards API](https://dashboard.adquest.batriders.ir/docs/api/rewards.md): Read a participant’s token balance, enter lotteries and submit prize claims.
- [Platform API](https://dashboard.adquest.batriders.ir/docs/api/platform.md): Read your platform’s public configuration and branding.
- [Server routes API](https://dashboard.adquest.batriders.ir/docs/api/server-routes.md): Routes your backend calls: winner contact, fulfillment acknowledgements and streak callbacks.
- [Errors](https://dashboard.adquest.batriders.ir/docs/errors.md): Error codes returned by the API and SDK, and what to check for each.
- [Bridge messages](https://dashboard.adquest.batriders.ir/docs/bridge-messages.md): Messages exchanged between your page or native app and the hosted embed.
- [Webhook events](https://dashboard.adquest.batriders.ir/docs/api/webhook-events.md): Headers, signatures, retries and the payload of each event AdQuest sends to your endpoint.

### SDK reference

- [Client](https://dashboard.adquest.batriders.ir/docs/sdk/client.md): Create the typed AdQuest client and set the user, token and host context.
- [Quest methods](https://dashboard.adquest.batriders.ir/docs/sdk/quests.md): Client methods for listing quests, starting them and sending evidence.
- [Reward methods](https://dashboard.adquest.batriders.ir/docs/sdk/rewards.md): Client methods for balances, lotteries, entries and claims.
- [Quest session](https://dashboard.adquest.batriders.ir/docs/sdk/quest-session.md): The object startQuest returns. It tracks the timer, the question and the completion of one quest.
- [React components](https://dashboard.adquest.batriders.ir/docs/sdk/react.md): Props, callbacks and views of the AdQuestWidget and QuestWidget components.
- [AdQuestError](https://dashboard.adquest.batriders.ir/docs/sdk/errors.md): The error every SDK method throws, with its stable codes.

### Resources

- [FAQ](https://dashboard.adquest.batriders.ir/docs/faq.md): Short answers to the questions integrators ask most.
- [Glossary](https://dashboard.adquest.batriders.ir/docs/glossary.md): The terms used across the AdQuest documentation.
- [Changelog](https://dashboard.adquest.batriders.ir/docs/changelog.md): Notable changes to the AdQuest SDK and public API.
- [Use the docs with AI agents](https://dashboard.adquest.batriders.ir/docs/ai-agents.md): Machine-readable entry points and a rules file that help coding agents integrate AdQuest correctly.

## Publishers

Set up your platform, quests and rewards in the dashboard. No code.

### Start here

- [AdQuest for publishers](https://dashboard.adquest.batriders.ir/docs/dashboard.md): Add your app or site, make AdQuest look like it, publish quests and follow the results, all from the dashboard. Your developer does one part: showing AdQuest in your app.
- [Create your account](https://dashboard.adquest.batriders.ir/docs/dashboard/account.md): Sign up with your phone number, type the code we send you and tell us your name. Later you sign in with your email or Google.
- [Add your platform](https://dashboard.adquest.batriders.ir/docs/dashboard/platform.md): Add your app or site, check its colours, save your first keys, then get it reviewed and switched on.
- [Keys for your developer](https://dashboard.adquest.batriders.ir/docs/dashboard/keys.md): Everything your developer needs is on your platform’s Connection tab. What to send, how to send it safely, and what to do if a key leaks.
- [Brand it in Theme Studio](https://dashboard.adquest.batriders.ir/docs/dashboard/theme-studio.md): Change how AdQuest looks inside your app by describing it in a chat, check it on a phone and a desktop, and publish when you are happy.

### Quests

- [Create your first quest](https://dashboard.adquest.batriders.ir/docs/dashboard/quests.md): Choose how the quest runs and who pays for it, pick what people do, set it up one section at a time, and publish.
- [Funding: credits, boost and tokens](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/funding.md): How a quest is paid for, and how that differs from the tokens people earn.
- [Video with end question](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/video.md): People watch a video, then answer a question about it to earn their reward.
- [Time-link](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/time-link.md): People look at a banner for a set time, then answer a question to earn their reward.
- [Survey](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/survey.md): People answer your questions to earn their reward. There is no timer.
- [Quiz](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/quiz.md): People answer your questions right to earn their reward. Each question has one correct answer.
- [Visit destination](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/visit.md): People open a link to earn their reward.
- [Verified event](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/event.md): People earn their reward when something you track happens in your product, such as a signup or a purchase.
- [Profile completion](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/profile.md): People earn their reward by completing their profile in your app.
- [Referral invite](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/referral.md): People earn their reward when a friend they invited joins and does what you ask.
- [Streak](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/streak.md): People earn their reward for doing something on several days in a row. Private quests only.
- [Custom outcome](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/custom.md): People earn their reward for an outcome you define and prove your own way. Private quests only.
- [Multi-step quest](https://dashboard.adquest.batriders.ir/docs/dashboard/quests/multi-step.md): People finish several steps and get one reward at the end. Private quests only, where multi-step quests are enabled.

### Results and money

- [Home and Results](https://dashboard.adquest.batriders.ir/docs/dashboard/analytics.md): Home shows what needs you and how the last days went. Results goes deeper: what people did, who came back and where they dropped off.
- [Rewards and credits](https://dashboard.adquest.batriders.ir/docs/dashboard/billing.md): Top up credits, see what you earn, get paid through Stripe, and check every payment in History.

### Lotteries (White Label)

- [Create a lottery](https://dashboard.adquest.batriders.ir/docs/dashboard/lotteries.md): White Label accounts can run prize draws that people enter with the tokens they earn.
- [Winners and prizes](https://dashboard.adquest.batriders.ir/docs/dashboard/lotteries/winners-claims.md): After the draw, check each winner’s details, approve them, and mark the prize as sent once you have delivered it.

### Help

- [When something does not work](https://dashboard.adquest.batriders.ir/docs/dashboard/troubleshooting.md): Plain-language checks for the most common problems, and who should look at each one.