The document describes how third-party integrations (BI systems, scripts, dashboards) can authenticate and retrieve statistics data through the platform's public HTTP API.

Base URL: https://adset.pro (production). Swagger UI: https://adset.pro/api/docs (OpenAPI 3.0).

---

TL;DR (checklist)

1. In the UI cabinet (section API keys) create a PAT (Personal Access Token). Copy the token immediately — it is shown only once.

2. Pass the token in each request header Authorization: Bearer <token>.

3. All public statistics endpoints live under the prefix /api/stats/**.

4. The request body for /api/stats/query is StatsQueryDto (see below).

5. The scopes of the PAT are divided: api:stats (read), api:stats:export (CSV export), api:stats:meta (dictionaries).

6. An alternative to PAT is OAuth 2.0 (Authorization Code + PKCE) via /oauth/authorize → /api/oauth/token. Discovery: /.well-known/oauth-authorization-server.

---

1. Authentication

1.1 Personal Access Token (PAT) — recommended for scripts

Token prefix: pat_… (~64 characters). Suitable for server integrations and curl.

Usage

curl -X POST 'https://adset.pro/api/stats/meta/metrics' \
  -H 'Authorization: Bearer pat_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

The prefix pat_ is accepted only on paths /api/*. A separate key of type mcp (prefix mcp_) is needed on /mcp.

1.2 OAuth 2.0 (Authorization Code + PKCE) — for applications

OAuth tokens oat_ are accepted both on /api/* and on /mcp.

1.3 API access scopes

Effective rights = token scopes ∩ RBAC role of the owner user. BUYER sees only their statistics, TEAM_LEAD — team statistics according to resourceAccess rules, etc.

1.4 Standard authorization errors

---

2. Public API statistics endpoints

The base prefix is /api/stats. The request bodies are JSON, responses are application/json (or text/csv for export).

2.1 POST /api/stats/query

Request body (StatsQueryDto):

{
  "time": {
    "preset": "last7",        // OR from/to
    "from":  "2026-05-01 00:00:00",
    "to":    "2026-05-20 23:59:59",
    "timezone": "UTC"
  },
  "groups":  ["day", "cmp_campaign"],     // see Section 5
  "metrics": ["clicks", "cpa_accept", "revenue", "roi"],
  "filters": [
    { "field": "user_country", "op": "in",  "value": ["US", "CA"] },
    { "field": "cmp_offer",    "op": "eq",  "value": "65f0…" }
  ],
  "pagination": { "page": 1, "limit": 100 },
  "sort": { "field": "clicks", "order": "desc" },
  "attributionWindow": { "hours": 24, "eventType": "click" }
}

Rules

• time is required; you must pass either preset, or from (optionally with to).

• groups — an array of keys from the grouping table (see section 5). An empty array → aggregate "total".

• metrics — an array of metric keys from section 6. Defaults to `[

[!] Перевод выполнен с усечением исходника — проверьте оригинал.