Перейти к основному содержимому
Public API v1

Управляйте Hideads из своих инструментов.

Создавайте трекеры, получайте статистику и делитесь отчётами по HTTPS — те же действия, что и в портале, но из ваших скриптов, CRM или AI-агента.

Базовый URL: https://api.hideads.app/v1

Получить API-ключ Скачать JSON

Первый запрос за три шага

1

Создайте ключ

В портале откройте раздел API-ключей и создайте ключ с нужными вам правами (scopes).

2

Передайте его как Bearer-токен

Каждый запрос содержит Authorization: Bearer hd_live_…. Партнёрские ключи также передают X-Customer-Id.

3

Вызовите API

Начните с GET /v1/me, чтобы увидеть свой тариф и квоту. Лимит: 60 запросов в минуту на ключ.

curl -H "Authorization: Bearer hd_live_…" https://api.hideads.app/v1/me

Эндпоинты

Список генерируется из спецификации OpenAPI, поэтому всегда совпадает с рабочим API.

GET /v1/me — Who am I + plan + quota · Любой ключ

Параметры
X-Customer-Id · header · integer · необязательно — Partner keys: REQUIRED on every customer-scoped route (trackers, stats, share-links) — the customer must belong to your partner (400 E_API_CUSTOMER_REQUIRED when missing, 403 E_API_CUSTOMER_SCOPE when outside your book). Customer keys: ignored.

Ответы
200 ok
401 E_API_UNAUTHORIZED
429 E_API_RATE_LIMITED

curl https://api.hideads.app/v1/me \
  -H "Authorization: Bearer hd_live_…"
GET /v1/apexes — Apexes you may provision onto · Права: trackers:r

Параметры
X-Customer-Id · header · integer · необязательно — Partner keys: REQUIRED on every customer-scoped route (trackers, stats, share-links) — the customer must belong to your partner (400 E_API_CUSTOMER_REQUIRED when missing, 403 E_API_CUSTOMER_SCOPE when outside your book). Customer keys: ignored.

Ответы
200 ok
400 E_API_CUSTOMER_REQUIRED
401 E_API_UNAUTHORIZED
403 E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)

curl https://api.hideads.app/v1/apexes \
  -H "Authorization: Bearer hd_live_…"
GET /v1/trackers — List trackers (keyset, 50/page) · Любой ключ

Параметры
X-Customer-Id · header · integer · необязательно — Partner keys: REQUIRED on every customer-scoped route (trackers, stats, share-links) — the customer must belong to your partner (400 E_API_CUSTOMER_REQUIRED when missing, 403 E_API_CUSTOMER_SCOPE when outside your book). Customer keys: ignored.
status · query · string: active | pending | paused | disabled | deleted · необязательно
cursor · query · integer · необязательно — Last id of the previous page (next_cursor).

Ответы
200 ok
400 E_API_BAD_REQUEST (bad status) / E_API_CUSTOMER_REQUIRED
401 E_API_UNAUTHORIZED
403 E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)

curl https://api.hideads.app/v1/trackers \
  -H "Authorization: Bearer hd_live_…"
POST /v1/trackers — Create tracker · Права: trackers:rw

Параметры
X-Customer-Id · header · integer · необязательно — Partner keys: REQUIRED on every customer-scoped route (trackers, stats, share-links) — the customer must belong to your partner (400 E_API_CUSTOMER_REQUIRED when missing, 403 E_API_CUSTOMER_SCOPE when outside your book). Customer keys: ignored.

Тело запроса
money_url · string · обязательно
name · string · необязательно — Omitted → auto name
apex_id · integer · необязательно — From /v1/apexes; omitted → weighted pick
safe_page_language · string · необязательно
safe_page_niche · string · необязательно

Ответы
201 active — data.cloak_url ready to use
202 pending — data.no_apex or data.blocked_reasons; poll GET /trackers/{id}
400 E_API_BAD_REQUEST (issues[]) / E_API_CUSTOMER_REQUIRED
402 E_QUOTA_EXCEEDED (quota{}) or E_API_TRIAL_EXPIRED
403 E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)
409 E_APEX_UNAVAILABLE
429 E_API_RATE_LIMITED (10 creates/min per customer)
500 E_API_CREATE_FAILED — nothing persisted, retry

curl -X POST https://api.hideads.app/v1/trackers \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{"money_url":"https://example.com/offer"}'
GET /v1/trackers/{id} — Get one tracker (reads primary) · Любой ключ

Параметры
id · path · integer · обязательно
X-Customer-Id · header · integer · необязательно — Partner keys: REQUIRED on every customer-scoped route (trackers, stats, share-links) — the customer must belong to your partner (400 E_API_CUSTOMER_REQUIRED when missing, 403 E_API_CUSTOMER_SCOPE when outside your book). Customer keys: ignored.

Ответы
200 ok
400 E_API_CUSTOMER_REQUIRED
403 E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)
404 E_API_NOT_FOUND (also when outside your scope)

