Zyntent Docs — API & Integrations

Quick Start

Get intent-matched ads running on your platform in under 5 minutes. Add our SDK, configure a surface, and start earning.

Prerequisites

A Zyntent account and Site ID
A web page or app where you want to display ads

index.html

<!-- 1. Add the SDK to your <head> -->
<script
  src="https://sdk.zyntent.com/v1/zyntent.js"
  data-site-id="YOUR_SITE_ID"
  async
></script>

page.html

<!-- 2. Add an ad surface where you want ads -->
<div
  data-zyntent-surface="chat"
  data-context="auto"
></div>

That's it! The SDK will automatically detect user intent from page context and serve relevant ads. You can customize the surface type, styling, and behavior.

Installation

Choose the installation method that best fits your stack.

Script Tag (recommended)

The simplest way — works with any website or web app.

<head>

<script
  src="https://sdk.zyntent.com/v1/zyntent.js"
  data-site-id="YOUR_SITE_ID"
  async
></script>

REST API

For server-side or custom integrations.

Public API base URL: https://app.zyntent.ai

server.js

const response = await fetch('https://api.zyntent.com/v1/ads', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    site_id: 'YOUR_SITE_ID',
    surface: 'chat',
    context: {
      query: 'best noise cancelling headphones',
      page_url: 'https://example.com/tech-review',
      user_session: 'sess_abc123',
    },
  }),
})

const { ad } = await response.json()
// ad.headline, ad.description, ad.cta_url, ad.ctr_estimate

NPM Package

For React, Next.js, Vue, and other JavaScript frameworks.

Status: The NPM SDK is still in development and will be available soon.

terminal

npm install @zyntent/sdk

app.tsx

import { ZyntentProvider, AdSurface } from '@zyntent/sdk'

export default function App() {
  return (
    <ZyntentProvider siteId="YOUR_SITE_ID">
      <YourApp />
      <AdSurface
        type="chat"
        context="auto"
        position="inline"
      />
    </ZyntentProvider>
  )
}

Ad Surfaces

A surface is a placement on your page where Zyntent will render an ad. You can have multiple surfaces per page.

surfaces.html

<!-- Chat-style recommendation -->
<div data-zyntent-surface="chat" data-context="auto"></div>

<!-- Search result ad -->
<div data-zyntent-surface="search" data-query="user search query"></div>

<!-- Inline context ad -->
<div data-zyntent-surface="inline" data-context="auto"></div>

<!-- Forum/Q&A ad -->
<div data-zyntent-surface="forum" data-thread-id="thread_123"></div>

<!-- Domain parking -->
<div data-zyntent-surface="domain" data-domain="bestcoffeemachines.com"></div>

Surface Attributes

Attribute	Type	Description
data-zyntent-surface	string	Surface type: chat, search, inline, forum, domain
data-context	string	'auto' or custom context string for intent detection
data-query	string	User's search query (for search surfaces)
data-thread-id	string	Thread/discussion ID (for forum surfaces)
data-domain	string	Domain name (for domain parking surfaces)
data-max-ads	number	Maximum ads to show (default: 1)
data-style	string	'default', 'minimal', 'card', or 'native'

Ad Formats

Each surface type renders ads in a format optimized for that context.

Chat-Style

4-6% CTR

Native recommendations inside AI chat interfaces

Search-Driven

5-6% CTR

REST API

Public API base URL: https://app.zyntent.ai

POST /public_api/v1/ads/search/

Primary endpoint for retrieving intent-matched ads. Supports metadata and debug mode.

ads.search.request.json

{
  "source_id": "f2dec457-da5d-46fc-b810-645b0f8a3fdf",
  "query": {
    "text": "Apple phone buy"
  },
  "country": "US",
  "language": "",
  "ads_limit": 3,
  "metadata": {
    "surface": "suggest",
    "session_id": "sess_123",
    "page_url": "https://example.com/search"
  }
}

ads.search.response.json

