# API reference

> Base URL, authentication, headers and response format shared by every public AdQuest route.

Source: https://dashboard.adquest.batriders.ir/docs/api-reference · Audience: Developers · Section: API reference

## Base URL

**Base URL**

```env
ADQUEST_API_URL=https://api.adquest.batriders.ir/api/v1
```

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

- [Authentication guide](https://dashboard.adquest.batriders.ir/docs/authentication): Which credential goes where, with examples.

## Response format

**Response envelope**

```json
{
  "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 sessions](https://dashboard.adquest.batriders.ir/docs/api/participant-sessions): Create the token a user needs to take part.
- [Quests](https://dashboard.adquest.batriders.ir/docs/api/quests): List quests, start them, record views and clicks.
- [Quest actions](https://dashboard.adquest.batriders.ir/docs/api/quest-actions): Send evidence and complete a quest.
- [Rewards](https://dashboard.adquest.batriders.ir/docs/api/rewards): Balance, lotteries, entries and claims.
- [Platform](https://dashboard.adquest.batriders.ir/docs/api/platform): Public configuration and branding.
- [Server routes](https://dashboard.adquest.batriders.ir/docs/api/server-routes): Winner contact, fulfillments and streak callbacks.
- [Webhook events](https://dashboard.adquest.batriders.ir/docs/api/webhook-events): Headers, signatures, retries and payloads.
- [Errors](https://dashboard.adquest.batriders.ir/docs/errors): Every error code and what to check.
- [Bridge messages](https://dashboard.adquest.batriders.ir/docs/bridge-messages): Messages between your page or app and the hosted embed.