API Technical specifications

The technical specifications of the Authentic Discovery^TM API 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

Parameters and Headers

ℹ️
Note:
Parameters marked with an asterisk (*) are mandatory.

Parameter	Placement	Description	Example
`client-id`(*)	Path	Bazaarvoice client instance name as registered in the Bazaarvoice Portal. If not passed, the API returns a result for the client instance associated with the API Passkey passed in the header.
`productId`(*)	Query	Use the `productId` from the Bazaarvoice product catalog for the client instance. Note: Ensure the product-Id matches the one saved in the Bazaarvoice product catalog.	P-7777-MSD
`Bv-Passkey`(*)	Header	An Authentic Discovery API passkey for authentication. This is a query parameter, which is a part of the request URL
`User-Agent` (Recommended)	Header	Ensure the User-Agent header reflects the actual entity (browser or crawler) requesting the PDP. This implementation is critical for clients who need to track and verify how different AI bots are crawling their content.	Java-http-client/17.0.7'
`Accept`	Header	To ensure the API returns the correct response, the `Accept` header should be set to `text/*`. By default, the API returns text/javascript. If no header is provided, the API will fall back to the default text/javascript format.	text/javascript Other available types: "text/*", "text/javascript", "text/html", "application/ld+json".
`canonical`	Query	The exact identifier string used in your Product Schema's @id field. Important: This value is used to populate itemReviewed @id. For search engines to associate these reviews with your product, the string you send here must be identical (character-for-character) to the @id you assign to the Product object in your own schema generation.	https://www.example.com/products/running-shoe#product Recommended format: Product Canonical URL + #product fragment.
`locale`(*)	Query	Locale to display Labels, Configuration, Product Attributes and Category Attributes. The default value is the locale associated with the API key.	en_US Format: languageCode_countryCode Any other format will return a bad request response.
`siteId` (Recommended)	Query	Site ID of the implementation. The default value is the main_site	main_site
`q`	Query	The `q` parameter accepts a JSON object specifying which markup schemas should be included in the response. The API supports five schema types: reviews, ratings, questions, reviewSummary. and galleries Default behavior: If `q` is omitted, the API returns reviews and ratings by default. Customization: You can pass filters within each schema object to refine and control the data.	`{ "reviews": { "filter": [ "productid:eq:product1,contentLocale:eq:en_US" ], "limit": "1", "offset": "0", "sort": "submissiontime:desc", "excludeFamily": true, "bvstate": "pg:2&ct:r" }, "ratings": { "filter": [ "id:eq:product1" ] }, "questions": { "filter": [ "productid:eq:product1" ], "include": "answers", "sort": "submissiontime:desc", "limit": 1, "offset": 0 }, "reviewSummary": {}, "galleries": [ { "dataSourceId": "<DATA-SOURCE-ID>", "limit": 10, "sort": "Latest" } ] }`
`Bv-Forwarded-User-Agent`	Header	The original User-Agent from the AI crawler's request Note: This parameter is crucial for clients who need to monitor the crawlability of their content by various AI bots.	Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot

Headers

Header	Required	Description
`Bv-Passkey`(*)	Yes	The GEO-only Authentic Discover API passkey (authentication).
`User-Agent`	Recommended	Reflects the requesting entity; used to track which bots crawl.
`Bv-Forwarded-User-Agent`	Recommended	The original AI crawler’s User-Agent, for crawl monitoring.
`Accept`	Optional	Response format. See the Response formats table.

Response formats (Accept header)

Optional. If omitted, defaults to text/javascript.

Accept value	Returns	Use When?
`text/javascript` (default)	A ready-to-embed <script type="application/ld+json"> tag.	Recommended. Embed directly in HTML, no modification.
`application/ld+json`	Raw markup objects as JSON.	You want to merge it into your own Product schema programmatically.
`text/html`	HTML with inline microdata attributes.	JSON-LD is unsuitable for your environment; add as hidden PDP content.

Request query parameters (q)