{
  "ads": [
    {
      "title": "iPhone near me on Hi Store RU",
      "short_description": "Find iPhone near you via Hi Store RU",
      "link": "https://ztent.ai/g/6dd2a16b0b631b9e1593?impression_id=301e6eac-5c85-4c89-9fdd-d6c66b2dc64f",
      "price": null
    },
    {
      "title": "Used iPhones from HK Resale - HK Resale US",
      "short_description": "Find used iPhone options with HK Resale US",
      "link": "https://ztent.ai/g/6dd2a16b0b1e2157bc60?impression_id=301e6eac-5c85-4c89-9fdd-d6c66b2dc64f",
      "price": null
    },
    {
      "title": "Financing Vertu phone vertu.com US",
      "short_description": "Buy Vertu phone with financing in the US via vertu.com US",
      "link": "https://ztent.ai/g/6dd2a16b0ba45b858a77?impression_id=301e6eac-5c85-4c89-9fdd-d6c66b2dc64f",
      "price": null
    }
  ]
}

Debug mode

Set debug=true to receive intent diagnostics.

ads.search.debug.request.json

{
  "source_id": "f2dec457-da5d-46fc-b810-645b0f8a3fdf",
  "query": {
    "text": "Apple phone buy"
  },
  "country": "US",
  "language": "",
  "debug": true,
  "ads_limit": 3
}

ads.search.debug.response.json

{
  "ads": [
    {
      "title": "iPhone near me on Hi Store RU",
      "short_description": "Find iPhone near you via Hi Store RU",
      "link": "https://ztent.ai/g/6dd2a16b0b631b9e1593",
      "price": null,
      "language_code": "en",
      "entity_type": "merchant",
      "entity_pk": "e51443c0-1feb-497a-b477-6c549c2bedd1",
      "google_category_specific_id": 1001502,
      "intent_id": 685550
    },
    {
      "title": "Used iPhones from HK Resale - HK Resale US",
      "short_description": "Find used iPhone options with HK Resale US",
      "link": "https://ztent.ai/g/6dd2a16b0b1e2157bc60",
      "price": null,
      "language_code": "en",
      "entity_type": "merchant",
      "entity_pk": "529a8212-0851-4a38-a334-3c0558570fdf",
      "google_category_specific_id": 1001502,
      "intent_id": 433982
    },
    {
      "title": "Financing Vertu phone vertu.com US",
      "short_description": "Buy Vertu phone with financing in the US via vertu.com US",
      "link": "https://ztent.ai/g/6dd2a16b0ba45b858a77",
      "price": null,
      "language_code": "en",
      "entity_type": "merchant",
      "entity_pk": "da0e0384-0c6c-4cda-b179-4af3a205a8b8",
      "google_category_specific_id": 1001502,
      "intent_id": 476501
    }
  ],
  "debug_info": {
    "source_id": "f2dec457-da5d-46fc-b810-645b0f8a3fdf",
    "query_text": "Apple phone buy",
    "country_id": "US",
    "language_id": "en",
    "ads_limit": 3,
    "is_profitable": true,
    "profitable_score": "0.71",
    "result_ads_count": 3,
    "intents_with_degradated_filters": [
      {
        "intent": {
          "intent_id": 685550,
          "intent_text": "where can I buy iPhone near me",
          "score": 0.72989637,
          "google_categories_ids": [
            1001502
          ],
          "disambiguation_score": 2.02697277,
          "google_categories": [
            {
              "pk": 1001502,
              "name": "Hardware Stores"
            }
          ]
        },
        "degradated_filters": []
      },
      {
        "intent": {
          "intent_id": 433982,
          "intent_text": "buy used iPhone from Hong Kong HK Resale shipping to US",
          "score": 0.6588867,
          "google_categories_ids": [
            1001502
          ],
          "disambiguation_score": 2.02697277,
          "google_categories": [
            {
              "pk": 1001502,
              "name": "Hardware Stores"
            }
          ]
        },
        "degradated_filters": []
      },
      {
        "intent": {
          "intent_id": 476501,
          "intent_text": "buy Vertu phone with financing US",
          "score": 0.6381897,
          "google_categories_ids": [
            1001502
          ],
          "disambiguation_score": 2.02697277,
          "google_categories": [
            {
              "pk": 1001502,
              "name": "Hardware Stores"
            }
          ]
        },
        "degradated_filters": []
      }
    ],
    "slots": []
  }
}

