Skip to documentation
AdQuestDocs

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.io/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

HeaderUsed onValue
X-AdQuest-Platform-KeyEvery /platform route except public-configYour public API key (aqk_). Safe in browser code.
X-AdQuest-Participant-TokenRewards routes and every quest action: start, view, click, visit, question, answer, progress, growth-status, complete, completion, review, execution, steps and step evidence (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-SecretParticipant sessions, winner contact and every /server route (backend only)Your Secret Key (aqs_). Never expose it.
X-AdQuest-SignatureAny /server route, optional (backend only)t=<unix seconds>,v1=<hex HMAC-SHA256 of t + "." + raw body> with your Event signing secret, sent with X-AdQuest-Platform-Key. An alternative to X-AdQuest-Platform-Secret.
X-AdQuest-Preview-TokenOptional, Theme Studio previewsA preview token for this platform. It is honoured only while the platform is not yet approved or is inactive: it then lets the request through instead of 403. On an approved, active platform it is ignored.
X-AdQuest-Reservation, X-AdQuest-Delivery-TokenQuest actions after start, optionalThe reservation id and delivery token the start returned. They name the attempt the request belongs to. The SDK sends them for you.
X-AdQuest-RuntimeOptionalJSON describing the SDK runtime capabilities, such as {"runtime_version":1,"capabilities":["quests"]}.
X-TimezoneOptionalIANA 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.

ScopeLimit
Most routes300 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 sessionNo request limit. 60 failed Secret Keys a minute per IP address, then 429.
Enter a lottery60 a minute.
Submit a claim30 a minute.
Winner contact60 a minute.
Acknowledge a fulfillmentThe Most routes limit: 300 a minute per API key and IP address when you send X-AdQuest-Platform-Key, otherwise 120 a minute per IP address.
Public config240 a minute per IP address.

Idempotency

Retry only with the same key, so a repeated request never pays twice.

RouteHow
Enter a lotteryidempotency_key in the body, unique for each purchase attempt.
Complete a questIdempotency-Key header. A repeated key returns the earlier completion.
Acknowledge or reject a fulfillmentThe same answer is safe to repeat. A different one returns 409 FULFILLMENT_CONFLICT.
Report activitiesEach fact’s id. A repeated id is answered duplicate and changes nothing.

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

Something unclear, missing or wrong here? Tell us