offerswap.com API
Branded short links, campaign tracking and click and page view analytics.
https://app.offerswap.com
Links https://offerswap.com/{code}
Auth Bearer bgl_...
93 endpoints
The OfferSwap API does everything the app does: short links and their stats, collections, custom domains, tracking pixels, and the campaign tracker (campaigns, offers, landers, traffic sources, postbacks, reports and site properties). Responses are JSON over HTTPS.
OfferSwap was called BuyGoLinks until 2026-11-20. Every buygolinks.com link, campaign link, /click button, t.js tag and postback URL, and every call to https://app.buygolinks.com/api/*, keeps working unchanged.
Base URLs
- API:
https://app.offerswap.com - Short links and the public tracker endpoints:
https://offerswap.com, or any custom domain the account has connected.
Authentication
Every /api/* endpoint needs Authorization: Bearer <token>. Two token shapes work:
- Personal access token,
bgl_<24 base62>. Use this for anything programmatic. Create one withPOST /api/api-keysor in the app under Account Settings, API keys. The raw token is returned exactly once; only its SHA-256 is stored. - Supabase JWT, issued to the app after sign in. Short lived, not meant for integrations.
Errors
Errors are JSON shaped { "error": "<code>" }, and many also carry a human message. Common codes: unauthorized (401), forbidden (403, it exists but is not yours), not_found (404), bad_json, invalid_url, no_changes and name_required (400), and alias_taken, slug_taken and name_taken (409). Each endpoint lists its own below.
Postbacks
Every account has one postback URL, returned as postback_url on GET /api/me. It matches the sale to the click by clickid alone and credits whichever campaign the click belongs to, so one URL serves every campaign and every network. event= says what happened: none is a sale, refund and chargeback are built in, and anything else is a custom event from /api/custom-events. See the Postback URL under Public endpoints for every parameter.
Time zones
Reports count days, weekdays and hours in the account's time zone (timezone on GET /api/me, set with PATCH /api/me). The report endpoints take ?tz= to override it for one call and echo the zone they used.
Versioning
The API is unversioned. Breaking changes are avoided, and additions (new fields, new endpoints) ship without notice. This spec is the contract.
Quickstart
# Create a personal access token (Account Settings, API keys), then:
TOKEN="bgl_..."
# Your account, including your postback URL
curl -H "Authorization: Bearer $TOKEN" https://app.offerswap.com/api/me
# Create a short link
curl -X POST https://app.offerswap.com/api/links \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"destination_url":"https://www.amazon.com/dp/B08N5WRWNW?tag=yourtag-20"}'
# Today's campaign numbers, counted in your time zone
curl -H "Authorization: Bearer $TOKEN" \
"https://app.offerswap.com/api/tracker/overview?days=1"
For AI agents
Everything here is built to be read by software as well as people.
MCP server
npx -y @offerswap/mcp with OFFERSWAP_API_KEY set. Works with Claude, Cursor, Cline, Continue, Hermes and any MCP client, and covers every endpoint on this page.
OpenAPI 3.1
The spec this page is generated from. Import it into Postman, a Custom GPT's actions or any OpenAPI tool.
/openapi.yamlAccount
The signed-in account's profile, plan usage, preferences and postback URL.
Current user profile
Profile of the signed-in user: plan, billing_period, current_period_end (next billing date), cancels_at (when a cancelled subscription ends, otherwise null), click + page-view usage meters (pageview_usage), preferences (tracker_range_days, timezone: the IANA zone reports count days and hours in, or null), and postback_url, the account's postback URL (the only one) (https://offerswap.com/postback/u/{token}), one URL that records a conversion for any click across every campaign and network.
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Update your preferences
tracker_range_days (1, 7, 14, 30 or 90) is the dashboard's default range. timezone is the IANA zone (e.g. America/New_York) that reports count days, weekdays and hours in, on every device and for API calls with no tz. null clears it. An unknown name is a 400 invalid_timezone.
Request body
| Field | Type | Notes |
|---|---|---|
| tracker_range_days | integer | One of |
| timezone | string | null | Example |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | invalid_range / invalid_timezone / no_fields |
Links
Branded short links. A link redirects to exactly the URL you saved, opening the right app on a phone when the destination belongs to one (Amazon, YouTube, Instagram and more).
/api/linksPOST /api/linksPATCH /api/links/{id}DELETE /api/links/{id}POST /api/links/{id}/refresh-imageGET /api/links/{id}/pixelsPUT /api/links/{id}/pixelsPOST /api/links/{id}/collectionGET /api/links/{id}/campaignPOST /api/links/{id}/campaignList your links
Parameters
| Name | In / type | Notes |
|---|---|---|
| include_archived | query string | Pass |
Responses
| Status | Meaning |
|---|---|
| 200 | Links with per-link click counts and current usage. |
| 401 | Missing or invalid bearer token. |
Create a short link
Request body
| Field | Type | Notes |
|---|---|---|
| destination_url required | string (uri) | Destination URL the short link redirects to (http/https only), used exactly as given. Include any affiliate tag yourself. Amazon |
| title | string | Max 200 chars. |
| source_label | string | Your own label for where the link is posted (for example |
| domain_id | integer | Optional; id of one of the caller's active custom domains. If omitted, defaults to their first active custom domain, or offerswap.com if they have none. |
Responses
| Status | Meaning |
|---|---|
| 200 | Created. |
| 400 | Validation failed. |
| 401 | Missing or invalid bearer token. |
Edit a link
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| destination_url | string (uri) | Repoint the short link at a new http(s) destination. The short code, alias, and click history are preserved; the ASIN is re-extracted for Amazon /dp/ URLs. |
| title | string | Max 200 chars. |
| source_label | string | Max 60 chars. |
| archived | boolean | true archives, false un-archives. |
| password | string | Set/change link password. Empty string clears it. Max 200 chars. |
| domain_id | integer | null | Move the link to a different custom domain (must be one the caller owns and is active). Pass null to move it back to offerswap.com. Changing the domain clears the current alias. |
| phone_open | string | null | On a phone, what a tap does: browser leaves Facebook's, Instagram's or TikTok's own in-app browser for Safari or Chrome first, stay loads it where they tapped and never opens an app, app or null is the default (an app destination such as Amazon opens its app, by way of Safari or Chrome when the tap was in an in-app browser). One of |
| alias | string | null | Custom path alias on the link's custom domain (e.g. |
Responses
| Status | Meaning |
|---|---|
| 200 | Updated link. |
| 400 |
|
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Delete a link (cascades click history)
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Deleted. |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Get or refresh a link's thumbnail image
Amazon /dp/ links get the Amazon product photo. Any other URL gets a screenshot of the page (1280x800, the first screen, ad pixels and analytics blocked), with the page's og:image or first image as the fallback. Takes about 5 to 10 seconds. Use when a link has no thumbnail or a stale one. On success the link's product_image_url is updated; a failed attempt leaves the existing image untouched.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Scrape attempted. |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Which tracking pixels fire on this link's clicks
A link fires only the pixels picked for it, and none when none are picked (since 2026-11-13: an active pixel on the account no longer fires on every link). events maps a pixel id to the event this link fires it as, when that differs from the pixel's default_event. overridden is kept for older clients and no longer changes what fires.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Replace the link's pixel selection
The link fires exactly these pixels; an empty list means none. overridden is still stored for older clients but no longer changes what fires. Each event must be valid for its pixel's platform.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| pixel_ids required | array of integer | |
| overridden | boolean | |
| events | object | Per pixel event, keyed by pixel id. |
Responses
| Status | Meaning |
|---|---|
| 200 | The saved selection: { pixel_ids, events, overridden }. |
| 400 |
|
| 403 | The link or one of the pixels is not yours. |
| 404 | Resource does not exist. |
Assign a link to (or detach from) a collection
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| collection_id | integer | null | Numeric collection id. Pass |
Responses
| Status | Meaning |
|---|---|
| 200 | Updated link. |
| 400 |
|
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Preview turning a link into a campaign
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | { can_convert, blocked, campaign_name, short_url, offer, dropped: { pixels, collection } }. Nothing changes. |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Turn a link into a campaign on the same URL
The campaign takes the link's short code and domain, so the posted URL keeps working and runs through the tracker. Its flow sends traffic to an offer for the link's destination. The link is archived and keeps its click history. Cannot be undone. Links with a custom alias or a password are refused with 409.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | { campaign: { id, name, code, short_url }, offer: { id, reused }, link_id } |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
| 409 | { error: link_has_alias | link_has_password | already_moved } |
Statistics
Click analytics for short links. Campaign traffic and page views are under Reports.
Account-wide aggregated LINK CLICK stats
Account-wide analytics for branded short LINKS only (total clicks, by day/country/device/browser/referrer, peak hour & weekday). Does NOT include Tracker page views, site-property traffic, or campaign visits/conversions. For PAGE VIEWS use GET /api/tracker/overview or the per-property GET /api/properties/{id}/stats. To report clicks AND page views together, read both this endpoint and GET /api/tracker/overview and combine them, because they are separate event streams.
Parameters
| Name | In / type | Notes |
|---|---|---|
| days | query integer | Time window in days. Clamped to 1–90. Default |
Responses
| Status | Meaning |
|---|---|
| 200 | Account-wide click stats in one round trip (short-link clicks only; page views and campaign traffic are under Reports). Returns |
| 401 | Missing or invalid bearer token. |
Per-link aggregated stats
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer | |
| days | query integer | Default |
Responses
| Status | Meaning |
|---|---|
| 200 | Per-link stats. Returns |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Every link's clicks in a window
Every live short link with its clicks in the window, plus archived links that had clicks in it, sorted by clicks. Not part of /api/tracker/overview.
Parameters
| Name | In / type | Notes |
|---|---|---|
| from | query string (date-time) | Window start. |
| to | query string (date-time) | Window end. Omit to run to now. |
| days | query integer | Rolling window when from is not set. Default |
Responses
| Status | Meaning |
|---|---|
| 200 | { window_from, window_to, totals: { links, clicks, unique_clicks }, links: [{ id, code, title, destination_url, short_url, clicks, unique_clicks, top_country, top_device, last_click_at, archived, campaign }] } |
| 401 | Missing or invalid bearer token. |
Collections
Folders of links. A collection can also be a rotator, offerswap.com/c/{alias}, which sends each visit to a random member.
/api/collectionsPOST /api/collectionsGET /api/collections/{id}PATCH /api/collections/{id}DELETE /api/collections/{id}List collections
Responses
| Status | Meaning |
|---|---|
| 200 | Collections with link + click counts. |
Create a collection
Request body
| Field | Type | Notes |
|---|---|---|
| name required | string | Max 80 chars. |
| description | string | Max 280 chars. |
| color | string | Hex color from a fixed palette; invalid values fall back to |
| starred | boolean | Default |
| rotator_enabled | boolean | Default |
| rotator_alias | string | 8–24 chars |
Responses
| Status | Meaning |
|---|---|
| 200 | Created. |
| 400 |
|
| 409 |
|
Collection detail (meta + member links + aggregated stats)
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer | |
| days | query integer | Default |
Responses
| Status | Meaning |
|---|---|
| 200 | Collection detail page payload. |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Update a collection
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| name | string | Max 80 chars. |
| description | string | Max 280 chars. |
| color | string | |
| starred | boolean | |
| rotator_enabled | boolean | |
| rotator_alias | string |
Responses
| Status | Meaning |
|---|---|
| 200 | Updated. |
| 400 |
|
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
| 409 |
|
Delete a collection (member links are detached, not deleted)
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Deleted. |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Tracking pixels
Meta, TikTok and Google pixels. They fire in the browser when a short link is clicked, and a Meta or TikTok pixel with a Conversions API token also receives a campaign's sales server to server.
/api/tracking-pixelsPOST /api/tracking-pixelsPOST /api/tracking-pixels/{id}/testPATCH /api/tracking-pixels/{id}DELETE /api/tracking-pixels/{id}List tracking pixels + supported platforms
Responses
| Status | Meaning |
|---|---|
| 200 | Pixels + platform catalog (label/placeholder/help text). |
Add a tracking pixel
Request body
| Field | Type | Notes |
|---|---|---|
| platform required | string | One of the keys returned by |
| pixel_id required | string | |
| label | string | Max 80 chars. |
| default_event | string | Event this pixel fires by default (e.g. Facebook |
| capi_token | string | Optional server-side Conversions API access token (Facebook/TikTok). Lets campaign events fire server-to-server. Whitespace inside it (a line break from pasting) is removed. Never returned; only |
| test_event_code | string | Optional Meta test event code. While set, every server event this pixel sends lands in Test events and never counts. |
| active | boolean | Default |
Responses
| Status | Meaning |
|---|---|
| 200 |
|
| 400 |
|
Send one test event with the pixel's token
Sends a $1 Purchase (or the event in the body) server-side with the pixel's own token, to prove the pixel id and token work. Requires a test_event_code on the pixel, so a test never counts as a real sale. The result is recorded on the pixel's last_sent_* / last_error*.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| event | string | Optional event name valid for the platform. Defaults to Purchase. |
Responses
| Status | Meaning |
|---|---|
| 200 |
|
| 400 |
|
| 404 | Resource does not exist. |
Update a pixel
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| pixel_id | string | |
| label | string | |
| default_event | string | New default event (must be valid for the pixel's platform). |
| capi_token | string | null | New Conversions API token, or empty string / null to clear. |
| test_event_code | string | null | Meta test event code, or empty string / null to clear it and go live. |
| active | boolean |
Responses
| Status | Meaning |
|---|---|
| 200 |
|
| 400 |
|
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Delete a pixel
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Deleted. |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Domains
Serve short links and campaigns from your own hostname, such as go.acme.com, with SSL from Cloudflare for SaaS. Paid plans only.
/api/domainsPOST /api/domainsDELETE /api/domains/{id}POST /api/domains/{id}/verifyGET /api/domains/{id}/dnsPOST /api/domains/{id}/connect-cloudflareList custom domains
List the user's branded short-link domains, plan tier, plan domain limit, and the CNAME target each domain must point at.
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Register a custom domain
Creates a Cloudflare for SaaS custom hostname and stores it. The user must then point a CNAME record at cname_target for SSL/validation to complete. Free plan returns 402 upgrade_required.
Request body
| Field | Type | Notes |
|---|---|---|
| hostname required | string | Example |
Responses
| Status | Meaning |
|---|---|
| 200 | Created. |
| 400 | invalid_hostname or reserved_hostname |
| 402 | upgrade_required or plan_limit_reached |
| 409 | hostname_taken |
| 502 | cloudflare_error |
Remove a custom domain
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Removed. |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Force re-check domain status against Cloudflare
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Refreshed. |
Detect the DNS host and the easiest way to connect
Reads the domain's public nameservers. one_click.method is domain_connect (send the user to one_click.url), cloudflare_oauth (the user clicks Connect Cloudflare in Properties, which needs a browser), or null (add the CNAME by hand). On Cloudflare, one_click.token_url is also set, for connect-cloudflare.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Detection result. |
Add the CNAME to the user's own Cloudflare zone
For callers with no browser. Uses a Cloudflare API token with Zone Read and DNS Edit for this one request. The token is never stored. Never overwrites an existing record.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| api_token required | string |
Responses
| Status | Meaning |
|---|---|
| 200 | Record created, or already correct. |
| 400 |
|
| 403 |
|
| 404 |
|
| 409 |
|
API keys
Personal access tokens for the API and the MCP server.
List your personal access tokens (token hash never returned)
Responses
| Status | Meaning |
|---|---|
| 200 | Tokens with metadata. |
Create a new personal access token
Returns the raw token exactly once. Store it immediately. There is no way to retrieve it again. We store SHA-256(token) only.
Request body
| Field | Type | Notes |
|---|---|---|
| label | string | Default |
Responses
| Status | Meaning |
|---|---|
| 200 | Created. Token shown ONCE. |
Revoke an API key
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Revoked. |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Campaigns
A campaign is the tracked link that goes in an ad. Its flow routes each visit to landing pages and offers by weight, mints a click id, and credits sales from the postback to the ad that sent them.
/api/campaignsPOST /api/campaignsGET /api/campaigns/{id}PATCH /api/campaigns/{id}DELETE /api/campaigns/{id}POST /api/campaigns/{id}/duplicatePUT /api/campaigns/{id}/offersPUT /api/campaigns/{id}/landersGET /api/campaigns/{id}/flowPUT /api/campaigns/{id}/flowCreate a campaign
Server mints an 8-char base62 code (same namespace as link codes; a DB trigger blocks collisions). Pass optional offer_ids and lander_ids arrays (with matching *_weights) to wire the destination inline.
Every campaign response includes a click_url (https://{host}/click): the single, campaign-agnostic lander click URL the operator pastes into their lander's CTA button. It's the same on every campaign, so one lander can be reused across many; the campaign is resolved at click time from the bgl_clk_{code} cookie (short-link traffic) or the ad's ?utm_campaign={slug} (matched against any of the campaign's direct_slugs) forwarded onto the CTA (direct-link). It always resolves to an offer (chosen by the flow graph + split weights), never a lander, never a dead page (see the public /click path). Responses include direct_slugs: [{ slug, label }] plus a legacy direct_slug that mirrors the OLDEST slug for back-compat.
Request body
| Field | Type | Notes |
|---|---|---|
| name required | string | |
| traffic_source_id | integer | null | Id of one of the caller's saved traffic sources (from |
| traffic_source | string | Legacy structured traffic source key (facebook, google, tiktok, …). Prefer |
| traffic_source_label | string | Free-text display label. |
| country | string | |
| cost_model | string | One of |
| cost_value | number | |
| transition_mode | string | How the campaign link sends a visitor on. |
| domain_id | integer | null | Optional id of one of the caller's active custom domains (from /api/domains). The campaign's short link will resolve at that hostname. If omitted, defaults to the caller's first active custom domain, or offerswap.com if they have none. Pass null to force the platform default. |
| conversion_pixel_id | integer | null | Optional id of one of the caller's tracking pixels to fire when this campaign converts (server-side via the pixel's CAPI token when set). Pass null for none. |
| conversion_event | string | Event a sale fires (e.g. Purchase, Lead, CompletePayment). Must be valid for the pixel's platform; defaults to that pixel's default_event. Prefer pixel_events. |
| pixel_events | object | null | Which of the campaign's events reach its conversion pixel, and as what. Keys are |
| report_value_mode | string | What revenue value to report back to the ad platform on a CAPI conversion. payout (default) = real payout; fixed = always report_value_fixed; adjusted = real payout − report_value_adjust_pct% − report_value_adjust_flat (floored at 0). Lets the operator withhold their margin from what the platform optimizes against. One of |
| report_value_fixed | number | null | Fixed value reported on every conversion when report_value_mode = fixed. |
| report_value_adjust_pct | number | null | Percentage subtracted from real payout when report_value_mode = adjusted (applied before the flat amount). |
| report_value_adjust_flat | number | null | Flat amount subtracted after the percentage when report_value_mode = adjusted. |
| direct_slugs | array of string or object | Direct-link tags for this campaign. A campaign can now claim MULTIPLE |
| direct_slug | string | null | DEPRECATED but still accepted: the legacy single direct-link tag. Prefer |
| fallback_url | string | null | Optional URL the click falls back to when the flow yields no live offer: the never-dead-end guarantee. If unset, falls back to the platform default. Pass null to clear. Max 2000 chars. |
| open_in_browser | boolean | Older all-offers default, kept for compatibility: sends a phone tap to any offer with no phone_open of its own to Safari or Chrome. Set phone_open on each flow node instead; it wins over this. Default |
| offer_ids | array of integer | |
| offer_weights | array of integer | |
| lander_ids | array of integer | |
| lander_weights | array of integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Created |
Get a campaign with attached offers and landers
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Update a campaign
Patch any subset of: name, traffic_source_id, traffic_source, traffic_source_label, country, cost_model, cost_value, transition_mode, domain_id, conversion_pixel_id, conversion_event, pixel_events, report_value_mode, report_value_fixed, report_value_adjust_pct, report_value_adjust_flat, direct_slugs, direct_slug (legacy), fallback_url, open_in_browser, dim_labels, archived. Pass dim_labels to replace the names the user gave this campaign's tokens, for example { "utm_medium": "Ad Name" }. Pass direct_slugs (array of strings or { slug, label }) to replace the campaign's full set of direct-link tags ([] clears them); the legacy single direct_slug is still accepted and merged in. Pass domain_id to change the branded hostname the short link resolves under (must be one the caller owns and is active), or null to move it back to offerswap.com. Setting any slug already used by another of the caller's campaigns returns 409 direct_slug_taken.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
Body: object
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Archive a campaign
Campaigns are never deleted. This sets archived_at (the short link stops routing, reports stay) and returns { ok, archived }. PATCH archived=false restores it.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Duplicate a campaign
Deep-copies the campaign's settings, full routing flow graph (nodes + edges with split weights), and derived offer/lander pools into a brand-new campaign with a fresh short code. The copy is named COPY - {original} (or COPY (1) - {original}, COPY (2) - … when duplicating a copy). Stats are not copied and the unique direct-link tags (direct_slugs / legacy direct_slug) are left blank. Returns the new campaign.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Replace the campaign's offer split
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| items required | array of object |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Replace the campaign's lander split
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| items required | array of object |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Get the campaign's routing flow graph (n8n-style)
Returns { flow: { nodes, edges }, offers, landers }. Nodes have kind of source (one entry, ref_id null), lander, or offer. Edges (from_node_id → to_node_id, weight) only go source→lander, source→offer, or lander→offer. The resolver walks this graph per click, so a specific lander can route to its own specific offers. A rule node also carries name, conditions and priority.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Replace the campaign's routing flow graph
Replaces the whole graph and re-derives the flat offer/lander pools. tmp_id is any client-stable key; edges reference nodes by tmp_id. Provide exactly one source node. An unwired graph (source with no outbound edges) falls back to flat-pool routing. Set direct: true on a lander the ad links straight to: the campaign link then goes on to its offers instead of sending the visitor to it, and direct landers win over every other edge on the source.
Rules (Voluum style rule paths): a rule node hangs off the source (not on a direct link campaign) or off a lander, with one edge into it. Its own edges are its branches: landers or offers after the source, offers after a lander. At that step, rules are checked in priority order; the first whose conditions all match and that has a branch sends the visitor down its branches, everyone else takes the step's plain edges, and with no plain edge they go to the campaign's fallback_url. Condition types: country, region, city, device (mobile, desktop), os, browser, inapp, language, ip (addresses or CIDR), isp, referrer, param (name plus values), time (from, to, tz) and weekday (values, tz). A bad condition or misplaced rule is 400 with error (invalid_rule, rule_on_direct_source, rule_bad_parent, rule_bad_branch, rule_has_many_parents) and a message.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| nodes required | array of object | |
| edges required | array of object |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Offers
The destinations a campaign sends clicks to, usually an affiliate or checkout URL. An offer has no link of its own; the link to share is always a campaign's.
/api/offersPOST /api/offersPOST /api/offers/{id}/campaignPATCH /api/offers/{id}DELETE /api/offers/{id}List offers
Parameters
| Name | In / type | Notes |
|---|---|---|
| include_archived | query string | 1 to include archived offers One of |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Create an offer
Request body
| Field | Type | Notes |
|---|---|---|
| name required | string | |
| url required | string | |
| affiliate_network_id | integer | null | |
| payout | number | |
| payout_currency | string | Default |
| country | string |
Responses
| Status | Meaning |
|---|---|
| 200 | Created |
Create a campaign for an offer (its link to share)
Makes the simplest campaign for the offer (named after it, on the account's default domain, every click to the offer) and returns its link. Each call makes a new campaign.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | { campaign: { id, name, code, short_url } } |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Update an offer
Renaming an offer also renames any older short link left on its URL. Offers get no short link of their own.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
Body: object
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Archive an offer
Offers are never deleted. This sets archived_at and returns { ok, archived }. PATCH archived=false restores it.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Landers
Landing pages a campaign can send visitors to before the offer.
Create a lander
Request body
| Field | Type | Notes |
|---|---|---|
| name required | string | |
| url required | string | Lander URL. May contain {clickid} tokens which the resolver expands at click time. |
| country | string |
Responses
| Status | Meaning |
|---|---|
| 200 | Created |
Update a lander
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
Body: object
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Delete a lander
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Traffic sources
The ad platforms you buy traffic from, with each platform's click macros mapped onto UTM parameters.
/api/traffic-sourcesPOST /api/traffic-sourcesPATCH /api/traffic-sources/{id}DELETE /api/traffic-sources/{id}List traffic sources + presets
User-managed list of the platforms the caller buys traffic from. Returns sources plus a presets catalog (Facebook, TikTok, Google, …) with each platform's standard click macros. A campaign references one source via traffic_source_id.
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Create a traffic source
Request body
| Field | Type | Notes |
|---|---|---|
| name required | string | Example |
| platform | string | null | Optional pixel-platform key (facebook, google_ads, tiktok, bing, …) for the icon + conversion-pixel suggestion. |
| token_params | array of object | Maps the source's click macros onto Google UTM params. Each item is { slot, label, token }. |
Responses
| Status | Meaning |
|---|---|
| 200 | Created |
Update a traffic source
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| name | string | |
| platform | string | null | |
| token_params | array of object | |
| archived | boolean |
Responses
| Status | Meaning |
|---|---|
| 200 | Updated |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Delete a traffic source
Unlinks the source from any campaigns (their traffic_source_id is set null) and removes it.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | Deleted |
| 403 | Resource exists but is not owned by the caller. |
| 404 | Resource does not exist. |
Affiliate networks
Networks your offers belong to, with the parameter name each reads the click id from.
/api/affiliate-networksPOST /api/affiliate-networksPATCH /api/affiliate-networks/{id}DELETE /api/affiliate-networks/{id}Create an affiliate network
Request body
| Field | Type | Notes |
|---|---|---|
| name required | string | |
| conversion_param | string | Default |
| amazon_tag | string | Amazon Associates tag (e.g. yourtagid-20). When set, Amazon destination links are auto-tagged with ?tag={amazon_tag} at click time. |
Responses
| Status | Meaning |
|---|---|
| 200 | Created |
Update an affiliate network
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
Body: object
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Delete an affiliate network
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Postback events
Custom events a postback can record besides a sale, such as add_to_cart, upsell or lead.
/api/custom-eventsPOST /api/custom-eventsPATCH /api/custom-events/{id}DELETE /api/custom-events/{id}List custom postback events
Returns events (the account's own), built_in (sale, refund, chargeback) and presets (common starting points, not yet created).
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Create a custom postback event
The slug is the value of event= on a postback, defaults to the label slugified, and cannot be changed later. With counts_revenue the event adds its payout to revenue and is deduped by txid. Without it, the event is counted at most once per click.
Request body
| Field | Type | Notes |
|---|---|---|
| label required | string | |
| slug | string | |
| counts_revenue | boolean |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | label_required, bad_slug, reserved_slug or too_many_events |
| 409 | slug_taken |
Rename a custom event or change whether it counts revenue
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| label | string | |
| counts_revenue | boolean |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Delete a custom event
Recorded events stay. Postbacks using the slug get a 400 from then on.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Reports
The campaign report, the dashboard overview, the event log and saved report views.
/api/report-viewsPOST /api/report-viewsPUT /api/report-views/activePATCH /api/report-views/{id}DELETE /api/report-views/{id}GET /api/campaigns/{id}/statsGET /api/observed-campaign-tagsGET /api/tracker/overviewGET /api/tracker/realtimeGET /api/tracker/eventsList saved report views
Returns views (each { id, name, columns, created_at, updated_at }) and active: "fewer", "all", or a view id as a string. A view is the report's columns in the user's order; reports open on the active one.
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Save a report view
columns is an ordered list of column ids (lander_views, unique_lander_views, visits, unique_visits, clicks, unique_clicks, ctr, unique_ctr, conversions, cr, refunds, chargebacks, epc, epv, unique_epv (all three gross), aov (net), gross_aov, gross_revenue (before refunds and chargebacks), reversed (refunds and chargebacks), revenue (net), cost (ad spend), custom:{slug}, take:{slug}, unique_take:{slug}). The view becomes active unless activate is false.
Request body
| Field | Type | Notes |
|---|---|---|
| name required | string | |
| columns required | array of string | |
| activate | boolean |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | name_required, columns_required, bad_column, too_many_columns or too_many_views |
| 409 | name_taken |
Pick the view reports open on
Request body
| Field | Type | Notes |
|---|---|---|
| view required | string | "fewer", "all", or a view id |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | bad_view |
| 404 | not_found |
Rename a report view or replace its columns
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| name | string | |
| columns | array of string |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 409 | name_taken |
Delete a report view
If it was active, reports go back to "fewer".
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Get full report for a campaign
Totals (visits/offer_clicks/conversions/refunds/chargebacks/revenue/ gross_revenue/reversed_revenue/custom/CTR/CR/EPC/ROI), by_day/ country/device/browser/referrer/hour, per-offer + per-lander performance, recent events, and breakdowns: grouped report rows for 10 dimensions (utm_campaign / utm_medium / utm_source / utm_content / utm_term / lander / offer / country / device / day), each row {key, visits, clicks, conversions, refunds, chargebacks, revenue, gross_revenue, reversed_revenue, cost, custom, ctr, cr, epc, aov, gross_aov}. cost (here and in totals) is the ad cost the campaign's cost model put on its visits (CPC), 0 without one. It never includes refunds or chargebacks, which are reversed_revenue (the app's Reversed column). aov (here and in totals) is net revenue per sale, after refunds and chargebacks; gross_aov is gross revenue per sale, before them. Both are 0 with no sale. epc (here and in totals) is gross revenue per offer click, before refunds and chargebacks. conversions counts sales and revenue is net of refunds and chargebacks. custom is keyed by event slug, each {count, revenue}, and the top-level custom_events lists the account's definitions with their labels. Offer clicks and conversions are attributed to the utm values of the visit that minted their click_id; the offer dimension attributes each visit to the offer its click routed to (keyed by offer name); the lander dimension is the page the click came from (visit referrer as host+path; pages running the property tag pass their full path via bgl_page, added only to links on the account's own tracker domains); missing values group under (none). Drill-down: pass any breakdown dimension as a query param (e.g. ?utm_campaign=Summer Sale, ?offer=My Offer, ?day=2026-07-09) and the whole report (totals, by_day, breakdowns) narrows to that traffic slice; filters combine and echo back in filters. Stacked report: ?group=utm_campaign,utm_medium,offer (up to 3 dimensions) returns report.rows as a tree, each row with children for the next level. group also takes region, city, browser, language, weekday and hour and custom tokens as param:<name>. Day, weekday, hour, by_day and by_hour count in the account time zone, or in tz when given; the response echoes it as timezone. Every extra param on the inbound link, sub1 to sub5 included, is kept on the visit, except click ids and personal fields. With no group the report groups by offer. passed_dims lists what the URLs really carried in the window: the utm_* tokens that had a value, then the param:<name> ones. On a direct lander the ad's URL counts even if the page's button drops it: the visit fills in from that visitor's page view. Custom tokens filter as ?param:adset_name=Broad. dim_labels holds the names the user gave this campaign's tokens, e.g. utm_medium: Ad Name. When the flow has a direct lander, direct_lander is true, and totals.lander_views and each row's lander_views count that page's property-tag page views, with lander_ctr as visits per lander view. Every row and the totals also count people, not rows: unique_visits and unique_clicks (unique_offer_clicks in totals) go by the IP and user agent of the visit that minted the click, and unique_lander_views by the property tag's visitor cookie, then IP and device. totals.unique_events counts the people behind each sale and custom event, keyed conversion or the event slug. Window is a rolling days count, or an explicit closed range via from/to (which override days).
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer | |
| days | query integer | Default |
| from | query string (date-time) | |
| to | query string (date-time) | |
| group | query string | Comma-separated dimensions to stack, up to 3, e.g. utm_campaign,utm_medium,offer |
| breakdowns | query string | 0 skips the ten fixed breakdowns (returned as empty arrays) and keeps everything else. Several times faster on a long window; the app's Report sends it. One of |
| utm_campaign | query string | |
| utm_medium | query string | |
| utm_source | query string | |
| utm_content | query string | |
| utm_term | query string | |
| lander | query string | Lander page host+path as returned in breakdowns.lander keys |
| offer | query string | Offer name as returned in breakdowns.offer keys |
| country | query string | |
| device | query string | |
| day | query string | Day YYYY-MM-DD in the report's time zone |
| tz | query string | IANA time zone to count days and hours in. Defaults to the account time zone |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Distinct utm_campaign tags seen on properties (direct-link-tag picker)
Returns the distinct utm_campaign values actually seen arriving on the caller's properties/visits over the last 90 days, most-active first. Each item also carries a slug (the sanitized form of utm_campaign). Use to wire an already-running direct-link campaign to a BGL campaign: pick an unclaimed tag and add it to the campaign's direct_slugs. claimed_by is matched by slug across all of a campaign's tags and is non-null when another campaign already owns that tag.
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Unified tracker dashboard rollup, PAGE VIEWS (sites + campaigns)
PAGE VIEWS live here. One-call rollup across BOTH event streams (property_events + tracker_events): totals (page_views, unique_visitors, visits, offer_clicks, conversions, revenue), by_day (merged daily activity), by_country / by_device / by_browser, per-property and per-campaign rollups (the per-property rollup gives page_views per site; each campaign row has visits, lander_views, offer_clicks, conversions, net revenue and direct_lander, and on a direct lander campaign EPV is revenue per lander view, else per visit), utm_campaigns (auto-detected Google utm_* tags with events/conversions/revenue), utm_sources (one row per utm_source, uncapped), and the 50 most recent events across both streams. In utm_campaigns and utm_sources a sale counts under the UTMs of the visit on its click, revenue is net, and events counts traffic only. This is the endpoint for "page views" and "page views per property". Page views here are SEPARATE from branded short-link clicks (GET /api/stats/overview); to report clicks AND page views together, read both endpoints and combine them.
Parameters
| Name | In / type | Notes |
|---|---|---|
| days | query integer | Default |
| from | query string (date-time) | Start of an explicit range (overrides days). With no |
| to | query string (date-time) | End of the explicit range. |
| tz | query string | IANA time zone by_day counts in. Defaults to the account time zone, else UTC. Echoed as |
| offer_id | query integer | Scope the rollup to a single offer: its offer_click events plus the conversions that share a click_id with one of them. Property events are excluded when set. |
| property_id | query integer | Scope the rollup to a single property's page events. Campaign events are excluded when set. |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Realtime, the last 30 minutes across every campaign and property
Google Analytics "Realtime overview" for the whole account. Always the last 30 minutes, so it takes no window. active_30 and active_5 are people active in the last 30 and 5 minutes; per_minute is 30 counts, oldest minute first. by_campaign is active people per campaign (campaign_id: null, name: "Not from a campaign" is people on a tagged page that no campaign claimed) with active_5. by_page is page views and people per page (host+path, newest title), most viewed first. events is the funnel in order (page views, visits, offer clicks, custom events, sales, then revenue events, refunds and chargebacks), each { type, label, count, people }. locations is people per city with Cloudflare's approximate lat/lon; located is how many people could be placed. A person is IP + device + browser on every row; an offer click or a postback counts under the visit on its click, so a postback is never a person on its own. Only traffic (page views, visits, lander views, offer clicks, outbound) makes a person active. Bots are left out. revenue_today is GROSS revenue since midnight (sales and revenue events plus property tag conversions, before refunds and chargebacks, which are for sales from other days), and net_revenue_today is the same after refunds and chargebacks. Both are counted in timezone: the tz param, else the account's time zone, else UTC. Each is null when it could not be read.
Parameters
| Name | In / type | Notes |
|---|---|---|
| tz | query string | IANA time zone that today's midnight is counted in (revenue_today). Defaults to the account's zone, then UTC. |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Searchable / filterable / sortable unified UTM event log
Event log across BOTH streams with full search/filter/sort over auto-detected Google UTM tags (utm_source / utm_medium / utm_campaign / utm_term / utm_content). Returns the matching page of events plus facets (distinct UTM values in the window) and total (full match count). Only visit events store city, region and IP, so other campaign events report the values of the visit that shares their click_id. An event with no matching visit leaves them null.
Parameters
| Name | In / type | Notes |
|---|---|---|
| days | query integer | Default |
| from | query string (date-time) | Start of an explicit range (overrides days). |
| to | query string (date-time) | End of the explicit range. Defaults to now. |
| q | query string | Free-text across utm_* |
| stream | query string | Ignored when campaign_id, offer_id, property_id, or link_id is set (each forces its own single stream). One of |
| campaign_id | query integer | Scope the log to a single campaign (forces stream=campaign). |
| event | query string | Exact event_type filter |
| utm_source | query string | |
| utm_medium | query string | |
| utm_campaign | query string | |
| utm_term | query string | |
| utm_content | query string | |
| offer_id | query integer | Scope the log to a single offer (forces stream=campaign): its offer_click events plus the conversions sharing a click_id with one of them. |
| property_id | query integer | Scope the log to a single property (property/site stream only). |
| link_id | query integer | Scope the log to a single short link: its resolver clicks from link_clicks, returned as stream=link, event_type=click rows. For a plain link that has no offer/campaign record behind it. |
| sort | query string | One of |
| dir | query string | One of |
| limit | query integer | Default |
| offset | query integer | Default |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Properties
Site containers for the universal /t.js tag, which records page views, engagement, outbound clicks and conversions on every page of a site.
/api/propertiesPOST /api/propertiesGET /api/properties/{id}PATCH /api/properties/{id}DELETE /api/properties/{id}PUT /api/properties/{id}/campaignsGET /api/properties/{id}/statsGET /api/property-pagesList properties with quick-look stats
A property is a GTM/GA-style site container. Each property has a public property_key and an install snippet: one universal tag the user pastes on every page of their site. Pages auto-report pageviews, time-on-page, scroll, outbound clicks, and conversions, and auto-attribute to a campaign when the visitor carries that campaign's click.
Page views are metered on the Free plan only (10k per month). Paid plans are unlimited. When a user exceeds their monthly page-view allowance, new page-view events stop recording until the cycle resets; outbound/conversion events keep recording, and link clicks (the Links section) remain unlimited.
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Create a property
Server mints a 16-char base62 property_key. Requires an active custom domain: the install tag is served from the user's own domain so it stays first-party to their site (required for tracking to work on iOS/Safari, because a tag loaded cross-site from offerswap.com gets its visitor cookie partitioned/blocked). Defaults to the user's first active custom domain; pass domain_id to pin a specific one. If the user has no active custom domain, returns 400 { error: "domain_required" }.
The response includes tracking_domain (the bound hostname) and the install snippet: a single GA/Facebook-style inline <script> block (an IIFE that defines a queueing bglFireConversion stub and then injects https://{tracking_domain}/t.js?p={property_key} asynchronously). The stub ensures a thank-you page calling window.bglFireConversion(revenue) before the async tag finishes loading does not lose the conversion (the tag drains the queue on load).
Request body
| Field | Type | Notes |
|---|---|---|
| name required | string | |
| site_url | string | Optional primary site URL (informational). |
| domain_id | integer | Optional id of one of the user's active custom domains to serve the tag from. Defaults to the first active custom domain. |
Responses
| Status | Meaning |
|---|---|
| 200 | Created |
Get a property with its install snippet and linked campaigns
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Update a property
Patch any subset of: name, site_url, domain_id, archived. domain_id must reference one of the user's active custom domains (a property never falls back to offerswap.com); re-binding regenerates the install snippet.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
Body: object
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Archive a property
Properties are never deleted. This sets archived_at (the tag stops counting, page views stay) and returns { ok, archived }. PATCH archived=false restores it.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Replace the campaigns linked to a property
Many-to-many link, for organisation and the source split in reports. Stitching still happens automatically by click regardless of links.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| items required | array of object |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Get full GA-style report for a property
Totals (page_views, unique_visitors, outbound, conversions, revenue, avg_time_on_page_ms, avg_scroll_pct, CR), by_day, by_page (top paths), by_source (organic vs each stitched campaign), by_country / by_device / by_browser / by_referrer, and the 50 most recent events.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer | |
| days | query integer | Default |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
List pages seen across all properties (usable as campaign landers)
Returns the distinct pages observed across all the caller's properties (their pageview stream), most-viewed first. Any page can be used as a campaign lander: POST its url to /api/landers, then wire the lander into a campaign flow.
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Split tests
Test a page's headline, buttons or images without rebuilding it. The property tag swaps each variant in per visitor, and a revenue bandit moves traffic toward the variant making the most money per visitor.
/api/split-testsPOST /api/split-testsPOST /api/split-tests/scanPOST /api/split-tests/scan/clickPOST /api/split-tests/scan/closePOST /api/split-tests/generatePOST /api/split-tests/imagesGET /api/split-tests/{id}PATCH /api/split-tests/{id}DELETE /api/split-tests/{id}List split tests with their live results
Every split test, newest first, with its arms and results: per arm views (people who saw it), clicks, buyers, sales, gross, net (after refunds and chargebacks), weight (its share of new visitors right now) and p_best (how often the bandit drew it as best). Arm a is the page as it is. burn_in is true until the test has burn_in_target counted visitors (200), and the split is even until then. missing counts views where the tested element was no longer on the page as scanned (missing_last, found_last say when). Also returns ai_credits { used, limit, left, resets_at }.
Parameters
| Name | In / type | Notes |
|---|---|---|
| include_archived | query string | One of |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Create a split test (a draft)
elements are scanned elements (from POST /api/split-tests/scan) the test changes, each { id, kind: text|image, role, selector, text, match?, src, bg_image?, rect }. Arm a (the original) is added for you. arms are up to 3 variants, each { name, source?, changes } where a change is { element, text?, src?, color?, background? }. In text, *words* in stars take the page's highlight style. Start it with PATCH { status: "running" }.
Request body
| Field | Type | Notes |
|---|---|---|
| page_url required | string | |
| name | string | |
| page_title | string | |
| device | string | One of |
| property_id | integer | |
| screenshot_url | string | |
| screenshot_w | integer | |
| screenshot_h | integer | |
| elements required | array of object | |
| candidates | array of object | |
| arms | array of object |
Responses
| Status | Meaning |
|---|---|
| 201 | Created |
| 400 | bad_url, no_elements, invalid_property, bad_changes or too_many_tests |
Scan a page for things to test
Opens the page in a headless browser (a phone unless device is desktop), with tracking pixels and the property tag blocked so the scan is never counted. Returns scan: a screenshot of the first six screens (screenshot_url, width, height in CSS pixels), the elements found there (every line of text as headline, subheadline, heading or text, buttons as role cta, images) with positions, and whether the page carries this account's property tag (has_tag, property_id). A test cannot start without the tag. Unless browse is false, the browser stays open for 5 minutes and session lets POST /api/split-tests/scan/click tap through the page. Takes about 15 seconds.
Request body
| Field | Type | Notes |
|---|---|---|
| url required | string | |
| device | string | One of |
| browse | boolean |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | bad_url |
| 502 | scan_failed |
| 503 | scan_unavailable |
Tap a scanned page to reach a later step
Browse mode. Taps the scan's open page at x, y (the screenshot's CSS pixels), for example a quiz's start button, and returns view: a new screenshot and that screen's elements, with ids of their own and later: true. The tag changes a later element whenever it appears, so a quiz's second screen can be tested. navigated: true means a different page loaded; its elements cannot go in this test.
Request body
| Field | Type | Notes |
|---|---|---|
| session required | string | |
| x required | number | |
| y required | number | |
| step | integer | |
| device | string | One of |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | bad_point |
| 410 | scan_expired (the browser closed after 5 idle minutes) |
Close a scan's open browser
Request body
| Field | Type | Notes |
|---|---|---|
| session | string |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Write variants with AI
Cloudflare Workers AI writes count (1 to 3) variants of the text elements passed. mode: auto also picks the 1 to 3 elements that matter most (pass every scanned text element). One AI credit per call that returns usable copy: Free 0, Small 20, Medium 50, Large 150 a month. Returns arms (ready to save), picked and ai_credits. The copy keeps the page's facts, adds no claims, prices or guarantees, and has no dashes.
Request body
| Field | Type | Notes |
|---|---|---|
| mode | string | One of |
| count | integer | |
| page_url | string | |
| page_title | string | |
| elements required | array of object | |
| context | array of string | |
| test_id | integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | no_text |
| 402 | ai_credits_exhausted |
| 502 | ai_failed (no credit used) |
Upload an image for an image variant
The request body is the image itself (JPG, PNG, WebP or GIF, up to 5 MB) with its Content-Type. Returns { url } for a change's src.
Request body
Body: string (binary)
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | bad_type, empty or too_big |
Get a split test
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 404 | not_found |
Edit, start, pause or end a split test
status: running starts or resumes (needs the property tag on the page, a variant with a change, and no other running test on the page), paused shows the page as it is, ended with winner_arm keeps showing that arm to everyone (none, or a, shows the original). arms: with a key, edit that arm (active: false retires it and keeps its numbers); without one, add a variant. Once a test has run, its elements and an arm's changes are locked (409 arm_locked, 409 test_started). remove_arms deletes draft arms.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Request body
| Field | Type | Notes |
|---|---|---|
| name | string | |
| status | string | One of |
| winner_arm | string | |
| elements | array of object | |
| arms | array of object | |
| remove_arms | array of string | |
| burn_in | integer | |
| floor | number | |
| reward_weight | number | |
| archived | boolean |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
| 409 | tag_missing, page_has_running_test (another test runs on this page; test_id names it), page_has_winner (an ended test's winner still changes an element this test changes; test_id names it), arm_locked, test_started or test_ended |
Archive a split test
A running test is paused first. Nothing is deleted.
Parameters
| Name | In / type | Notes |
|---|---|---|
| id required | path integer |
Responses
| Status | Meaning |
|---|---|
| 200 | OK |
Public endpoints
Served on offerswap.com and on every custom domain an account connects. No auth.
/{code}GET /c/{alias}GET /clickGET /c/{click_id}/outGET /postback/u/{token}GET /postback/n/{token}GET /postback/{token}GET /t.jsPOST /t/collectGET /p.jsPOST /p/collectShort link or campaign link
Resolves a short link (by code, or by alias on a custom domain) or a campaign. A short link logs the click (country, device, browser, referrer, language), forwards the incoming query parameters onto the destination, and redirects to exactly the saved URL. On a phone, a destination that belongs to an app (Amazon, YouTube, Instagram, Spotify, eBay and more) opens the app and falls back to the website when it is not installed; inside Facebook's, Instagram's or TikTok's own browser, which cannot open apps, the tap moves to Safari or Chrome first. A short link's phone_open (app, browser, stay) overrides that.
A campaign link mints a click id, logs a visit with the ad's UTM parameters and any other tokens, and routes by the campaign's flow to a landing page or an offer. On a custom domain, codes resolve only to that domain owner's links and campaigns; an unknown hostname returns 404.
Collection rotator
Sends each visit to a random member of the collection with this rotator alias, then resolves it like a short link.
Landing page click URL
The one URL a landing page's button points to, the same for every campaign. It always lands on an offer, chosen by the campaign's flow, never on a landing page and never on an error. The campaign comes from the visitor's bgl_clk_{code} cookie (they arrived on the campaign link), ?cmp={code}, ?cid={click_id}, or ?utm_campaign= matching one of the campaign's direct-link tags (the ad went straight to the page). With no live offer it goes to the campaign's fallback_url, then the platform default.
Landing page click by click id
An older form of /click that carries the click id in the path. Routes to an offer the same way.
Postback URL
The account's one postback URL (Voluum-style), returned as postback_url on GET /api/me. Paste it into any network's S2S settings or your own webhook (n8n, Zapier, a store's order webhook). Parameters:
clickid(aliascid): required, the click id the offer URL received.payout,currency,txid: optional. A sale sent with nopayoutbooks the payout of the offer its click went to, when that offer has one set.event: none is a sale.refundandchargebackare built in, matched by click, and subtract from revenue (send the amount as 67 or -67, or leave it out to reverse whatever is booked on the click). Anything else must be a custom event from/api/custom-events. A blank or unknowneventreturns 400 and records nothing.email(aliasem): optional. Hashed with SHA-256 and sent to the campaign's ad platform pixel so the platform can match the sale. Never stored.
Sales are deduped by txid: at most one per account and txid. A re-fire with the same txid is ignored, and one with a different payout updates the stored revenue. A postback with no txid is always recorded. Which events reach the campaign's ad platform pixel is the campaign's pixel_events.
Old network postback URL
A network's postback URL from before 2026-11-07. No longer handed out, but it still records sales exactly like the account's postback URL and still reads that network's saved parameter names.
Old campaign postback URL
A campaign's postback URL from before 2026-11-07. No longer handed out, but it still records sales exactly like the account's postback URL, crediting the click's own campaign.
Universal property tag
<script async src="https://{your-custom-domain}/t.js?p={property_key}"></script> on every page of a site. It sets a first-party visitor cookie and records page_view on load, time on page and scroll depth on leave, outbound on clicks off the site, and conversion when the page sets window.bglConversion = true (optionally window.bglRevenue) or calls window.bglFireConversion(revenue). It reads UTM parameters off the landing URL and keeps them for the visit. Serve it from your own custom domain: on offerswap.com its cookie is blocked as third party on iOS and Safari. Page views count toward the plan's monthly allowance.
Property tag beacon
Where /t.js sends its events. Resolves the property by its public key. CORS open.
Lander pixel
<script src="https://offerswap.com/p.js?c={campaign_code}"></script> in a lander's head. Records lander_view, the outbound click back to the campaign, engagement, and conversion when the page sets window.bglConversion = true or calls window.bglFireConversion(revenue). For a whole site, use the property tag /t.js instead.