API overview

Everything ReTarget.gg does is driven by its public REST API. The widget calls it. Your dashboard calls it. You can too: for server-rendered offers, custom UIs, server-to-server integrations, or automation.

For the full interactive reference with request/response schemas, see /docs/api which is powered by our OpenAPI spec and lets you try requests directly from the browser.

Base URL

https://api.retarget.gg

All endpoints are versioned under /v1/. We never remove or change a /v1/ response shape; breaking changes ship under /v2/ when they're needed.

Authentication

Two distinct modes depending on what you're calling:

Widget / public endpoints: Public key + Origin

Endpoints called from the browser authenticate with:

• Your public key (pk_…) passed in the URL as ?pub=.
• Your website key (web_…) passed as ?website=.
• The browser's Origin header, which must match the domain registered on the website.

No Authorization header needed. The widget handles this automatically when you pass data-pub and data-website.

Server / private endpoints: Integration secret bearer

Server-to-server endpoints (today: POST /v1/widget-decline/trigger) authenticate with:

Authorization: Bearer its_your_integration_secret

Integration secrets (its_…) are generated per website from the website's Trigger Widget settings in the dashboard. Each secret is scoped to one website. Revoke and rotate at will without affecting other sites.

Request format

• Method + path: standard REST. Decision and offers use GET with query parameters; events and triggers use POST with JSON bodies.
• Content-Type: application/json works on every POST. The widget uses text/plain for /v1/events/* so the browser skips the CORS preflight: the API parses both.
• Origin: required on browser calls; must match the website's registered domain.

Response format

• 2xx: success. JSON body shape documented per endpoint.
• 204 No Content: success with no body. Used by /v1/events/impression, /v1/events/click, /v1/events/snippet-ping.
• 4xx: client error. Body: { "error": "human-readable message" } (plus occasionally a short machine-readable reason). Status 400 = bad request, 401 = auth missing, 403 = auth invalid or origin not allowed, 404 = resource not found, 429 = rate-limited.
• 5xx: our problem. Include a recent response body in your support ticket.

GET /v1/decision and GET /v1/offers set Cache-Control: no-store: decisions and offer lists are per-request.

Rate limits

Rate limits are applied per source IP over a 60-second rolling window:

Rate-limited requests return 429 Too Many Requests with standard rate-limit response headers. If you hit a limit in production, reach out and we'll look at it.

Endpoint groups

SDK?

Not yet. The API is small enough that a plain fetch or any HTTP client works well. If you'd like an official SDK in a specific language, let us know: we prioritize based on request volume.

Community SDKs (none official) may exist on npm or PyPI; we don't certify those.

Versioning

All endpoints live under /v1/. Breaking changes would ship under a new major (/v2/) with a deprecation window communicated via email. Non-breaking additions (new fields, new endpoints) land continuously: you don't need to do anything for those.

Related