API Technical specifications
This section outlines the technical specifications of the Authentic Discovery API.
The technical specifications of the Authentic DiscoveryTM 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
| 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 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 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: |
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 four schema types: reviews, ratings, questions, and reviewSummary. 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 specific data returned for that schema | { "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": {} } |
Headers
| Header | Required | Description |
|---|---|---|
Bv-Passkey | Yes | The GEO-only Authentic Discovery 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 | Filter criteria for primary content of the query. Multiple filter criteria are supported. |
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 | 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 is supported. |
Limit | reviews questions | Maximum number of records returned. An error is returned if the value passed exceeds 100. |
Offset | reviews questions | 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. |
Locale | reviews questions | Locale in which display labels, configuration, product attributes, and category attributes are displayed. The default value is the locale defined in the display associated with the API key. |
language | reviewSummary | Language of the AI-generated review summary (en, de, es, or fr) |
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).
-
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".
acceptedAnswerselection priority:- an answer from the client/brand, then
- the answer with the most positive feedback, then
- 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>'Tag IDs in the returned markup
| JSON-LD id (text/javascript) | Microdata id (text/html) | Content |
|---|---|---|
bv-geo-jsonld-reviews-data | bv-geo-microdata-reviews-data | Individual reviews |
bv-geo-jsonld-ratings-data | bv-geo-microdata-ratings-data | Aggregate rating & count |
bv-geo-jsonld-questions-data | bv-geo-microdata-questions-data | Q&A |
bv-geo-jsonld-reviewSummary-data | bv-geo-microdata-reviewSummary-data | AI review summary |
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-Authentic Discovery API 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.
qlimit ≤ 100; offset ≤ 300000.
Validation tools
Updated 4 days ago