API reference
API reference
Base URL, authentication, headers and response format shared by every public AdQuest route.
On this page
Base URL
Base URL
ADQUEST_API_URL=https://api.adquest.batriders.ir/api/v1All routes in this reference are relative to this URL. Use the API URL for your environment, and always include /api/v1.
Authentication
| Header | Used on | Value |
|---|---|---|
| X-AdQuest-Platform-Key | Every /platform route except public-config | Your public API key (aqk_). Safe in browser code. |
| X-AdQuest-Participant-Token | Rewards routes and every quest action: start, view, click, visit, question, progress, events, referrals, metrics, growth-status, complete (required); quest list, detail and stats (optional) | The participant token your backend got from a participant session. It is the participant's identity: a body external_user_id is optional and must match it. The public API key alone can no longer start or complete quests. |
| X-AdQuest-Platform-Secret | Participant sessions and winner contact (backend only) | Your Secret Key (aqs_). Never expose it. |
| X-AdQuest-Runtime | Optional | JSON describing the SDK runtime capabilities, such as {"runtime_version":1,"capabilities":["quests"]}. |
| X-Timezone | Optional | IANA timezone of the participant, such as Asia/Tehran. |
Response format
Response envelope
{
"status": true,
"code": "OK",
"message": "Human-readable result",
"data": {}
}- status is true when the request succeeded. Check it as well as the HTTP status.
- code is OK on success. On failure it is an error code you can match on. See Errors. Lottery, claim and config routes omit the top-level code. Read data.code for their error code.
- data holds the result. Validation errors (HTTP 422) list each failing field in data.
- Request fields and response fields are snake_case. The SDK converts them to camelCase.
Rate limits
Requests are limited per minute. When you go over, the API answers HTTP 429. Back off and retry later instead of retrying in a loop.
| Scope | Limit |
|---|---|
| Most routes | 300 a minute per participant token, or per API key and IP address. 120 a minute per IP address when no credentials are sent. |
| Create a participant session | 60 a minute. |
| Enter a lottery | 60 a minute. |
| Submit a claim | 30 a minute. |
| Winner contact, streak callback | 60 a minute. |
| Acknowledge a fulfillment | 120 a minute. |
| Public config | 240 a minute per IP address. |
Idempotency
Retry only with the same key, so a repeated request never pays twice.
| Route | How |
|---|---|
| Enter a lottery | idempotency_key in the body, unique for each purchase attempt. |
| Complete a quest | Idempotency-Key header. A repeated key returns the earlier completion. |
| Streak callback | Optional Idempotency-Key header. |
| Acknowledge a fulfillment | The same external_reference is safe to repeat. A different one returns 409. |
| Send an event | event_id. A repeated ID returns duplicate: true. |
Pagination
List routes take per_page and page. Lotteries return a pagination object with current_page, last_page, per_page and total. Balance history returns a paginated list in the same style.
Resources
Participant sessionsCreate the token a user needs to take part.QuestsList quests, start them, record views and clicks.Quest actionsSend evidence and complete a quest.RewardsBalance, lotteries, entries and claims.PlatformPublic configuration and branding.Server routesWinner contact, fulfillments and streak callbacks.Webhook eventsHeaders, signatures, retries and payloads.ErrorsEvery error code and what to check.Bridge messagesMessages between your page or app and the hosted embed.