Saltar al contenido principal
API pública v1

Automatiza Hideads desde tus propias herramientas.

Crea trackers, consulta estadísticas y comparte reportes por HTTPS: las mismas acciones que en el portal, desde tus scripts, tu CRM o tu agente de IA.

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

Obtén una clave API Descargar JSON

Tu primera llamada en tres pasos

1

Crea una clave

En el portal, abre Claves API y crea una clave con los scopes que necesites.

2

Envíala como token Bearer

Cada solicitud lleva Authorization: Bearer hd_live_…. Las claves de partner también envían X-Customer-Id.

3

Llama a la API

Empieza con GET /v1/me para ver tu plan y tu cuota. Límite: 60 solicitudes por minuto por clave.

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

Endpoints

Se genera a partir de la spec OpenAPI, así que esta lista siempre coincide con la API en vivo.

GET /v1/me — Who am I + plan + quota · Cualquier clave

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.

Respuestas
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 · Scope: 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.

Respuestas
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) · Cualquier clave

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).

Respuestas
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 · Scope: 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.

Cuerpo de la solicitud
money_url · string · obligatorio
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

Respuestas
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) · Cualquier clave

Parámetros
id · path · integer · obligatorio
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.

Respuestas
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 · Scope: trackers:rw

Parámetros
id · path · integer · obligatorio
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.

Cuerpo de la solicitud
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

Respuestas
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. · Scope: trackers:rw

Parámetros
id · path · integer · obligatorio
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.

Respuestas
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 · Scope: stats:r

Parámetros
id · path · integer · obligatorio
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

Respuestas
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 · Scope: 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.

Cuerpo de la solicitud
tracker_id · integer · opcional
expiry_days · integer: 7 | 30 | 60 · opcional
label · string · opcional

Respuestas
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 con Claude y Codex

Pega la URL de la spec en tu agente de IA y deja que escriba la integración por ti.

El acceso a la API está incluido en los planes que muestran Acceso a la API pública. Ver precios.

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