API overview

Everything AffilFinder 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.affilfinder.com

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 decline 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