Parameter	Input schema	Description
`filter`	ratings, reviews, questions, galleries	Filter criteria for the primary content of the query. For reviews/ratings/questions this is an array of `field:op:value` strings and multiple criteria are supported. For galleries, `filter` is a single string in the form `field:value` (for example, `productId:leather-jacket`). Please refer to media filters documentation Social Commerce API (For Vibe clients only).
`excludeFamily`	ratings, reviews, questions	Boolean flag indicating whether to exclude content (reviews, questions, etc.) from other products in the same family as the requested product. This setting only affects any nested content that is returned. For example, `&filter=productid:eq:1101&include=reviews&excludeFamily=true` limits returned review content to just that of product 1101 and not any of the products in the same family. If a value is not defined, content on all products in the family is returned.
`sort`	reviews, questions, galleries	Sort criteria for the primary content type of the query. Sort order is required (ascending or descending). Multi-attribute sorting for each content/subject type (except galleries) is supported. For galleries, `sort` accepts one of a fixed set of values: `Latest`, `Likes`, `Moderation`, `Optimized`, `LastUpdated`.
`limit`	reviews, questions, galleries	Maximum number of records returned. For reviews/questions an error is returned if the value exceeds 100.
`offset`	reviews, questions, galleries	Index at which to return results. By default, indexing begins at 0. When you issue a query. Using `Limit=100`, `Offset=0` returns results 0-99. When changing this to `Offset=1`, results 1-100 are returned. The maximum supported value is 300000 (not applicable for galleries).
`locale`	reviews, questions	Locale in which display labels, configuration, product attributes, and category attributes are displayed.
`language`	reviewSummary	Language of the AI-generated review summary (`en`, `de`, `es`, or `fr`).
`dataSourceId` (required for galleries only)	galleries	Unique gallery ID that identifies the media data source. Example: `DKQGLerBTQCDXwNS`. Required for every object in the `galleries` array.
`before`	galleries	Cursor for pagination. Returns items positioned before the supplied cursor.
`after`	galleries	Cursor for pagination. Returns items positioned after the supplied cursor.
`requireProduct`	galleries	Boolean. When `true`, only returns media items that have an associated product. Example: `true`.
`networkSource`	galleries	Restricts results to a single social/import source. One of: `Pinterest`, `Facebook`, `Instagram`, `Twitter`, `Tumblr`, `Snapchat`, `TikTok`, `YouTube`, `MediaImport`.
`noExpired`	galleries	Boolean. When `true`, excludes expired media items. Defaults to `false`.

ℹ️
Format differences to note for galleries

filter is a single string (productId:leather-jacket), not the array/field:op:value form used by reviews, ratings, and questions.

sort uses a fixed keyword set (Latest, Likes, Moderation, Optimized, LastUpdated), not the field:direction form.

You must supply a dataSourceId. See the Media / Galleries configuration to obtain your gallery IDs.

Content types returned

Content type	Description	Default?
Ratings	Overall star rating and total review count (AggregateRating).	Yes
Reviews	Individual reviews: rating, body, author, dates, images, videos.	Yes
AI-generated Review Summary	AI summary returned as a Review object when available.	Opt-in via `q`
Questions & Answers	Q&A content as FAQPage schema.	Opt-in via `q`

Schema Reference

Review (@type: Review): dateCreated, datePublished, reviewBody, name, reviewRating (Rating: ratingValue, bestRating, worstRating), author (Person or Organization), optional image (ImageObject array) and video (VideoObject array).

An additionalProperty array carrying Bazaarvoice-configured contextual attributes — trust badges (Verified Purchaser, Incentivized, Staff, Expert, Top Contributor tiers), secondary ratings (Quality, Value, Fit, Comfort, Appearance), and product questions (Best Uses, Length of Ownership).

These fields surface review context that was previously only rendered in the display layer, giving AI crawlers and search engines richer signals for persona-matching and trust-scoring; the change is purely additive, enabled by default for all Authentic Discovery API clients, and only fields enabled in your Bazaarvoice display configuration are emitted.

📘
Only Bazaarvoice-configured fields that provide relevant contextual data are included.

Caveats:

Pros & Cons are added as positiveNotes and negativeNotes directly on the Review object. These are spec-valid Schema.org Review properties and are handled separately from the additionalProperty extension.
additionalProperty is not a spec-valid Schema.org Review property. This is a known limitation. It will not be penalised for SEO. The primary intent is to surface contextual information for LLM crawlers that read page text; it does not guarantee all data will be understood by every crawler
People questions and answers are NOT included in schema markup. Our current system adds product attribute questions/answers, secondary ratings, and badges (subject to visibility/config rules). This avoids exposing personal data (e.g., age, gender, body type) via structured data.

