Public HTTP API

The Adset.pro public HTTP API gives external systems programmatic access to the data and entities of your account: BI tools and dashboards, ETL scripts, and automation that creates campaigns, affiliate networks, offers and flows.

Base URL: https://adset.pro. Swagger UI: https://adset.pro/api/docs (OpenAPI 3.0; JSON spec — https://adset.pro/api/docs/swagger.json).

The public API consists of the same endpoints the web cabinet uses: there is no separate /api/public/* layer. Request and response fields match what the UI shows, and data visibility is the same as in the cabinet. The articles in this section list the required and key fields; full schemas are in Swagger.

Articles in this section

Quick start

1. In the cabinet open User settings → the "MCP keys" tab (https://adset.pro/user-settings), click "Create API key" and choose the Personal Access Token type. Copy the token right away — it is shown only once.
2. Send the token with every request in the Authorization: Bearer pat_… header.
3. Check access with a catalog request:

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

4. Entity lists are paginated on the server: GET /api/campaigns?page=1&pageSize=100.
5. To create or edit entities, add write scopes to the key — a new PAT is read-only by default.

Getting a token

Personal Access Token (PAT)

The primary option for scripts and server-side integrations. The token prefix is pat_, the length is about 64 characters.

A key is created in the UI (see "Quick start") or with a request from the cabinet — it requires the browser session JWT, not another PAT:

POST /api/mcp/keys
Authorization: Bearer <cabinet session JWT>
Content-Type: application/json

{
  "type": "pat",
  "name": "BI ETL job",
  "scopes": ["api:stats", "api:stats:meta", "api:campaigns"],
  "expiresInDays": 365
}

The response returns the token field once — store it.

Key management (from the cabinet; a user sees only their own keys):

All of these actions are also available in the UI on the "MCP keys" tab.

pat_ is accepted only on /api/* paths. It is rejected on /mcp — that endpoint needs an MCP key (mcp_) or an OAuth token, see MCP Service Adset.

OAuth 2.0 (for applications)

OAuth tokens (oat_…, Authorization Code + PKCE) are also accepted on /api/* with the same scopes. This flow exists primarily to connect MCP clients (ChatGPT, Claude and compatible tools) and is described in MCP Service Adset. Discovery document: GET /.well-known/oauth-authorization-server. For scripts and server-side integrations use a PAT.

Scopes

A scope is the token's own permission to call a group of endpoints. Effective access = token scopes ∩ the permissions of the token owner's role.

• A new PAT without an explicit scopes list gets all read scopes. Write scopes are enabled when the key is created or later — via the UI or PATCH /api/mcp/keys/{keyId}/scopes.
• Previously issued keys do not receive new scopes automatically: add them the same way.
• No scope grants deletion — entities cannot be deleted through the API.

Permissions of the token owner's role

A token acts on behalf of the user who created it and inherits their role and data visibility:

All roles can read and create/edit campaigns, offers and flows, create CPA networks, and read domains, CPA templates and statistics. The single exception: BUYER cannot edit CPA networks — PATCH /api/cpa/{id} returns 403. An entity of another team or user does not exist for the token: the response is 404, not 403.

Common conventions

Request and response format

• JSON, UTF-8, Content-Type: application/json. Dates are ISO 8601 in UTC. {id} identifiers are 24-character hex ObjectIds.
• Single object: { "data": { … }, "traceId": "…" }.
• List: { "data": [ … ], "meta": { "page", "pageSize", "total", "sort", "filters" }, "links": { "self", "next"?, "prev"? }, "traceId": "…" }.
• Creation — 201 Created with a Location: /<resource>/{id} header; editing — 200 OK with the full object.
• Every response contains traceId and the X-Trace-Id header — quote it when contacting support.

List parameters (GET …)

A single contract for all entity lists. The allowed filter and sort fields differ per entity — they are listed in each group's article.

curl -G 'https://adset.pro/api/offers' \
  -H 'Authorization: Bearer pat_…' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=100' \
  --data-urlencode 'sort=updated:desc' \
  --data-urlencode 'filter[isActive]=true' \
  --data-urlencode 'filter[country][in]=DE,AT'

meta.total is the total number of records; the last page has no next in links. If you need a full catalog, request it page by page or pass pageSize up to 1000.

Errors

The error body is uniform: { "error": { "code": "…", "message": "…", "details": [ … ] }, "traceId": "…" } (details lists per-field violations and is not always present).

On /mcp, authorization errors use the OAuth format ({ "error": "invalid_token", … }); on /api/* the format is always as in the table.

Limits

Recommendations: cache catalogs (/api/stats/meta/*, CPA templates), request only the fields you need (select), and retry with exponential backoff on 429.

What is not part of the public API

Deleting entities, copying (/copy, /clone), bulk operations (/reassign-owner, /replace-domain), server-side tables (/table), /free-list, a campaign's domain list, the domain registration wizard and domain purchase, Cloudflare operations, creating and editing CPA templates and domains. These endpoints have no scope, are not published in /api/docs, and their contract is not guaranteed and may change without notice. Do not use them from integrations — PAT/OAuth access to them will be closed.

Useful links

• Swagger UI: https://adset.pro/api/docs
• MCP Service Adset — LLM client access to data via the Model Context Protocol and OAuth 2.0
• Report Builder — the same metrics and groupings in the cabinet UI