Pular para o conteúdo principal
API pública v1

Automatize a Hideads nas suas próprias ferramentas.

Crie trackers, consulte estatísticas e compartilhe relatórios via HTTPS — as mesmas ações do portal, a partir dos seus scripts, do seu CRM ou do seu agente de IA.

URL base: https://api.hideads.app/v1

Gerar uma chave de API Baixar JSON

Sua primeira chamada em três passos

1

Crie uma chave

No portal, abra Chaves de API e crie uma chave com os escopos de que você precisa.

2

Envie como token Bearer

Toda requisição leva Authorization: Bearer hd_live_…. Chaves de parceiro também enviam X-Customer-Id.

3

Chame a API

Comece com GET /v1/me para ver seu plano e sua cota. Limite: 60 requisições por minuto por chave.

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

Endpoints

Gerada a partir da spec OpenAPI, então esta lista sempre corresponde à API em produção.

GET /v1/me — Who am I + plan + quota · Qualquer chave

Parâmetros
X-Customer-Id · header · integer · opcional — 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.

Respostas
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 · Escopo: trackers:r

Parâmetros
X-Customer-Id · header · integer · opcional — 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.

Respostas
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) · Qualquer chave

Parâmetros
X-Customer-Id · header · integer · opcional — 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 · opcional
cursor · query · integer · opcional — Last id of the previous page (next_cursor).

Respostas
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 · Escopo: trackers:rw

Parâmetros
X-Customer-Id · header · integer · opcional — 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.

Corpo da requisição
money_url · string · obrigatório
name · string · opcional — Omitted → auto name
apex_id · integer · opcional — From /v1/apexes; omitted → weighted pick
safe_page_language · string · opcional
safe_page_niche · string · opcional

Respostas
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) · Qualquer chave

Parâmetros
id · path · integer · obrigatório
X-Customer-Id · header · integer · opcional — 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.

Respostas
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 · Escopo: trackers:rw

Parâmetros
id · path · integer · obrigatório
X-Customer-Id · header · integer · opcional — 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.

Corpo da requisição
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 · opcional

Respostas
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. · Escopo: trackers:rw

Parâmetros
id · path · integer · obrigatório
X-Customer-Id · header · integer · opcional — 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.

Respostas
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 · Escopo: stats:r

Parâmetros
id · path · integer · obrigatório
X-Customer-Id · header · integer · opcional — 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 · opcional

Respostas
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 · Escopo: share:rw

Parâmetros
X-Customer-Id · header · integer · opcional — 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.

Corpo da requisição
tracker_id · integer · opcional
expiry_days · integer: 7 | 30 | 60 · opcional
label · string · opcional

Respostas
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 '{}'

Funciona com Claude e Codex

Cole a URL da spec no seu agente de IA e deixe que ele escreva a integração para você.

O acesso à API está incluído nos planos que listam Acesso à API pública. Ver preços.

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