{"openapi":"3.0.3","info":{"title":"Hideads Public API","version":"1.0.0","description":"Automate trackers, stats and share links. Auth: `Authorization: Bearer hd_live_…` (create keys in the portal → API keys; requires a plan with API access — `GET /me` reports `plan.api_enabled`, every other route answers `403 E_API_PLAN_FORBIDDEN api_not_in_plan` otherwise). Partner keys must send `X-Customer-Id`; the gate then uses that customer's plan. Every auth failure is `401` with the same body. Rate limit 60 req/min per key (`429` + `Retry-After`). An unexpected server failure on any route is `500 E_API_INTERNAL` with an `err_id` to quote to support."},"servers":[{"url":"https://api.hideads.app"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"hd_live_<43 base64url chars>"}},"parameters":{"customerId":{"name":"X-Customer-Id","in":"header","required":false,"schema":{"type":"integer"},"description":"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."},"id":{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}},"schemas":{"Error":{"type":"object","required":["ok","error","code"],"properties":{"ok":{"const":false},"error":{"type":"string"},"code":{"type":"string","pattern":"^E_"}}},"Tracker":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["active","pending","paused","disabled","deleted"]},"money_url":{"type":"string","nullable":true},"click_capi":{"$ref":"#/components/schemas/ClickCapi"},"cloak":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"url":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string"},"dns_status":{"type":"string","nullable":true},"safe_page":{"type":"string","enum":["inline","url","none"]}}},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"ClickCapi":{"type":"object","description":"Send a server-side event to the tracker's Facebook / TikTok pixel on every real click (BETA). Only state + event; access tokens are never returned. Turning a platform on needs a plan with click events (else `403 E_API_PLAN_FORBIDDEN click_capi_not_in_plan`); `on` without a Pixel ID + access token is saved but sends nothing.","properties":{"fb":{"type":"object","properties":{"state":{"type":"string","enum":["off","on"]},"event":{"type":"string","enum":["ViewContent","PageView","Contact","Search","FindLocation","CustomizeProduct","AddToWishlist"]}}},"tt":{"type":"object","properties":{"state":{"type":"string","enum":["off","on"]},"event":{"type":"string","enum":["ClickButton","Contact","Download","AddToWishlist"]}}}}}}},"paths":{"/v1/me":{"get":{"summary":"Who am I + plan + quota","parameters":[{"$ref":"#/components/parameters/customerId"}],"responses":{"200":{"description":"ok"},"401":{"description":"E_API_UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"E_API_RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/apexes":{"get":{"summary":"Apexes you may provision onto (scopes: trackers:r)","parameters":[{"$ref":"#/components/parameters/customerId"}],"responses":{"200":{"description":"ok"},"400":{"description":"E_API_CUSTOMER_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"E_API_UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trackers":{"get":{"summary":"List trackers (keyset, 50/page)","parameters":[{"$ref":"#/components/parameters/customerId"},{"name":"status","in":"query","schema":{"type":"string","enum":["active","pending","paused","disabled","deleted"],"default":"active"}},{"name":"cursor","in":"query","schema":{"type":"integer"},"description":"Last id of the previous page (`next_cursor`)."}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Tracker"}},"next_cursor":{"type":"integer","nullable":true}}}}}},"400":{"description":"E_API_BAD_REQUEST (bad status) / E_API_CUSTOMER_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"E_API_UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create tracker (scopes: trackers:rw)","parameters":[{"$ref":"#/components/parameters/customerId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["money_url"],"properties":{"money_url":{"type":"string","format":"uri"},"name":{"type":"string","maxLength":80,"description":"Omitted → auto name"},"apex_id":{"type":"integer","description":"From /v1/apexes; omitted → weighted pick"},"safe_page_language":{"type":"string","default":"en"},"safe_page_niche":{"type":"string"}}}}}},"responses":{"201":{"description":"active — `data.cloak_url` ready to use"},"202":{"description":"pending — `data.no_apex` or `data.blocked_reasons`; poll GET /trackers/{id}"},"400":{"description":"E_API_BAD_REQUEST (issues[]) / E_API_CUSTOMER_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"E_QUOTA_EXCEEDED (quota{}) or E_API_TRIAL_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"E_APEX_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"E_API_RATE_LIMITED (10 creates/min per customer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"E_API_CREATE_FAILED — nothing persisted, retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trackers/{id}":{"get":{"summary":"Get one tracker (reads primary)","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/customerId"}],"responses":{"200":{"description":"ok"},"400":{"description":"E_API_CUSTOMER_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"E_API_NOT_FOUND (also when outside your scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update any subset of fields (scopes: trackers:rw)","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/customerId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"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.","properties":{"click_capi":{"$ref":"#/components/schemas/ClickCapi"}},"additionalProperties":true}}}},"responses":{"200":{"description":"`{ id, updated_at, bridge_failed }` — `bridge_failed:true` = saved in DB but edge sync failed; retry the PATCH later"},"400":{"description":"E_API_BAD_REQUEST / E_API_CUSTOMER_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan | shield_preset_not_in_plan | click_capi_not_in_plan)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"E_API_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"E_SAFE_URL_FALLBACK_REQUIRED — cannot clear safe_url without an inline safe page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete tracker (scopes: trackers:rw). Cloak link drains 24h then retires; clicks/conversions wiped; not restorable.","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/customerId"}],"responses":{"200":{"description":"`{ id, detached, already_deleted }`"},"400":{"description":"E_API_CUSTOMER_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"E_API_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"E_DETACH_FAILED (`failed[].cloak_link_id`) — edge detach failed, nothing changed; retry later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trackers/{id}/stats":{"get":{"summary":"Tracker stats (scopes: stats:r)","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/customerId"},{"name":"range","in":"query","schema":{"type":"string","enum":["24h","7d","30d"],"default":"24h"}}],"responses":{"200":{"description":"`{ 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":{"description":"E_API_BAD_REQUEST (bad range) / E_API_CUSTOMER_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"E_API_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/share-links":{"post":{"summary":"Create public read-only report link (scopes: share:rw)","parameters":[{"$ref":"#/components/parameters/customerId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer"},"expiry_days":{"type":"integer","enum":[7,30,60],"default":30},"label":{"type":"string","maxLength":120}}}}}},"responses":{"201":{"description":"`{ id, url, tracker_id, expires_at }`"},"400":{"description":"E_API_BAD_REQUEST / E_API_CUSTOMER_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"E_API_SCOPE / E_API_PLAN_FORBIDDEN (api_not_in_plan)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"E_API_NOT_FOUND — tracker outside scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"x-scopes":["trackers:r","trackers:rw","stats:r","share:rw"]}