Zum Hauptinhalt springen
Public API v1

Steuere Hideads aus deinen eigenen Tools.

Erstelle Tracker, rufe Statistiken ab und teile Reports per HTTPS — dieselben Aktionen wie im Portal, aus deinen Skripten, deinem CRM oder deinem KI-Agenten.

Basis-URL: https://api.hideads.app/v1

API-Schlüssel erstellen JSON herunterladen

Dein erster Aufruf in drei Schritten

1

Schlüssel erstellen

Öffne im Portal die API-Schlüssel und erstelle einen Schlüssel mit den Scopes, die du brauchst.

2

Als Bearer-Token senden

Jede Anfrage enthält Authorization: Bearer hd_live_…. Partner-Schlüssel senden zusätzlich X-Customer-Id.

3

API aufrufen

Starte mit GET /v1/me, um deinen Tarif und dein Kontingent zu sehen. Limit: 60 Anfragen pro Minute und Schlüssel.

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

Endpunkte

Direkt aus der OpenAPI-Spec generiert — diese Liste entspricht also immer der Live-API.

GET /v1/me — Who am I + plan + quota · Jeder Schlüssel

Parameter
X-Customer-Id · header · integer · optional — 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.

Antworten
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

Parameter
X-Customer-Id · header · integer · optional — 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.

Antworten
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) · Jeder Schlüssel

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

Antworten
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

Parameter
X-Customer-Id · header · integer · optional — 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.

Request-Body
money_url · string · Pflicht
name · string · optional — Omitted → auto name
apex_id · integer · optional — From /v1/apexes; omitted → weighted pick
safe_page_language · string · optional
safe_page_niche · string · optional

Antworten
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) · Jeder Schlüssel

Parameter
id · path · integer · Pflicht
X-Customer-Id · header · integer · optional — 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.

Antworten
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

Parameter
id · path · integer · Pflicht
X-Customer-Id · header · integer · optional — 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.

Request-Body
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 · optional

Antworten
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

Parameter
id · path · integer · Pflicht
X-Customer-Id · header · integer · optional — 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.

Antworten
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

Parameter
id · path · integer · Pflicht
X-Customer-Id · header · integer · optional — 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 · optional

Antworten
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

Parameter
X-Customer-Id · header · integer · optional — 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.

Request-Body
tracker_id · integer · optional
expiry_days · integer: 7 | 30 | 60 · optional
label · string · optional

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

Funktioniert mit Claude und Codex

Füge die Spec-URL in deinen KI-Agenten ein und lass ihn die Integration für dich schreiben.

API-Zugang ist in den Tarifen enthalten, die „Zugang zur Public API“ aufführen. Preise ansehen.

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