Integration Examples

Example patterns for different surfaces using the same API.

These integrations reflect the currently supported surfaces. The REST API is production-ready, while the SDK and additional widgets are still being finalized.

Suggest (search dropdown)

suggest.js

const res = await fetch('https://app.zyntent.ai/public_api/v1/ads/search/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    source_id: 'SITE_ID',
    query: { text: userQuery },
    country: 'US',
    ads_limit: 3,
    metadata: { surface: 'suggest', input_id: 'search-box' }
  })
})
const { ads } = await res.json()
renderSuggestAds(ads)

LLM App (assistant response)

llm-app.ts

const ads = await zyntentAds({
  source_id: 'SITE_ID',
  query: { text: userPrompt },
  country: 'US',
  ads_limit: 2,
  metadata: { surface: 'llm', message_id: llmMessageId }
})

const assistantReply = formatLLMResponse({
  answer: llmAnswer,
  sponsored: ads
})

Domain Parking

domain-parking.js

fetch('https://app.zyntent.ai/public_api/v1/ads/search/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    source_id: 'SITE_ID',
    query: { text: 'best coffee machines' },
    country: 'US',
    ads_limit: 3,
    metadata: { surface: 'domain', domain: location.hostname }
  })
}).then(r => r.json()).then(({ ads }) => renderDomainAds(ads))

Browser Extension

extension.js

const query = window.getSelection().toString() || document.title
const res = await fetch('https://app.zyntent.ai/public_api/v1/ads/search/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    source_id: 'SITE_ID',
    query: { text: query },
    country: 'US',
    ads_limit: 1,
    metadata: { surface: 'browser', page_url: location.href }
  })
})
const { ads } = await res.json()
showBrowserPanel(ads[0])

Configuration

Customize SDK behavior via data attributes or the JavaScript API.

config.html

<script
  src="https://sdk.zyntent.com/v1/zyntent.js"
  data-site-id="YOUR_SITE_ID"
  data-theme="dark"
  data-brand-safety="strict"
  data-max-ads-per-page="3"
  data-locale="en-US"
  data-debug="false"
  async
></script>

config.ts

// JavaScript API configuration
window.zyntent?.configure({
  theme: 'dark',            // 'light' | 'dark' | 'auto'
  brandSafety: 'strict',    // 'strict' | 'standard' | 'permissive'
  maxAdsPerPage: 3,
  locale: 'en-US',
  onAdLoad: (ad) => {
    console.log('Ad loaded:', ad.id, ad.headline)
  },
  onAdClick: (ad) => {
    console.log('Ad clicked:', ad.id)
  },
  onError: (error) => {
    console.error('Zyntent error:', error.message)
  },
})

Analytics

Track performance in real time via our dashboard or API.

Available Metrics

Impressions

Total ads shown

Clicks

Total ad clicks

CTR

Click-through rate

Revenue

Total earnings

eCPM

Effective CPM

Fill Rate

Ads served / requested

Latency

Avg ad load time

Intent Score

Avg intent confidence

analytics-response.json

{
  "period": "7d",
  "impressions": 1247832,
  "clicks": 62391,
  "ctr": 0.05,
  "revenue_usd": 18426.5,
  "ecpm": 14.76,
  "fill_rate": 0.94,
  "avg_latency_ms": 43,
  "avg_intent_score": 0.87
}

Need help?

Our engineering team can help you with integration and setup.

Integrate Zyntent

Quick Start

Installation

Script Tag (recommended)

REST API

NPM Package

Ad Surfaces

Surface Attributes

Ad Formats

REST API

POST /public_api/v1/ads/search/

Debug mode

Integration Examples

Suggest (search dropdown)

LLM App (assistant response)

Domain Parking

Browser Extension

Configuration

Analytics

Available Metrics

Need help?