Web: HTTP API

Authentication

Get an API key in publisher settings. Keep it on the server. Server requests to Sidekick must omit Origin.

Send exactly one user identity. Allowed characters: A–Z, a–z, 0–9, _, ., :, -. Keep the ID across requests; do not use an email or phone number.

Platform and site address requirements →

Request an ad

POST /api/v1/web/ads

* Required fields.

Content-Type: application/json. Maximum body size: 64 KiB.

Server request

POST /api/v1/web/ads
Authorization: Bearer sk_live_EXAMPLE
Content-Type: application/json

{
  "platform_id": "plt_example",
  "stable_user_id": "customer_42",
  "context": {
    "question": "Headphones?",
    "answer": "Here are some options…"
  },
  "test": true,
  "test_format": "card"
}

Browser request

visitorId is the persisted visitor ID. Send the request without an API key or cookies.

const response = await fetch("https://sidekick-ads.com/api/v1/web/ads", {
  method: "POST",
  credentials: "omit",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    platform_id: "plt_example",
    visitor_id: visitorId,
    request_id: "chat-42-message-7",
    test: true,
    test_format: "card"
  })
});

if (!response.ok) throw new Error("Ad request failed");
const payload = await response.json();

Context

Topic matching uses the user's question: question or title. feed and static have none, so they receive only ads without topic targeting.

Response

{
  "has_ad": false,
  "ad": null
}

An impression is paid once the ad is seen, not when it is issued. The browser SDK confirms the view itself; with custom rendering, send a view confirmation.

Rendering

Render every block and the disclosure. Use mountSidekickAd from the browser SDK for the standard card. In this example, payload comes from your server and /my-ad-interaction handles actions in your app.

const view = Sidekick.mountSidekickAd(document.querySelector("#ad-slot"), {
  onAction: async (ad, action) => {
    const response = await fetch("/my-ad-interaction", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ delivery_id: ad.delivery_id, action })
    });
    if (!response.ok) throw new Error("Interaction failed");
    return (await response.json()).ad;
  }
});

view.setAd(payload.has_ad ? payload.ad : null);

Interactions

POST /api/v1/web/interact

For consent and quiz, send the clicked button’s action, delivery_id and original user identity. Use the same authentication as the ad request.

{
  "platform_id": "plt_example",
  "stable_user_id": "customer_42",
  "delivery_id": "imp_example",
  "action": "signed-action-from-button"
}

Response: {ok: true, ad}. Replace the card with the returned ad. Advancing a scene does not create another paid impression.

For buttons with a url, open it on click. Do not prefetch advertising links.

View confirmation

POST /api/v1/web/seen

An impression is paid after a view: at least half of the card on screen for at least one second. The browser SDK sends this request itself. With custom rendering, call trackView(ad) or send the request with the same authentication and user identity.

{
  "platform_id": "plt_example",
  "stable_user_id": "customer_42",
  "delivery_id": "imp_example",
  "view": "view-receipt-from-ad"
}

Response: {ok: true}. The view receipt is valid for an hour. A request sooner than one second after issuance returns 409. A button press or a click on the ad link also counts the impression. Ads that are never seen are not paid.

Errors

Preserve the app response on error. Do not automatically retry ad requests after network failures or 5xx: every request is a new issuance.