> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cevoid.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Render a product Rich Snippet
> Returns visible product-rating HTML and matching Product JSON-LD.
## OpenAPI
````yaml /openapi/widget-api.json get /v1/products/{productRef}/rich-snippet
openapi: 3.0.3
info:
title: Cevoid Widget API
version: 1.0.0
servers:
- url: https://api.widget.cevoid.com
description: Production
- url: http://localhost:3007
description: Development
security: []
paths:
/v1/products/{productRef}/rich-snippet:
get:
tags:
- Storefront rendering
summary: Render a product Rich Snippet
description: Returns visible product-rating HTML and matching Product JSON-LD.
parameters:
- schema:
type: string
minLength: 1
maxLength: 256
description: >-
Stable Cevoid product or variant id, external product reference,
URL slug, or `auto` with a referer.
example: prd_linen_shirt
required: true
description: >-
Stable Cevoid product or variant id, external product reference, URL
slug, or `auto` with a referer.
name: productRef
in: path
- schema:
type: string
minLength: 1
maxLength: 128
description: >-
Workspace market short id. When omitted, Cevoid infers the market
from the referer URL.
example: mar_sweden
required: false
description: >-
Workspace market short id. When omitted, Cevoid infers the market
from the referer URL.
name: market
in: query
- schema:
type: string
minLength: 1
maxLength: 64
description: >-
Language used for market-specific product presentation, such as
`sv` or `en-US`.
example: sv-SE
required: true
description: >-
Language used for market-specific product presentation, such as `sv`
or `en-US`.
name: language
in: query
- schema:
type: string
maxLength: 2048
format: uri
description: >-
Product page URL used for `auto` product resolution and optional
market inference.
example: https://shop.example.com/products/linen-shirt
required: false
description: >-
Product page URL used for `auto` product resolution and optional
market inference.
name: referer
in: query
- schema:
type: string
maxLength: 2048
format: uri
description: Product page URL used when the referer query parameter is omitted.
example: https://shop.example.com/products/linen-shirt
required: false
description: Product page URL used when the referer query parameter is omitted.
name: referer
in: header
responses:
'200':
description: Successful response
headers:
Cevoid-Processing-Ms:
description: End-to-end request processing time in milliseconds
schema:
type: string
example: '12'
Cevoid-Request-Id:
description: Request identifier for support and tracing
schema:
type: string
example: req_abc123
RateLimit-Limit:
description: Current rate limit bucket size
schema:
type: string
example: '100'
RateLimit-Remaining:
description: Remaining requests in the current rate limit window
schema:
type: string
example: '99'
RateLimit-Reset:
description: Seconds until the next request token is available
schema:
type: integer
example: 1
Cache-Control:
description: >-
Browser freshness is 60 seconds. Shared caches are fresh for
five minutes and may serve stale content while revalidating for
another five minutes. TTL is the only invalidation guarantee;
moderation or removal may take up to ten minutes because no
active purge is performed.
schema:
type: string
example: public, max-age=60, s-maxage=300, stale-while-revalidate=300
Vary:
description: >-
Workspace credentials and both accepted referer header spellings
are included because product and Market context may be inferred
from the page URL.
schema:
type: string
example: Authorization, Referer, Referrer
content:
application/json:
schema:
type: object
properties:
html:
type: string
minLength: 1
description: >-
Visible aggregate-rating HTML rendered from the same
projection snapshot as jsonLd.
example: >-
Rated 4.8 out of 5 from 24
reviews
jsonLd:
type: object
properties:
'@context':
type: string
enum:
- https://schema.org
description: Schema.org vocabulary URL.
example: https://schema.org
'@type':
type: string
enum:
- Product
description: Schema.org entity type.
example: Product
'@id':
type: string
format: uri
description: Canonical product entity identifier.
example: >-
https://shop.example.com/products/linen-shirt#cevoid-product
url:
type: string
format: uri
description: Canonical product page URL.
example: https://shop.example.com/products/linen-shirt
name:
type: string
description: Market-specific product title.
example: Linen Shirt
image:
type: string
format: uri
description: Market-specific primary product image URL.
example: https://cdn.cevoid.com/products/linen-shirt.jpg
brand:
type: object
properties:
'@type':
type: string
enum:
- Brand
example: Brand
name:
type: string
example: Example Apparel
required:
- '@type'
- name
description: Product brand when available.
sku:
type: string
description: Product SKU when available.
example: LINEN-SHIRT-NATURAL-M
gtin:
type: string
description: Global Trade Item Number when available.
example: '07350012345678'
mpn:
type: string
description: Manufacturer Part Number when available.
example: LS-NAT-M
aggregateRating:
type: object
properties:
'@type':
type: string
enum:
- AggregateRating
example: AggregateRating
ratingValue:
type: number
minimum: 0
exclusiveMinimum: true
description: Published average rating.
example: 4.8
ratingCount:
type: integer
minimum: 0
exclusiveMinimum: true
description: Published rating count.
example: 24
bestRating:
type: number
enum:
- 5
description: Highest possible rating.
example: 5
worstRating:
type: number
enum:
- 1
description: Lowest possible rating.
example: 1
required:
- '@type'
- ratingValue
- ratingCount
- bestRating
- worstRating
required:
- '@context'
- '@type'
- '@id'
- url
- name
- aggregateRating
projectionVersion:
type: number
enum:
- 1
description: >-
Version of the authoritative review projection used for
both response representations.
example: 1
computedAt:
type: string
format: date-time
description: >-
ISO 8601 timestamp when the authoritative review
projection was computed.
example: '2026-08-01T10:05:00.000Z'
required:
- html
- jsonLd
- projectionVersion
- computedAt
example:
html: >-
Rated 4.8 out of 5 from 24
reviews
jsonLd:
'@context': https://schema.org
'@type': Product
'@id': >-
https://shop.example.com/products/linen-shirt#cevoid-product
url: https://shop.example.com/products/linen-shirt
name: Linen Shirt
image: https://cdn.cevoid.com/products/linen-shirt.jpg
brand:
'@type': Brand
name: Example Apparel
sku: LINEN-SHIRT-NATURAL-M
gtin: '07350012345678'
mpn: LS-NAT-M
aggregateRating:
'@type': AggregateRating
ratingValue: 4.8
ratingCount: 24
bestRating: 5
worstRating: 1
projectionVersion: 1
computedAt: '2026-08-01T10:05:00.000Z'
'400':
description: Bad request
headers:
Cevoid-Processing-Ms:
description: End-to-end request processing time in milliseconds
schema:
type: string
example: '12'
Cevoid-Request-Id:
description: Request identifier for support and tracing
schema:
type: string
example: req_abc123
RateLimit-Limit:
description: Current rate limit bucket size
schema:
type: string
example: '100'
RateLimit-Remaining:
description: Remaining requests in the current rate limit window
schema:
type: string
example: '99'
RateLimit-Reset:
description: Seconds until the next request token is available
schema:
type: integer
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'401':
description: Unauthorized
headers:
Cevoid-Processing-Ms:
description: End-to-end request processing time in milliseconds
schema:
type: string
example: '12'
Cevoid-Request-Id:
description: Request identifier for support and tracing
schema:
type: string
example: req_abc123
RateLimit-Limit:
description: Current rate limit bucket size
schema:
type: string
example: '100'
RateLimit-Remaining:
description: Remaining requests in the current rate limit window
schema:
type: string
example: '99'
RateLimit-Reset:
description: Seconds until the next request token is available
schema:
type: integer
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'404':
description: Not found
headers:
Cevoid-Processing-Ms:
description: End-to-end request processing time in milliseconds
schema:
type: string
example: '12'
Cevoid-Request-Id:
description: Request identifier for support and tracing
schema:
type: string
example: req_abc123
RateLimit-Limit:
description: Current rate limit bucket size
schema:
type: string
example: '100'
RateLimit-Remaining:
description: Remaining requests in the current rate limit window
schema:
type: string
example: '99'
RateLimit-Reset:
description: Seconds until the next request token is available
schema:
type: integer
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'422':
description: Validation error
headers:
Cevoid-Processing-Ms:
description: End-to-end request processing time in milliseconds
schema:
type: string
example: '12'
Cevoid-Request-Id:
description: Request identifier for support and tracing
schema:
type: string
example: req_abc123
RateLimit-Limit:
description: Current rate limit bucket size
schema:
type: string
example: '100'
RateLimit-Remaining:
description: Remaining requests in the current rate limit window
schema:
type: string
example: '99'
RateLimit-Reset:
description: Seconds until the next request token is available
schema:
type: integer
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'429':
description: Too many requests
headers:
Cevoid-Processing-Ms:
description: End-to-end request processing time in milliseconds
schema:
type: string
example: '12'
Cevoid-Request-Id:
description: Request identifier for support and tracing
schema:
type: string
example: req_abc123
RateLimit-Limit:
description: Current rate limit bucket size
schema:
type: string
example: '100'
RateLimit-Remaining:
description: Remaining requests in the current rate limit window
schema:
type: string
example: '99'
RateLimit-Reset:
description: Seconds until the next request token is available
schema:
type: integer
example: 1
Retry-After:
description: Seconds to wait before retrying the request
schema:
type: integer
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitErrorResponse'
'500':
description: Internal server error
headers:
Cevoid-Processing-Ms:
description: End-to-end request processing time in milliseconds
schema:
type: string
example: '12'
Cevoid-Request-Id:
description: Request identifier for support and tracing
schema:
type: string
example: req_abc123
RateLimit-Limit:
description: Current rate limit bucket size
schema:
type: string
example: '100'
RateLimit-Remaining:
description: Remaining requests in the current rate limit window
schema:
type: string
example: '99'
RateLimit-Reset:
description: Seconds until the next request token is available
schema:
type: integer
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'503':
description: Service unavailable
headers:
Cevoid-Processing-Ms:
description: End-to-end request processing time in milliseconds
schema:
type: string
example: '12'
Cevoid-Request-Id:
description: Request identifier for support and tracing
schema:
type: string
example: req_abc123
RateLimit-Limit:
description: Current rate limit bucket size
schema:
type: string
example: '100'
RateLimit-Remaining:
description: Remaining requests in the current rate limit window
schema:
type: string
example: '99'
RateLimit-Reset:
description: Seconds until the next request token is available
schema:
type: integer
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
security:
- BearerAuth: []
components:
schemas:
ApiErrorResponse:
type: object
properties:
additional_data:
type: object
additionalProperties:
nullable: true
description: Optional machine-readable error details.
status:
type: integer
description: HTTP status code.
example: 404
code:
type: string
description: Stable machine-readable error code.
example: not_found
message:
type: string
description: Human-readable error description.
example: Resource not found
request_id:
type: string
description: Request identifier for support and tracing.
example: req_abc123
required:
- status
- code
- message
RateLimitErrorResponse:
allOf:
- $ref: '#/components/schemas/ApiErrorResponse'
- type: object
properties:
additional_data:
type: object
properties:
retry_after_seconds:
type: integer
minimum: 0
required:
- retry_after_seconds
additionalProperties:
nullable: true
description: Machine-readable rate-limit details.
required:
- additional_data
example:
status: 429
code: rate_limit_exceeded
message: Rate limit exceeded
request_id: req_abc123
additional_data:
retry_after_seconds: 1
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: Cevoid publishable key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.