Any custom question in review submission form created by Client will not be added to the SEO markup.

Supported additionalProperty Schema Fields:

Field	Type of data
Verified Purchaser	Badge
Incentivized Review	Badge
Staff Reviewer	Badge
Expert Badge	Badge
Top Contributor	Badge
Top 10 Contributor	Badge
Top 25 Contributor	Badge
Top 50 Contributor	Badge
Top 100 Contributor	Badge
Top 250 Contributor	Badge
Top 500 Contributor	Badge
Top 1000 Contributor	Badge
Quality Rating	SecondaryRating
Value Rating	SecondaryRating
Fit	SecondaryRating
Comfort	SecondaryRating
Appearance	SecondaryRating
LengthOfOwnership	Product Question

AggregateRating (@type: AggregateRating): bestRating, ratingValue, reviewCount.
FAQPage (Q&A): mainEntity is an array of Question objects, each with name, dateCreated, author, answerCount, and one acceptedAnswer (Answer with text, dateCreated, author, upvoteCount).
AI Summary: returned as a Review whose author is an Organization named "AI Review Summary".

acceptedAnswer selection priority:
1. an answer from the client/brand, then
2. the answer with the most positive feedback, then
3. the most recent answer.

Sample request

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: ...compatible; GPTBot/1.1; +https://openai.com/gptbot' \
  --header 'Bv-Passkey: <PASSKEY>'

Sample Response (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"
      },
       "@id": "https://example.com/productId/product1#2784681771",
       "additionalProperty": [
         {
            "@type": "PropertyValue",
            "name": "Best Uses - Telecom",
            "value": "Office Use"
          },
          {
            "@type": "PropertyValue",
            "name": "Quality of Product",
            "value": "4",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Value of Product",
            "value": "5",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Comfort",
            "value": "5",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Length of ownership",
            "value": "3 months"
          }
        ],

      "image": [
        {
          "@type": "ImageObject",
          "description": "normal",
          "contentUrl": "https://photos-cert-eu.bazaarvoice.com/photo/2/cGhvdG86dGVzdGN1c3RvbWVyLWZhc3QtcHJz/c4f2df63-64db-5ef2-8673-33ab2a4302e4"
        }
      ],
      "positiveNotes": {
          "@type": "ItemList",
          "itemListElement": [
            {
              "@type": "ListItem",
              "position": 1,
              "name": "Example Pros 1"
            },
            {
              "@type": "ListItem",
              "position": 2,
              "name": "Example Pros 2"
            },
            {
              "@type": "ListItem",
              "position": 3,
              "name": "Example Pros 3"
            }
          ]
        },
        "negativeNotes": {
          "@type": "ItemList",
          "itemListElement": [
            {
              "@type": "ListItem",
              "position": 1,
              "name": "Example Cons 1"
            },
            {
              "@type": "ListItem",
              "position": 2,
              "name": "Example Cons 2"
            }
          ]
        },
       "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
  }
}
</script>

Errors & common causes

Symptom	Cause
Empty or incorrect markup	productId does not match the Bazaarvoice catalog.
401 / authentication error	Wrong or unapproved passkey, or a non-GEO key.
Bad request on every call	Malformed locale (must be languageCode_countryCode).
Duplicate markup warnings	Client-side SEO still active alongside the server-side markup.
Reviews not linked to product	@id / canonical mismatch.
Nothing returns / unavailable	Package not eligible, or account on legacy PRR platform.
limit error	q limit value exceeds 100.

Constraints

Available to Enterprise accounts (rollout to Advanced/Essentials planned — confirm eligibility).
Requires the current Conversations platform. Legacy PRR is not supported.
Requires a GEO-only Authentic Discovery API key, approved by a Technical Administrator.
q limit ≤ 100; offset ≤ 300000.

Validation tools

Google Rich Results Test

Endpoint

HTTPS method

Parameters and Headers

Note:

Headers

Response formats (Accept header)

Request query parameters (q)

Format differences to note for galleries

Content types returned

Schema Reference

Only Bazaarvoice-configured fields that provide relevant contextual data are included.

Sample request

Sample Response (JSON-LD Format)

Errors & common causes

Constraints

Validation tools

What’s Next