curl https://api.hideads.app/v1/trackers/123 \
  -H "Authorization: Bearer hd_live_…"
PATCH /v1/trackers/{id} — Update any subset of fields · Права: trackers:rw

Параметры
id · path · integer · обязательно
X-Customer-Id · header · integer · необязательно — Partner keys: REQUIRED on every customer-scoped route (trackers, stats, share-links) — the customer must belong to your partner (400 E_API_CUSTOMER_REQUIRED when missing, 403 E_API_CUSTOMER_SCOPE when outside your book). Customer keys: ignored.

Тело запроса
Any subset of: name, money_url, safe_url, redirect_type(301|302|307), shield_preset(standard|advanced), fb_pixel_id, fb_access_token, fb_test_event_code, tt_pixel_code, tt_access_token, tt_test_event_code, target_country (CSV ISO-2 allow), target_device[], target_os[], target_client[], target_language (CSV block), target_referer_regex, target_url_param, target_ua_regex, target_ip_cidrs, target_isp_keywords, safe_page_language, safe_page_theme, safe_page_niche, safe_page_custom_notice, repeat_visitor_state(off|active), repeat_visitor_window_min, repeat_visitor_max_visits, click_capi ({ fb?: { state?, event? }, tt?: { state?, event? } } — click events only; Lead / Purchase / TikTok ViewContent are 400). Omitted fields keep their current value; tokens are never returned.
click_capi · ClickCapi · необязательно

Ответы
200 { id, updated_at, bridge_failed } — bridge_failed:true = saved in DB but edge sync failed; retry the PATCH later
400 E_API_BAD_REQUEST / E_API_CUSTOMER_REQUIRED
403 E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan | shield_preset_not_in_plan | click_capi_not_in_plan)
404 E_API_NOT_FOUND
409 E_SAFE_URL_FALLBACK_REQUIRED — cannot clear safe_url without an inline safe page

curl -X PATCH https://api.hideads.app/v1/trackers/123 \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
DELETE /v1/trackers/{id} — Delete tracker. Cloak link drains 24h then retires; clicks/conversions wiped; not restorable. · Права: trackers:rw

Параметры
id · path · integer · обязательно
X-Customer-Id · header · integer · необязательно — Partner keys: REQUIRED on every customer-scoped route (trackers, stats, share-links) — the customer must belong to your partner (400 E_API_CUSTOMER_REQUIRED when missing, 403 E_API_CUSTOMER_SCOPE when outside your book). Customer keys: ignored.

Ответы
200 { id, detached, already_deleted }
400 E_API_CUSTOMER_REQUIRED
403 E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)
404 E_API_NOT_FOUND
502 E_DETACH_FAILED (failed[].cloak_link_id) — edge detach failed, nothing changed; retry later

curl -X DELETE https://api.hideads.app/v1/trackers/123 \
  -H "Authorization: Bearer hd_live_…"
GET /v1/trackers/{id}/stats — Tracker stats · Права: stats:r

Параметры
id · path · integer · обязательно
X-Customer-Id · header · integer · необязательно — Partner keys: REQUIRED on every customer-scoped route (trackers, stats, share-links) — the customer must belong to your partner (400 E_API_CUSTOMER_REQUIRED when missing, 403 E_API_CUSTOMER_SCOPE when outside your book). Customer keys: ignored.
range · query · string: 24h | 7d | 30d · необязательно

Ответы
200 { tracker_id, range, since, real_visitors, shield_hits, human_rate_pct, top_country, top_device, top_block_reason } — human_rate_pct = real visitors ÷ all visits; since is the first second counted (unix seconds); for 30d it is 00:00 UTC of the first day
400 E_API_BAD_REQUEST (bad range) / E_API_CUSTOMER_REQUIRED
403 E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)
404 E_API_NOT_FOUND

curl https://api.hideads.app/v1/trackers/123/stats \
  -H "Authorization: Bearer hd_live_…"
POST /v1/share-links — Create public read-only report link · Права: share:rw

Параметры
X-Customer-Id · header · integer · необязательно — Partner keys: REQUIRED on every customer-scoped route (trackers, stats, share-links) — the customer must belong to your partner (400 E_API_CUSTOMER_REQUIRED when missing, 403 E_API_CUSTOMER_SCOPE when outside your book). Customer keys: ignored.

Тело запроса
tracker_id · integer · необязательно
expiry_days · integer: 7 | 30 | 60 · необязательно
label · string · необязательно

Ответы
201 { id, url, tracker_id, expires_at }
400 E_API_BAD_REQUEST / E_API_CUSTOMER_REQUIRED
403 E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)
404 E_API_NOT_FOUND — tracker outside scope

curl -X POST https://api.hideads.app/v1/share-links \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Работает с Claude и Codex

Вставьте URL спецификации в своего AI-агента — и он сам напишет интеграцию.

Доступ к API входит в тарифы, где указан доступ к Public API. Смотреть тарифы.

https://api.hideads.app/openapi.json