Bazaarvoice Clients API
The Clients API from Bazaarvoice — 1 operation(s) for clients.
The Clients API from Bazaarvoice — 1 operation(s) for clients.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/bazaarvoice-clients-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
title: Bazaarvoice Clients API
x-refined-note:
- x-api-id differs across the merged source definitions and was not carried
- x-audience differs across the merged source definitions and was not carried
version: '1.0'
description: 'Operations tagged Clients across 2 of this provider''s published API definitions: bazaarvoice-authentic-discovery-openapi.yml, bazaarvoice-clients-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://seo-stg.bazaarvoice.com/structured-data/v1
description: Staging Server
- url: https://seo.bazaarvoice.com/structured-data/v1
description: Production Server
- url: https://content-search.eu-west-1a.bosun.qa.bazaarvoice.com/
description: QA | Content Search
tags:
- name: Clients
paths:
/clients/{clientId}/ugc:
get:
summary: Fetch Structured Data (JSON-LD or Microdata)
description: Retrieves structured data for a specific product. This is the recommended endpoint that accepts productId as a query parameter.
operationId: getStructuredDataV2
security:
- Bv-passkey: []
parameters:
- name: clientId
in: path
description: The name of the client. Can contain special characters.
required: true
schema:
type: string
example: yourclientid
- name: productId
in: query
description: The ID of the product. Can contain special characters.
required: true
schema:
type: string
example: product1
- name: Bv-Forwarded-User-Agent
in: header
description: Clients will need to send User-Agent of consumers accessing the PDP page
required: false
schema:
type: string
pattern: ^[a-zA-Z0-9\s\(\)\[\]\{\}\/\.\-_;:,+]+$
minLength: 10
maxLength: 500
example: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot
- name: User-Agent
in: header
description: Clients will need to send User-Agent of their backend http client
required: false
schema:
type: string
pattern: ^[a-zA-Z0-9\s\(\)\[\]\{\}\/\.\-_;:,+]+$
minLength: 10
maxLength: 500
example: Apache-HttpClient/4.5.8 (Java/1.8.0_191)
- name: Accept
in: header
description: Accept header must be empty or omitted. The API will return the default content type (text/javascript) for now, in future this might change.
required: false
schema:
type: string
maxLength: 0
example: ''
- name: q
in: query
description: 'A JSON-encoded query object containing parameters for various content types. Refer to Bazaarvoice CV2 documentation for specific filter and sort values.
'
required: false
content:
application/json:
schema:
type: object
properties:
reviews:
type: object
additionalProperties: true
properties:
filter:
type: array
description: Filter criteria for primary content of the query. Multiple filter criteria are supported.
items:
type: string
limit:
type: string
description: Max number of records returned. An error is returned if the value passed exceeds 100.
offset:
type: string
description: 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.
sort:
type: string
description: Sort criteria for primary content of the query. Multiple sort criteria are supported.
excludeFamily:
type: boolean
description: Boolean flag indicating whether to exclude content from other products in the same family as the requested product.
ratings:
type: object
properties:
filter:
type: array
description: Filter criteria for primary content of the query. Multiple filter criteria are supported.
items:
type: string
questions:
type:
- object
- 'null'
properties:
filter:
type: array
description: Filter criteria for primary content of the query. Multiple filter criteria are supported.
items:
type: string
include:
type: string
description: Additional content to include in the query response. Mostly used to include answers with questions.
sort:
type: string
description: Sort criteria for primary content type of the query. Sort order is required (asc or desc).
limit:
type: integer
description: Max number of records returned. An error is returned if the value passed exceeds 100.
offset:
type: integer
description: 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.
reviewSummary:
type:
- object
- 'null'
galleries:
type: array
description: Gets media items for a data source
items:
type: object
required:
- dataSourceId
properties:
dataSourceId:
type: string
description: Unique gallery ID.
example: DKQGLerBTQCDXwNS
filter:
type: string
description: Filters the requested content.
example: productId:leather-jacket
sort:
type: string
enum:
- Latest
- Likes
- Moderation
- Optimized
- LastUpdated
limit:
type: integer
format: int64
example: 10
before:
type: string
description: Cursor for pagination.
after:
type: string
description: Cursor for pagination.
offset:
type: integer
format: int64
example: 10
requireProduct:
type: boolean
description: Only return items with products.
example: true
networkSource:
type: string
enum:
- Pinterest
- Facebook
- Instagram
- Twitter
- Tumblr
- Snapchat
- TikTok
- YouTube
- MediaImport
example: Instagram
noExpired:
type: boolean
default: false
example:
reviews:
filter:
- productid:eq:product1,contentLocale:eq:en_US
limit: '1'
offset: '0'
sort: submissiontime:desc
excludeFamily: true
ratings:
filter:
- id:eq:product1
questions:
filter:
- productid:eq:product1
include: answers
sort: submissiontime:desc
limit: 1
offset: 0
reviewSummary:
language: ar
galleries:
- dataSourceId: DKQGLerBTQCDXwNS
limit: 10
sort: Latest
- name: canonical
in: query
required: false
schema:
type: string
format: uri
description: The exact identifier string used in your Product Schema's `@id` field. **CRITICAL REQUIREMENT:** 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. **Recommended Format:** Product Canonical URL + `#product` fragment.
example: https://www.example.com/running-shoe#product
- name: locale
in: query
description: Locale to display Labels, Configuration, Product Attributes and Category Attributes in. The default value is the locale defined in the display associated with the API key.
required: true
schema:
type: string
example: en_US
- name: siteId
in: query
description: Site ID of the implementation, default will be main_site
required: false
schema:
type: string
example: main_site
responses:
'200':
description: 'Returns JSONLD by default for reviews and ratings.
'
headers:
Vary:
description: Indicates which request headers affect the response
schema:
type: string
example: Origin, Accept-Encoding, Accept
Cache-Control:
description: Caching directives (default 55 minutes)
schema:
type: string
example: public, max-age=3300
content:
application/ld+json:
schema:
$ref: '#/components/schemas/JsonLdResponseJSONFormat'
text/javascript:
schema:
$ref: '#/components/schemas/JsonLdResponseScript'
text/html:
schema:
$ref: '#/components/schemas/MicrodataResponse'
'400':
description: Bad Request, Validation failed for the request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /problems/bad-request
title: Bad Request
status: 400
detail: Bv-passkey is required
instance: /clients/{clientId}/ugc
text/html:
schema:
type: string
example: "<html>\n <head><title>400 Bad Request</title></head>\n <body>\n <h1>Bad Request</h1>\n <p><strong>Status:</strong> 400</p>\n <p><strong>Detail:</strong> Bv-passkey is required</p>\n <p><strong>Type:</strong> /problems/bad-request </p>\n <p><strong>Instance:</strong> /clients/{clientId}/ugc</p>\n </body>\n</html>\n"
text/javascript:
schema:
type: string
example: "<script type=\"application/json\" id=\"bv-error-data\">\n{\n \"type\": \"/problems/bad-request\",\n \"status\": 400,\n \"title\": \"Bad Request\",\n \"detail\": \"Bv-passkey is required\",\n \"instance\": \"/clients/{clientId}/ugc\"\n}\n</script>\n"
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /problems/unauthorized
title: Unauthorized
status: 401
detail: Invalid Bv-passkey
instance: /clients/{clientId}/ugc
text/html:
schema:
type: string
example: "<html>\n <head><title>401 Unauthorized</title></head>\n <body>\n <h1>Unauthorized</h1>\n <p><strong>Status:</strong> 401</p>\n <p><strong>Detail:</strong> Invalid Bv-passkey</p>\n <p><strong>Type:</strong> /problems/unauthorized</p>\n <p><strong>Instance:</strong> /clients/{clientId}/ugc</p>\n </body>\n</html>\n"
text/javascript:
schema:
type: string
example: "<script type=\"application/json\" id=\"bv-error-data\">\n{\n \"type\": \"/problems/unauthorized\",\n \"status\": 401,\n \"title\": \"Unauthorized\",\n \"detail\": \"Invalid Bv-passkey\",\n \"instance\": \"/clients/{clientId}/ugc\"\n}\n</script>\n"
default:
description: Internal Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /problems/unexpected-error
title: Internal Server Error
status: 500
detail: Internal Server Error
instance: /clients/{clientId}/ugc
text/html:
schema:
type: string
example: "<html>\n <head><title>500 Internal Server Error</title></head>\n <body>\n <h1>Internal Server Error</h1>\n <p><strong>Status:</strong> 500</p>\n <p><strong>Detail:</strong> Internal Server Error</p>\n <p><strong>Type:</strong>/problems/unexpected-error</p>\n <p><strong>Instance:</strong> /clients/{clientId}/ugc</p>\n </body>\n</html>\n"
text/javascript:
schema:
type: string
example: "<script type=\"application/json\" id=\"bv-error-data\">\n {\n \"type\": \"/problems/unexpected-error\",\n \"status\": 500,\n \"title\": \"Internal Server Error\",\n \"detail\": \"Internal Server Error\",\n \"instance\": \"/clients/{clientId}/ugc\"\n }\n</script>\n"
tags:
- Clients
servers:
- url: https://seo-stg.bazaarvoice.com/structured-data/v1
description: Staging Server
- url: https://seo.bazaarvoice.com/structured-data/v1
description: Production Server
/clients/{client-id}/ugc:
get:
summary: Fetch Structured Data (JSON-LD or Microdata)
description: Retrieves structured data for a specific product. This is the recommended endpoint that accepts product-id as a query parameter.
operationId: getStructuredDataV2
security:
- Bv-Passkey: []
parameters:
- name: client-id
in: path
description: The name of the client. Can contain special characters.
required: true
schema:
type: string
example: yourclientid
- name: productId
in: query
description: The ID of the product. Can contain special characters.
required: true
schema:
type: string
example: product1
- name: Bv-Forwarded-User-Agent
in: header
description: Clients will need to send User-Agent of consumers accessing the PDP page
required: false
schema:
type: string
example: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot
- name: User-Agent
in: header
description: Clients will need to send User-Agent of their backend http client
required: false
schema:
type: string
pattern: ^[a-zA-Z0-9\s\(\)\[\]\{\}\/\.\-_;:,+]+$
minLength: 10
maxLength: 500
example: Apache-HttpClient/4.5.8 (Java/1.8.0_191)
- name: Accept
in: header
description: Accept header must be empty or omitted. The API will return the default content type (text/javascript) for now, in future this might change.
required: false
schema:
type: string
maxLength: 0
example: ''
- name: q
in: query
description: 'A JSON-encoded query object containing parameters for various content types. Refer to Bazaarvoice CV2 documentation for specific filter and sort values.
'
required: false
content:
application/json:
schema:
type: object
properties:
reviews:
type: object
additionalProperties: true
properties:
sort:
type: string
filter:
type: array
items:
type: string
limit:
type: string
offset:
type: string
ratings:
type: object
properties:
filter:
type: array
items:
type: string
questions:
type:
- object
- 'null'
reviewSummary:
type:
- object
- 'null'
example:
reviews:
filter:
- productid:eq:product1
limit: '1'
offset: '0'
sort: submissiontime:desc
- name: canonical
in: query
required: false
schema:
type: string
format: uri
description: The exact identifier string used in your Product Schema's `@id` field. **CRITICAL REQUIREMENT:** 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. **Recommended Format:** Product Canonical URL + `#product` fragment.
example: https://www.example.com/running-shoe#product
- name: locale
in: query
description: Locale to display Labels, Configuration, Product Attributes and Category Attributes in. The default value is the locale defined in the display associated with the API key.
required: true
schema:
type: string
example: en_US
- name: siteId
in: query
description: Site ID of the implementation, default will be main_site
required: false
schema:
type: string
example: main_site
responses:
'200':
description: 'Returns JSONLD by default for reviews and ratings.
'
headers:
Vary:
description: Indicates which request headers affect the response
schema:
type: string
example: Origin, Accept-Encoding, Accept
Cache-Control:
description: Caching directives (default 55 minutes)
schema:
type: string
example: public, max-age=3300
content:
application/ld+json:
schema:
$ref: '#/components/schemas/JsonLdResponseJSONFormat_2'
text/javascript:
schema:
$ref: '#/components/schemas/JsonLdResponseScript_2'
text/html:
schema:
$ref: '#/components/schemas/MicrodataResponse_2'
'400':
description: Bad Request, Validation failed for the request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /problems/bad-request
title: Bad Request
status: 400
detail: Bv-passkey is required
instance: /clients/clientid/ugc
text/html:
schema:
type: string
example: "<html>\n <head><title>400 Bad Request</title></head>\n <body>\n <h1>Bad Request</h1>\n <p><strong>Status:</strong> 400</p>\n <p><strong>Detail:</strong> Bv-passkey is required</p>\n <p><strong>Type:</strong> /problems/bad-request </p>\n <p><strong>Instance:</strong> /clients/clientid/ugc</p>\n </body>\n</html>\n"
text/javascript:
schema:
type: string
example: "<script type=\"application/json\" id=\"bv-error-data\">\n{\n \"type\": \"/problems/bad-request\",\n \"status\": 400,\n \"title\": \"Bad Request\",\n \"detail\": \"Bv-Passkey is required\",\n \"instance\": \"/clients/clientid/ugc\"\n}\n</script>\n"
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /problems/unauthorized
title: Unauthorized
status: 401
detail: Invalid Bv-Passkey
instance: /clients/clientid/ugc
text/html:
schema:
type: string
example: "<html>\n <head><title>401 Unauthorized</title></head>\n <body>\n <h1>Unauthorized</h1>\n <p><strong>Status:</strong> 401</p>\n <p><strong>Detail:</strong> Invalid Bv-Passkey</p>\n <p><strong>Type:</strong> /problems/unauthorized</p>\n <p><strong>Instance:</strong> /clients/clientid/ugc</p>\n </body>\n</html>\n"
text/javascript:
schema:
type: string
example: "<script type=\"application/json\" id=\"bv-error-data\">\n{\n \"type\": \"/problems/unauthorized\",\n \"status\": 401,\n \"title\": \"Unauthorized\",\n \"detail\": \"Invalid Bv-Passkey\",\n \"instance\": \"/clients/clientid/ugc\"\n}\n</script>\n"
default:
description: Internal Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: /problems/unexpected-error
title: Internal Server Error
status: 500
detail: Internal Server Error
instance: /clients/clientid/ugc
text/html:
schema:
type: string
example: "<html>\n <head><title>500 Internal Server Error</title></head>\n <body>\n <h1>Internal Server Error</h1>\n <p><strong>Status:</strong> 500</p>\n <p><strong>Detail:</strong> Internal Server Error</p>\n <p><strong>Type:</strong>/problems/unexpected-error</p>\n <p><strong>Instance:</strong> /clients/clientid/ugc</p>\n </body>\n</html>\n"
text/javascript:
schema:
type: string
example: "<script type=\"application/json\" id=\"bv-error-data\">\n {\n \"type\": \"/problems/unexpected-error\",\n \"status\": 500,\n \"title\": \"Internal Server Error\",\n \"detail\": \"Internal Server Error\",\n \"instance\": \"/clients/clientid/ugc\"\n }\n</script>\n"
tags:
- Clients
servers:
- url: https://content-search.eu-west-1a.bosun.qa.bazaarvoice.com/
description: QA | Content Search
- url: https://seo-stg.bazaarvoice.com/structured-data/v1
description: Staging Server
- url: https://seo.bazaarvoice.com/structured-data/v1
description: Production Server
components:
schemas:
ErrorResponse:
type: object
required:
- type
- title
- status
- detail
- instance
properties:
type:
type: string
format: uri-reference
title:
type: string
status:
type: integer
format: int32
detail:
type: string
instance:
type: string
MicrodataResponse:
type: string
description: HTML containing Microdata tags. Review schema - https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#review-schema-type-review , Aggregate Rating schema - https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#aggregaterating-schema-type-aggregaterating
example: "<div itemscope itemtype=\"https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#review-schema-type-review\" itemid=\"https://example.com/product\">\n <h1 itemprop=\"name\">Acne Patches</h1>\n <div itemprop=\"aggregateRating\" itemscope itemtype=\"https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#aggregaterating-schema-type-aggregaterating\">\n Rated \n <span itemprop=\"ratingValue\">4.7</span> out of \n <span itemprop=\"bestRating\">5</span> based on \n <span itemprop=\"reviewCount\">873</span> reviews.\n </div>\n</div>\n"
JsonLdResponseScript:
type: string
description: JSON-LD structured data object inside script tag which abides to google defined schema.org. Our Review schema - https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#review-schema-type-review, Aggregate Rating schema - https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#aggregaterating-schema-type-aggregaterating
example: "<script type=\"application/ld+json\">\n{\n \"@context\": \"https://schema.org/\",\n \"@id\": \"https://example.com/product\",\n \"aggregateRating\": {\n \"@type\": \"AggregateRating\",\n \"ratingValue\": \"4.7\",\n \"reviewCount\": 873,\n \"bestRating\": 5\n }\n}\n</script>\n"
JsonLdResponseJSONFormat:
type: object
description: JSON-LD structured data object inside script tag
properties:
reviews:
type: object
description: contains schema outlined at https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#review-schema-type-review
questions:
type: object
description: contains schema outlined at https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#question-properties
ratings:
type: object
description: contains schema outlined at https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#aggregaterating-schema-type-aggregaterating
reviewSummary:
type: object
description: contains schema outlined at https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#ai-summary-schema
galleries:
type: array
description: Gallery structured data appended to the response based on the requested Accept format.
items:
type: object
description: Schema.org structured data object for a single gallery, produced by the Media API.
example:
ratings:
'@context': https://schema.org/
'@id': https://example.com/product
aggregateRating:
'@type': AggregateRating
ratingValue: '4.7'
reviewCount: 873
bestRating: 5
galleries:
- '@context': https://schema.org
'@type': ItemList
name: Visual Gallery
numberOfItems: 97
itemListElement:
- '@type': ListItem
position: 1
item:
'@type': ImageObject
name: Featuring Sandals
contentUrl: https://example.com/image1.jpg
- '@type': ListItem
position: 2
item:
'@type': ImageObject
name: Featuring Boots
contentUrl: https://example.com/image2.jpg
MicrodataResponse_2:
type: string
description: HTML containing Microdata tags. Review schema - https://schema.org/Review , Aggregate Rating schema - https://schema.org/AggregateRating
example: "<div itemscope itemtype=\"https://schema.org/IndividualProduct\" itemid=\"https://www.example.com/skincare/acne/blemish-patches\">\n <h1 itemprop=\"name\">Acne Patches</h1>\n <div itemprop=\"aggregateRating\" itemscope itemtype=\"https://schema.org/AggregateRating\">\n Rated \n <span itemprop=\"ratingValue\">4.7</span> out of \n <span itemprop=\"bestRating\">5</span> based on \n <span itemprop=\"reviewCount\">873</span> reviews.\n </div>\n</div>\n"
JsonLdResponseScript_2:
type: string
description: JSON-LD structured data object inside script tag, Review schema - https://schema.org/Review , Aggregate Rating schema - https://schema.org/AggregateRating
example: "<script type=\"application/ld+json\">\n{\n \"@context\": \"https://schema.org/\",\n \"@id\": \"https://www.example.com/skincare/acne/blemish-patches\",\n \"aggregateRating\": {\n \"@type\": \"AggregateRating\",\n \"ratingValue\": \"4.7\",\n \"reviewCount\": 873,\n \"bestRating\": 5\n }\n}\n</script>\n"
JsonLdResponseJSONFormat_2:
type: object
description: JSON-LD structured data object inside script tag
properties:
reviews:
type: object
description: contains https://schema.org/Review schema in form of array
questions:
type: object
description: contains https://schema.org/FAQPage
ratings:
type: object
description: contains https://schema.org/AggregateRating
reviewSummary:
type: object
description: contains https://schema.org/Review schema in form of array
example:
ratings:
'@context': https://schema.org/
'@id': https://www.example.com/skincare/acne/blemish-patches
aggregateRating:
'@type': AggregateRating
ratingValue: '4.7'
reviewCount: 873
bestRating: 5
securitySchemes:
Bv-passkey:
type: apiKey
in: header
name: Bv-passkey
description: Authentic discovery API key for authentication
Bv-Passkey:
type: apiKey
in: header
name: Bv-Passkey
description: GEO API key for authentication
x-refined-from:
- bazaarvoice-authentic-discovery-openapi.yml
- bazaarvoice-clients-api-openapi.yml