Implementation overview

To implement Authentic Discovery API, you must

Create a Conversations API key specifically for the Authentic Discovery API .
Implement server-side API call: Implement logic to call the Authentic Discovery API only when a search engine or AI crawler visits the product detail page (PDP).
Insert the structured API response into your webpage
Verify the implementation.

Step 1: Create a Conversations API key

The Authentic Discovery API requires a dedicated Bazaarvoice Conversations API key created exclusively for SEO/GEO use.

To create a Conversations API key, follow these steps:

Sign in to Bazaarvoice Portal.
If you do not have a Portal account, ask the Account Administrator listed in your profile to create one for you. To learn more, visit the Bazaarvoice Knowledge Base.
Select the required client instance name from the Instance Selector drop-down list in the upper-right corner.
Select Settings ⚙️ and then select API under the Developer section.
Select the Request API key button.
Select the Conversations API radio button and click Next.
Select the GEO (Retrieve) only under the Access Control section.
Fill out the request form to request a new API key. After submitting, you will receive an email with the key details.
Wait for your Technical Administrator to approve the generated keys.

Step 2: Implement server-side API call

When a search engine or AI crawler visits your product detail page (PDP), implement logic to call the Bazaarvoice Authentic Discovery API once your server receives the page request.

The technical specifications are as follows:

Environment	URL
Staging	`https://seo-stg.bazaarvoice.com/structured-data/v1/clients/{client-id}/ugc`
Production	`https://seo.bazaarvoice.com/structured-data/v1/clients/{client-id}/ugc`

Endpoint

[GET]/structured=data/v1/clients/{client-id}/ugc

HTTPS method

GET

Required Headers

Bv-Passkey: YOUR_API_KEY - Your Conversations API Key

Required Query Parameters

locale: Content locale (e.g., en_US)

Sample Request (Shell)

curl --location '<https://seo.bazaarvoice.com/structured-data/v1/clients/testcustomer-fast-prs/ugc?locale=en_US&productId=product1'> \`  
`--header 'Accept: text/javascript' \`  
`--header 'User-Agent: Java-http-client/17.0.7' \`  
`--header 'Bv-Forwarded-User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot' \`  
\`--header 'Bv-Passkey: <PASSKEY>'

Sample Request (JavaScript/Node.js)

const clientId = 'your-client-id';
const productId = 'product-123';
const apiKey = process.env.BV_API_KEY;

const url = `https://seo.bazaarvoice.com/structured-data/v1/clients/${clientId}/products/${productId}/ugc?locale=en_US&siteId=main_site`;

const response = await fetch(url, {
  headers: {
    'Bv-Passkey': apiKey,
    'User-Agent': request.headers['user-agent']
  }
});

const structuredData = await response.text();

Sample Response (Default: JSON-LD Format)

<script type="application/ld+json" id="bv-jsonld-reviews-data">
{
  "@context": "https://schema.org/",
  "review": [
    {
      "@type": "Review",
      "dateCreated": "2021-04-25T16:32:07.000+00:00",
      "datePublished": "2025-10-30T06:58:22.000+00:00",
      "reviewBody": "Sample of an API review body",
      "name": "Test review Android 10 chromeTest review Android 10 chromeTe",
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": 4,
        "bestRating": 5,
        "worstRating": 1
      },
      "author": {
        "@type": "Person",
        "name": "rec88"
      },
      "image": [
        {
          "@type": "ImageObject",
          "description": "normal",
          "contentUrl": "https://photos-cert-eu.bazaarvoice.com/photo/2/cGhvdG86dGVzdGN1c3RvbWVyLWZhc3QtcHJz/c4f2df63-64db-5ef2-8673-33ab2a4302e4"
        }
      ],
      "video": [
        {
          "@type": "VideoObject",
          "description": "",
          "name": "YWhxSsj1upg",
          "thumbnailUrl": "https://www.youtube.com/watch?v=YWhxSsj1upg",
          "contentUrl": "https://www.youtube.com/watch?v=YWhxSsj1upg",
          "uploadDate": "2021-04-25T16:32:07.000+00:00",
          "thumbnail": {
            "@type": "ImageObject",
            "name": "www.youtube.com"
          }
        }
      ]
    }
  ]
}
</script>

<script type="application/ld+json" id="bv-jsonld-ratings-data">
{
  "@context": "https://schema.org",
  "aggregateRating": {
    "@type": "AggregateRating",
    "bestRating": 5,
    "ratingValue": 3.4329896907216493,
    "reviewCount": 776,
    "itemReviewed": {
      "@type": "IndividualProduct",
      "name": "Papaver orientale"
    }
  }
}
</script>

Step 3: Insert the response into your webpage

Insert the Bazaarvoice Authentic Discovery API response directly into the HTML <head> of your webpage. The API already includes the required <script type="application/ld+json"> tags, so you can embed it exactly as received without making any changes.

Example HTML template

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Product Name - Your Site</title>
  
  <!-- Bazaarvoice Structured Data (insert API response here) -->
  <!-- API returns complete script tag - no modification needed -->
  <%= bazaarvoiceStructuredData %>
  
</head>
<body>
  <!-- Your product page content -->
</body>
</html>

Step 4: Verify implementation

Execute a cURL request against the product URLs.
Set the User-Agent header to mimic a search engine (e.g., Googlebot) or an AI crawler.
Confirm the presence of the required script type="application/ld+json" tags in the response.
Verify if your product page URL passes the Google Rich Results Test.