{ "openapi": "3.0.3", "info": { "title": "Cevoid Storefront API", "version": "1.0.0" }, "servers": [ { "url": "https://api.widget.cevoid.com", "description": "Production" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Cevoid publishable key" } }, "schemas": { "ReviewRatingsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "prd_abc123", "description": "Opaque Cevoid identifier." }, "average_rating": { "type": "number", "nullable": true, "example": 4.5 }, "rating_count": { "type": "integer", "minimum": 0, "example": 2 } }, "required": [ "product_id", "average_rating", "rating_count" ] } }, "missing_product_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." } } }, "required": [ "data", "missing_product_ids" ], "example": { "data": [ { "product_id": "prd_abc123", "average_rating": 4.5, "rating_count": 2 } ], "missing_product_ids": [] } }, "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" ] }, "StorefrontReviewSummary": { "allOf": [ { "$ref": "#/components/schemas/DisplayReviewSummary" }, { "type": "object", "properties": { "rich_snippet": { "type": "object", "properties": { "json_ld": { "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" ] }, "computed_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" } }, "required": [ "json_ld", "computed_at" ] } } } ], "example": { "rating_count": 2, "text_review_count": 2, "average_rating": 4.5, "rating_distribution": { "1": 0, "2": 0, "3": 0, "4": 1, "5": 1 }, "verified_purchase_count": 0, "reviews_with_media_count": 0, "media_count": 0, "languages": [ { "language": "en", "rating_count": 2 } ], "question_summaries": [], "media_preview": [], "ai_summary": { "text": "Reviewers describe a positive overall experience, with ratings of four and five stars.", "language": "en", "generated_at": "2026-09-01T10:00:00.000Z", "review_count": 2 } } }, "DisplayReviewSummary": { "allOf": [ { "$ref": "#/components/schemas/ReviewSummary" }, { "type": "object", "properties": { "question_summaries": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rvq_abc123", "description": "Opaque Cevoid identifier." }, "answer_count": { "type": "integer", "minimum": 0, "example": 2, "description": "Public responses counted for this question. Summaries require at least two responses." }, "average": { "type": "number", "example": 4.5 }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "example": "blue" }, { "type": "number", "example": 4 } ] }, "count": { "type": "integer", "minimum": 0, "example": 1 } }, "required": [ "value", "count" ] } }, "yes_count": { "type": "integer", "minimum": 0, "example": 2 }, "no_count": { "type": "integer", "minimum": 0, "example": 0 }, "type": { "type": "string", "enum": [ "PRODUCT_ATTRIBUTE", "COMPANY_ATTRIBUTE", "PROFILE_PROPERTY" ], "example": "PRODUCT_ATTRIBUTE" }, "prompt": { "type": "string", "example": "How does it fit?" }, "format": { "type": "string", "enum": [ "SCALE", "CENTERED_RANGE", "SINGLE_SELECT", "MULTI_SELECT", "WOULD_RECOMMEND", "NUMERIC" ], "example": "SCALE" }, "scale": { "type": "object", "properties": { "steps": { "type": "number", "example": 5 }, "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "steps", "start_label", "end_label" ], "description": "Current scale size and labels, localized for the selected market. Not a submission-time snapshot." }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "numeric": { "type": "object", "properties": { "unit": { "type": "string", "example": "cm" } } } }, "required": [ "question_id", "answer_count", "type", "prompt", "format" ] } } } } ], "example": { "rating_count": 2, "text_review_count": 2, "average_rating": 4.5, "rating_distribution": { "1": 0, "2": 0, "3": 0, "4": 1, "5": 1 }, "verified_purchase_count": 0, "reviews_with_media_count": 0, "media_count": 0, "languages": [ { "language": "en", "rating_count": 2 } ], "question_summaries": [], "media_preview": [], "ai_summary": { "text": "Reviewers describe a positive overall experience, with ratings of four and five stars.", "language": "en", "generated_at": "2026-09-01T10:00:00.000Z", "review_count": 2 } } }, "ReviewSummary": { "type": "object", "properties": { "product_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "prd_abc123", "description": "Opaque Cevoid identifier." }, "rating_count": { "type": "integer", "minimum": 0, "example": 2, "description": "Number of published, visible ratings, including reviews without text. Independent of review-list filters and presentation market." }, "text_review_count": { "type": "integer", "minimum": 0, "example": 2, "description": "Public reviews with a non-blank title or body." }, "average_rating": { "type": "number", "nullable": true, "example": 4.5, "description": "Arithmetic mean of all public ratings; null when empty." }, "rating_distribution": { "type": "object", "properties": { "1": { "type": "number", "example": 0 }, "2": { "type": "number", "example": 0 }, "3": { "type": "number", "example": 0 }, "4": { "type": "number", "example": 1 }, "5": { "type": "number", "example": 1 } }, "required": [ "1", "2", "3", "4", "5" ] }, "verified_purchase_count": { "type": "integer", "minimum": 0, "example": 1, "description": "Public reviews with a verified purchase." }, "reviews_with_media_count": { "type": "integer", "minimum": 0, "example": 1, "description": "Public reviews with at least one displayable image or video." }, "media_count": { "type": "integer", "minimum": 0, "example": 1, "description": "Displayable images and videos across all public reviews, not only the preview." }, "languages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "example": "en" }, "rating_count": { "type": "number", "example": 2 } }, "required": [ "language", "rating_count" ] } }, "question_summaries": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rvq_abc123", "description": "Opaque Cevoid identifier." }, "answer_count": { "type": "integer", "minimum": 0, "example": 2, "description": "Public responses counted for this question. Summaries require at least two responses." }, "average": { "type": "number", "example": 4.5 }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "example": "blue" }, { "type": "number", "example": 4 } ] }, "count": { "type": "integer", "minimum": 0, "example": 1 } }, "required": [ "value", "count" ] } }, "yes_count": { "type": "integer", "minimum": 0, "example": 2 }, "no_count": { "type": "integer", "minimum": 0, "example": 0 } }, "required": [ "question_id", "answer_count" ] }, "maxItems": 20, "description": "At most 20 attribute questions, ordered by response count and stable question identity. Profile properties are excluded." }, "media_preview": { "type": "array", "items": { "type": "object", "properties": { "review_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "media": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "IMAGE", "VIDEO" ], "example": "IMAGE", "description": "Whether the item is an image or a video." }, "url": { "type": "string", "example": "https://example.com/reviews/123", "description": "Delivery URL for the full asset." }, "thumbnail_url": { "type": "string", "example": "https://example.com/reviews/123", "description": "Delivery URL for the thumbnail." }, "aspect_ratio": { "type": "number", "example": 1.5, "description": "Width divided by height." }, "aspect_ratio_type": { "type": "string", "enum": [ "LANDSCAPE", "PORTRAIT", "SQUARE" ], "example": "LANDSCAPE", "description": "Coarse orientation bucket." }, "video_length": { "type": "number", "example": 12, "description": "Video duration in seconds." }, "id": { "type": "string", "example": "rmed_abc123", "description": "Stable opaque asset identity shared by detail and preview." }, "alt": { "type": "string", "example": "Blue shirt worn outdoors", "description": "Available image alternative text, localized with source fallback." }, "thumbnail_alt": { "type": "string", "example": "Blue shirt video preview", "description": "Available video poster alternative text." }, "video_description": { "type": "string", "example": "A shopper shows the fit of a blue shirt.", "description": "Available description of video imagery." }, "video_captions": { "type": "string", "example": "WEBVTT\n\n00:00.000 --> 00:01.000\nThe fit is comfortable.", "description": "Available WebVTT captions with cue timing, localized with source fallback." } }, "required": [ "type", "url", "thumbnail_url", "aspect_ratio", "aspect_ratio_type", "id" ] } }, "required": [ "review_id", "media" ] }, "maxItems": 4 }, "ai_summary": { "type": "object", "properties": { "text": { "type": "string", "example": "Shoppers praise the comfortable fit." }, "language": { "type": "string", "example": "en" }, "generated_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" }, "review_count": { "type": "number", "example": 2 } }, "required": [ "text", "language", "generated_at", "review_count" ] } }, "required": [ "rating_count", "text_review_count", "average_rating", "rating_distribution", "verified_purchase_count", "reviews_with_media_count", "media_count", "languages", "question_summaries", "media_preview" ], "example": { "rating_count": 2, "text_review_count": 2, "average_rating": 4.5, "rating_distribution": { "1": 0, "2": 0, "3": 0, "4": 1, "5": 1 }, "verified_purchase_count": 0, "reviews_with_media_count": 0, "media_count": 0, "languages": [ { "language": "en", "rating_count": 2 } ], "question_summaries": [], "media_preview": [], "ai_summary": { "text": "Reviewers describe a positive overall experience, with ratings of four and five stars.", "language": "en", "generated_at": "2026-09-01T10:00:00.000Z", "review_count": 2 } } }, "DisplayProductReview": { "allOf": [ { "$ref": "#/components/schemas/DisplayCompanyReview" }, { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "title": { "type": "string", "example": "Comfortable everyday fit" }, "url": { "type": "string", "example": "https://example.com/reviews/123" }, "image_url": { "type": "string", "example": "https://example.com/reviews/123" } }, "required": [ "id" ] }, "variant": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "title": { "type": "string", "example": "Comfortable everyday fit" } }, "required": [ "id" ] }, "is_pinned": { "type": "boolean", "example": false } }, "required": [ "is_pinned" ] } ], "example": { "rating": 5, "title": "Comfortable everyday fit", "body": "Comfortable and true to size.", "language": "en", "purchase_verification": "UNVERIFIED", "is_incentivized": false, "is_insider": false, "channel": "IMPORT", "submitted_at": "2026-09-01T10:00:00.000Z", "media": [], "answers": [], "responses": [], "id": "rev_abc123", "published_at": "2026-09-01T10:00:00.000Z", "reviewer": { "display_name": "Jane S" }, "is_pinned": false, "product": { "id": "prd_abc123", "title": "Everyday shirt", "url": "https://example.com/products/everyday-shirt" }, "variant": { "id": "var_abc123", "title": "Blue / Medium" } } }, "DisplayCompanyReview": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "example": 5, "description": "Score from 1 to 5." }, "title": { "type": "string", "example": "Comfortable everyday fit", "description": "Reviewer-supplied headline. In localized responses, title and body both use source text unless a complete translation is available." }, "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reviewer-supplied text. Absent for star-only reviews. In localized responses, title and body both use source text unless a complete translation is available." }, "language": { "type": "string", "example": "en", "description": "BCP-47 language of the original submission, even when the returned text is translated." }, "purchase_verification": { "type": "string", "enum": [ "VERIFIED", "UNVERIFIED" ], "example": "UNVERIFIED", "description": "Purchase evidence state behind verified-buyer display." }, "is_incentivized": { "type": "boolean", "example": false, "description": "Whether a reward influenced submission." }, "is_insider": { "type": "boolean", "example": false, "description": "Whether the reviewer is brand-connected." }, "channel": { "type": "string", "enum": [ "REQUEST", "WIDGET", "LINK", "IMPORT", "SYNDICATED_IN" ], "example": "IMPORT", "description": "How the review entered Cevoid." }, "submitted_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when submission completed." }, "published_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when it first became public." }, "edited_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "Last reviewer edit; unrelated processing does not change this timestamp." }, "reviewer": { "type": "object", "properties": { "display_name": { "type": "string", "example": "Jane S" }, "avatar_url": { "type": "string", "example": "https://example.com/reviews/123" } }, "required": [ "display_name" ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "IMAGE", "VIDEO" ], "example": "IMAGE", "description": "Whether the item is an image or a video." }, "url": { "type": "string", "example": "https://example.com/reviews/123", "description": "Delivery URL for the full asset." }, "thumbnail_url": { "type": "string", "example": "https://example.com/reviews/123", "description": "Delivery URL for the thumbnail." }, "aspect_ratio": { "type": "number", "example": 1.5, "description": "Width divided by height." }, "aspect_ratio_type": { "type": "string", "enum": [ "LANDSCAPE", "PORTRAIT", "SQUARE" ], "example": "LANDSCAPE", "description": "Coarse orientation bucket." }, "video_length": { "type": "number", "example": 12, "description": "Video duration in seconds." }, "id": { "type": "string", "example": "rmed_abc123", "description": "Stable opaque asset identity shared by detail and preview." }, "alt": { "type": "string", "example": "Blue shirt worn outdoors", "description": "Available image alternative text, localized with source fallback." }, "thumbnail_alt": { "type": "string", "example": "Blue shirt video preview", "description": "Available video poster alternative text." }, "video_description": { "type": "string", "example": "A shopper shows the fit of a blue shirt.", "description": "Available description of video imagery." }, "video_captions": { "type": "string", "example": "WEBVTT\n\n00:00.000 --> 00:01.000\nThe fit is comfortable.", "description": "Available WebVTT captions with cue timing, localized with source fallback." } }, "required": [ "type", "url", "thumbnail_url", "aspect_ratio", "aspect_ratio_type", "id" ] } }, "answers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PRODUCT_ATTRIBUTE", "COMPANY_ATTRIBUTE", "PROFILE_PROPERTY" ], "example": "PRODUCT_ATTRIBUTE" }, "prompt": { "type": "string", "example": "How does it fit?" }, "format": { "type": "string", "enum": [ "SCALE", "CENTERED_RANGE", "SINGLE_SELECT", "MULTI_SELECT", "WOULD_RECOMMEND", "NUMERIC" ], "example": "SCALE" }, "scale": { "type": "object", "properties": { "steps": { "type": "number", "example": 5 }, "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "steps", "start_label", "end_label" ], "description": "Current scale size and labels, localized for the selected market. Not a submission-time snapshot." }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "numeric": { "type": "object", "properties": { "unit": { "type": "string", "example": "cm" } } }, "question_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rvq_abc123", "description": "Opaque Cevoid identifier." }, "value": { "anyOf": [ { "type": "number", "example": 4 }, { "type": "string", "example": "Comfortable fit" }, { "type": "boolean", "example": true }, { "type": "array", "items": { "type": "string", "example": "Comfortable fit" } } ] } }, "required": [ "type", "prompt", "format", "question_id", "value" ] } }, "responses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rrsp_abc123", "description": "Opaque Cevoid identifier." }, "body": { "type": "string", "example": "Comfortable and true to size." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" }, "author": { "type": "object", "properties": { "display_name": { "type": "string", "example": "Jane S" } }, "required": [ "display_name" ] } }, "required": [ "id", "body", "created_at", "author" ] } }, "helpful": { "type": "object", "properties": { "up_count": { "type": "number", "example": 3 }, "down_count": { "type": "number", "example": 0 } }, "required": [ "up_count" ] } }, "required": [ "id", "rating", "language", "purchase_verification", "is_incentivized", "is_insider", "channel", "reviewer", "media", "answers", "responses" ], "example": { "rating": 5, "title": "Comfortable everyday fit", "body": "Comfortable and true to size.", "language": "en", "purchase_verification": "UNVERIFIED", "is_incentivized": false, "is_insider": false, "channel": "IMPORT", "submitted_at": "2026-09-01T10:00:00.000Z", "media": [], "answers": [], "responses": [], "id": "crv_abc123", "published_at": "2026-09-01T10:00:00.000Z", "reviewer": { "display_name": "Jane S" } } }, "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 } } }, "WidgetPostsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WidgetPost" } }, "has_more": { "type": "boolean", "description": "Whether another page is available.", "example": true }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null when this is the final page.", "example": "eyJwdWJsaXNoZWRBdCI6IjIwMjYtMDgtMDFUMTA6MDA6MDAuMDAwWiJ9" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "pst_summerlook", "type": "IMAGE", "media": { "url": "https://cdn.cevoid.com/posts/pst_summerlook.jpg", "thumbnail_url": "https://cdn.cevoid.com/posts/pst_summerlook-thumbnail.jpg", "sprite_url": "https://cdn.cevoid.com/posts/pst_summerlook-sprite.jpg", "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj", "aspect_ratio": 0.8, "duration_seconds": 12.5, "has_audio": false }, "caption": "A summer favorite.", "hide_caption": false, "alt": "Person wearing a beige linen shirt outdoors.", "source_url": "https://www.instagram.com/p/example/", "author": { "name": "@jane", "avatar_url": "https://cdn.cevoid.com/profiles/prf_jane.jpg" }, "tagged_products": [ { "id": "prd_linen_shirt", "type": "PRODUCT", "title": "Linen Shirt", "url": "https://shop.example.com/products/linen-shirt", "image_url": "https://cdn.cevoid.com/products/linen-shirt.jpg", "price": { "min_amount": 59.95, "max_amount": 79.95, "currency": "SEK" }, "x": 0.35, "y": 0.65 } ], "published_at": "2026-08-01T10:00:00.000Z" } ], "has_more": true, "next_cursor": "eyJwdWJsaXNoZWRBdCI6IjIwMjYtMDgtMDFUMTA6MDA6MDAuMDAwWiJ9" } }, "WidgetPost": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable public Post identifier.", "example": "pst_summerlook" }, "type": { "type": "string", "enum": [ "IMAGE", "VIDEO" ], "description": "Post media type.", "example": "IMAGE" }, "media": { "$ref": "#/components/schemas/WidgetPostMedia" }, "caption": { "type": "string", "description": "Public post caption. Omitted when hide_caption is true.", "example": "A summer favorite." }, "hide_caption": { "type": "boolean", "description": "Whether clients should hide the caption.", "example": false }, "alt": { "type": "string", "description": "Accessible media description.", "example": "Person wearing a beige linen shirt outdoors." }, "video_captions": { "type": "string", "description": "WebVTT captions for video media.", "example": "WEBVTT\n\n00:00.000 --> 00:02.000\nA summer favorite." }, "video_description": { "type": "string", "description": "Accessible description of video content.", "example": "A person turns to show the front and back of a linen shirt." }, "source_url": { "type": "string", "format": "uri", "description": "Original public social post URL when available.", "example": "https://www.instagram.com/p/example/" }, "author": { "$ref": "#/components/schemas/WidgetPostAuthor" }, "custom_link": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://shop.example.com/stories/summer" }, "title": { "type": "string", "example": "Summer stories" }, "description": { "type": "string", "example": "Explore our summer stories." }, "image_url": { "type": "string", "format": "uri", "example": "https://cdn.cevoid.com/stories/summer.jpg" } }, "required": [ "url" ], "description": "Editorial link attached to this post.", "example": { "url": "https://shop.example.com/stories/summer", "title": "Summer stories" } }, "tagged_products": { "type": "array", "items": { "$ref": "#/components/schemas/WidgetPostProduct" }, "description": "Shoppable products in the selected market. Products without a presentation in that market are omitted." }, "published_at": { "type": "string", "format": "date-time", "description": "Creation time in Cevoid, used for newest-first ordering. This can differ from the original social publication date.", "example": "2026-08-01T10:00:00.000Z" } }, "required": [ "id", "type", "media", "hide_caption", "tagged_products", "published_at" ], "example": { "id": "pst_summerlook", "type": "IMAGE", "media": { "url": "https://cdn.cevoid.com/posts/pst_summerlook.jpg", "thumbnail_url": "https://cdn.cevoid.com/posts/pst_summerlook-thumbnail.jpg", "sprite_url": "https://cdn.cevoid.com/posts/pst_summerlook-sprite.jpg", "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj", "aspect_ratio": 0.8, "duration_seconds": 12.5, "has_audio": false }, "caption": "A summer favorite.", "hide_caption": false, "alt": "Person wearing a beige linen shirt outdoors.", "source_url": "https://www.instagram.com/p/example/", "author": { "name": "@jane", "avatar_url": "https://cdn.cevoid.com/profiles/prf_jane.jpg" }, "tagged_products": [ { "id": "prd_linen_shirt", "type": "PRODUCT", "title": "Linen Shirt", "url": "https://shop.example.com/products/linen-shirt", "image_url": "https://cdn.cevoid.com/products/linen-shirt.jpg", "price": { "min_amount": 59.95, "max_amount": 79.95, "currency": "SEK" }, "x": 0.35, "y": 0.65 } ], "published_at": "2026-08-01T10:00:00.000Z" } }, "WidgetPostMedia": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "CDN URL for the post media.", "example": "https://cdn.cevoid.com/posts/pst_summerlook.jpg" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Smaller preview image when available.", "example": "https://cdn.cevoid.com/posts/pst_summerlook-thumbnail.jpg" }, "sprite_url": { "type": "string", "format": "uri", "description": "Video sprite image for timeline previews when available.", "example": "https://cdn.cevoid.com/posts/pst_summerlook-sprite.jpg" }, "blurhash": { "type": "string", "description": "BlurHash placeholder for the media asset.", "example": "LEHV6nWB2yk8pyo0adR*.7kCMdnj" }, "aspect_ratio": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Media width divided by height.", "example": 0.8 }, "duration_seconds": { "type": "number", "minimum": 0, "description": "Video duration in seconds.", "example": 12.5 }, "has_audio": { "type": "boolean", "description": "Whether video media includes an audio track.", "example": true } }, "required": [ "url" ] }, "WidgetPostAuthor": { "type": "object", "properties": { "name": { "type": "string", "description": "Public display name selected for the storefront.", "example": "@jane" }, "avatar_url": { "type": "string", "format": "uri", "description": "Public profile image URL when available.", "example": "https://cdn.cevoid.com/profiles/prf_jane.jpg" } }, "required": [ "name" ] }, "WidgetPostProduct": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable public Product identifier.", "example": "prd_linen_shirt" }, "title": { "type": "string", "description": "Market-specific product title.", "example": "Linen Shirt" }, "type": { "type": "string", "enum": [ "PRODUCT", "VARIANT" ], "example": "PRODUCT" }, "parent_product_id": { "type": "string", "minLength": 1, "maxLength": 256, "example": "prd_linen_shirt" }, "availability": { "type": "string", "enum": [ "IN_STOCK", "OUT_OF_STOCK" ], "example": "IN_STOCK" }, "url": { "type": "string", "format": "uri", "description": "Market-specific storefront URL.", "example": "https://shop.example.com/products/linen-shirt" }, "image_url": { "type": "string", "format": "uri", "description": "Market-specific product image URL.", "example": "https://cdn.cevoid.com/products/linen-shirt.jpg" }, "price": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string" }, "min_amount": { "type": "number", "minimum": 0 }, "max_amount": { "type": "number", "minimum": 0 } }, "required": [ "currency", "min_amount", "max_amount" ] }, { "type": "object", "properties": { "currency": { "type": "string" }, "amount": { "type": "number", "minimum": 0 }, "sale_amount": { "type": "number", "minimum": 0 } }, "required": [ "currency", "amount" ] } ], "description": "Product price range or exact variant price in the selected market. Omitted when the market hides prices.", "example": { "currency": "SEK", "min_amount": 59.95, "max_amount": 79.95 } }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized horizontal hotspot position. Omitted together with y when no valid position is stored.", "example": 0.35 }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized vertical hotspot position.", "example": 0.65 } }, "required": [ "id", "title", "type" ] }, "WidgetPostResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WidgetPost" } }, "required": [ "data" ], "example": { "data": { "id": "pst_summerlook", "type": "IMAGE", "media": { "url": "https://cdn.cevoid.com/posts/pst_summerlook.jpg", "thumbnail_url": "https://cdn.cevoid.com/posts/pst_summerlook-thumbnail.jpg", "sprite_url": "https://cdn.cevoid.com/posts/pst_summerlook-sprite.jpg", "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj", "aspect_ratio": 0.8, "duration_seconds": 12.5, "has_audio": false }, "caption": "A summer favorite.", "hide_caption": false, "alt": "Person wearing a beige linen shirt outdoors.", "source_url": "https://www.instagram.com/p/example/", "author": { "name": "@jane", "avatar_url": "https://cdn.cevoid.com/profiles/prf_jane.jpg" }, "tagged_products": [ { "id": "prd_linen_shirt", "type": "PRODUCT", "title": "Linen Shirt", "url": "https://shop.example.com/products/linen-shirt", "image_url": "https://cdn.cevoid.com/products/linen-shirt.jpg", "price": { "min_amount": 59.95, "max_amount": 79.95, "currency": "SEK" }, "x": 0.35, "y": 0.65 } ], "published_at": "2026-08-01T10:00:00.000Z" } } } }, "parameters": {} }, "paths": { "/v1/product-reviews/ratings": { "get": { "summary": "Get product ratings", "description": "Returns average scores and rating counts for product cards.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Presentation market. Defaults to the workspace default; does not filter collection origin." }, "required": false, "description": "Presentation market. Defaults to the workspace default; does not filter collection origin.", "name": "market", "in": "query" }, { "schema": { "type": "string", "example": "prd_abc123,prd_def456", "description": "Comma-separated list of 1 to 100 distinct product IDs. Input order is preserved." }, "required": true, "description": "Comma-separated list of 1 to 100 distinct product IDs. Input order is preserved.", "name": "product_ids", "in": "query" } ], "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRatingsResponse" } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } }, "409": { "description": "Conflict", "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/ApiErrorResponse" } } } }, "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" } } } } } } }, "/v1/product-reviews/summaries": { "get": { "summary": "Get product review summaries", "description": "Returns rating breakdowns, answer summaries, and media previews for products.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Presentation market. Defaults to the workspace default; does not filter collection origin." }, "required": false, "description": "Presentation market. Defaults to the workspace default; does not filter collection origin.", "name": "market", "in": "query" }, { "schema": { "type": "string", "example": "prd_abc123,prd_def456", "description": "Comma-separated list of 1 to 100 distinct product IDs. Input order is preserved." }, "required": true, "description": "Comma-separated list of 1 to 100 distinct product IDs. Input order is preserved.", "name": "product_ids", "in": "query" }, { "schema": { "type": "string", "enum": [ "localization" ], "example": "localization", "description": "Include original prompts and labels for the returned question definitions. Does not include originals for AI summary text or preview media." }, "required": false, "description": "Include original prompts and labels for the returned question definitions. Does not include originals for AI summary text or preview media.", "name": "include", "in": "query" } ], "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 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontReviewSummary" } }, "missing_product_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." } }, "included": { "type": "object", "properties": { "localization": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "string", "example": "How does it fit?" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "scale": { "type": "object", "properties": { "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "start_label", "end_label" ] } }, "required": [ "prompt" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } } } } }, "required": [ "localization" ] } }, "required": [ "data", "missing_product_ids" ], "example": { "data": [ { "rating_count": 2, "text_review_count": 2, "average_rating": 4.5, "rating_distribution": { "1": 0, "2": 0, "3": 0, "4": 1, "5": 1 }, "verified_purchase_count": 0, "reviews_with_media_count": 0, "media_count": 0, "languages": [ { "language": "en", "rating_count": 2 } ], "question_summaries": [], "media_preview": [], "ai_summary": { "text": "Reviewers describe a positive overall experience, with ratings of four and five stars.", "language": "en", "generated_at": "2026-09-01T10:00:00.000Z", "review_count": 2 } } ], "missing_product_ids": [] } } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } }, "409": { "description": "Conflict", "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/ApiErrorResponse" } } } }, "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" } } } } } } }, "/v1/product-reviews/summaries/{product_id}": { "get": { "summary": "Get product review summary", "description": "Returns the rating breakdown, answer summaries, and media previews for a product.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "required": true, "description": "Opaque Cevoid identifier.", "name": "product_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Presentation market. Defaults to the workspace default; does not filter collection origin." }, "required": false, "description": "Presentation market. Defaults to the workspace default; does not filter collection origin.", "name": "market", "in": "query" }, { "schema": { "type": "string", "enum": [ "localization" ], "example": "localization", "description": "Include original prompts and labels for the returned question definitions. Does not include originals for AI summary text or preview media." }, "required": false, "description": "Include original prompts and labels for the returned question definitions. Does not include originals for AI summary text or preview media.", "name": "include", "in": "query" } ], "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 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StorefrontReviewSummary" }, "included": { "type": "object", "properties": { "localization": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "string", "example": "How does it fit?" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "scale": { "type": "object", "properties": { "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "start_label", "end_label" ] } }, "required": [ "prompt" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } } } } }, "required": [ "localization" ] } }, "required": [ "data" ], "example": { "data": { "rating_count": 2, "text_review_count": 2, "average_rating": 4.5, "rating_distribution": { "1": 0, "2": 0, "3": 0, "4": 1, "5": 1 }, "verified_purchase_count": 0, "reviews_with_media_count": 0, "media_count": 0, "languages": [ { "language": "en", "rating_count": 2 } ], "question_summaries": [], "media_preview": [], "ai_summary": { "text": "Reviewers describe a positive overall experience, with ratings of four and five stars.", "language": "en", "generated_at": "2026-09-01T10:00:00.000Z", "review_count": 2 } } } } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } }, "409": { "description": "Conflict", "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/ApiErrorResponse" } } } }, "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" } } } } } } }, "/v1/products/{product_id}/reviews": { "get": { "summary": "List product reviews", "description": "Returns product reviews and their submitted content.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "required": true, "description": "Opaque Cevoid identifier.", "name": "product_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Presentation market. Defaults to the workspace default; does not filter collection origin." }, "required": false, "description": "Presentation market. Defaults to the workspace default; does not filter collection origin.", "name": "market", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "example": 25, "description": "Maximum page size; does not limit total traversal." }, "required": false, "description": "Maximum page size; does not limit total traversal.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 3000, "example": "eyJ2IjoxLCJjdXJzb3IiOiJyZXZfYWJjMTIzIn0", "description": "Opaque next-page cursor. Keep filters and market fixed." }, "required": false, "description": "Opaque next-page cursor. Keep filters and market fixed.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "latest", "oldest", "highest", "lowest" ], "default": "latest", "example": "latest", "description": "Latest and oldest order by creation in Cevoid, not submission date. Highest and lowest order by rating, then newest creation. Ties use stable review identity." }, "required": false, "description": "Latest and oldest order by creation in Cevoid, not submission date. Highest and lowest order by rating, then newest creation. Ties use stable review identity.", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 5, "example": 5, "description": "Return reviews with exactly this star rating, from 1 to 5." }, "required": false, "description": "Return reviews with exactly this star rating, from 1 to 5.", "name": "rating", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "example": "true", "description": "True selects reviews with at least one non-processing asset that is neither pending nor declined. False selects reviews without such assets." }, "required": false, "description": "True selects reviews with at least one non-processing asset that is neither pending nor declined. False selects reviews without such assets.", "name": "with_media", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "example": "true", "description": "True selects verified purchases. False selects every other purchase-verification state. This does not filter author identity verification." }, "required": false, "description": "True selects verified purchases. False selects every other purchase-verification state. This does not filter author identity verification.", "name": "verified", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "Include reviews submitted at or after this UTC timestamp, using the original submission date for imports." }, "required": false, "description": "Include reviews submitted at or after this UTC timestamp, using the original submission date for imports.", "name": "submitted_after", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "Include reviews submitted strictly before this UTC timestamp, using the original submission date for imports." }, "required": false, "description": "Include reviews submitted strictly before this UTC timestamp, using the original submission date for imports.", "name": "submitted_before", "in": "query" }, { "schema": { "type": "string", "enum": [ "localization" ], "example": "localization", "description": "Include compact original content alongside localized fields. Review reads include reviews, public replies, visible media accessibility text, and returned questions. Summary reads include returned questions only." }, "required": false, "description": "Include compact original content alongside localized fields. Review reads include reviews, public replies, visible media accessibility text, and returned questions. Summary reads include returned questions only.", "name": "include", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "example": "true", "description": "Filter product reviews by whether they are pinned. Omit to return both pinned and unpinned reviews. Existing sorting still applies." }, "required": false, "description": "Filter product reviews by whether they are pinned. Omit to return both pinned and unpinned reviews. Existing sorting still applies.", "name": "pinned", "in": "query" } ], "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 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/DisplayProductReview" } }, "matched_count": { "type": "number", "example": 1, "description": "Total reviews matching the active filters, across all pages. Overall ratings are available from the separate summary endpoint." }, "product": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "title": { "type": "string", "example": "Comfortable everyday fit" }, "url": { "type": "string", "example": "https://example.com/reviews/123" }, "image_url": { "type": "string", "example": "https://example.com/reviews/123" } }, "required": [ "id" ] } }, "required": [ "reviews", "matched_count", "product" ] }, "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": "string", "nullable": true, "example": "eyJ2IjoxLCJjdXJzb3IiOiJyZXZfYWJjMTIzIn0" }, "included": { "type": "object", "properties": { "localization": { "type": "object", "properties": { "product_reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "example": "Comfortable everyday fit", "description": "Reviewer-supplied headline. In localized responses, title and body both use source text unless a complete translation is available." }, "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reviewer-supplied text. Absent for star-only reviews. In localized responses, title and body both use source text unless a complete translation is available." } }, "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "review_responses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reply text as published." } }, "required": [ "body" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "review_media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "alt": { "type": "string", "example": "Blue shirt worn outdoors", "description": "Available image alternative text, localized with source fallback." }, "thumbnail_alt": { "type": "string", "example": "Blue shirt video preview", "description": "Available video poster alternative text." }, "video_description": { "type": "string", "example": "A shopper shows the fit of a blue shirt.", "description": "Available description of video imagery." }, "video_captions": { "type": "string", "example": "WEBVTT\n\n00:00.000 --> 00:01.000\nThe fit is comfortable.", "description": "Available WebVTT captions with cue timing, localized with source fallback." } }, "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "string", "example": "How does it fit?" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "scale": { "type": "object", "properties": { "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "start_label", "end_label" ] } }, "required": [ "prompt" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } } } } }, "required": [ "localization" ] } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": { "reviews": [ { "rating": 5, "title": "Comfortable everyday fit", "body": "Comfortable and true to size.", "language": "en", "purchase_verification": "UNVERIFIED", "is_incentivized": false, "is_insider": false, "channel": "IMPORT", "submitted_at": "2026-09-01T10:00:00.000Z", "media": [], "answers": [], "responses": [], "id": "rev_abc123", "published_at": "2026-09-01T10:00:00.000Z", "reviewer": { "display_name": "Jane S" }, "is_pinned": false, "product": { "id": "prd_abc123", "title": "Everyday shirt", "url": "https://example.com/products/everyday-shirt" }, "variant": { "id": "var_abc123", "title": "Blue / Medium" } } ], "matched_count": 1, "product": { "id": "prd_abc123", "title": "Everyday shirt", "url": "https://example.com/products/everyday-shirt" } }, "has_more": false, "next_cursor": null } } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } }, "409": { "description": "Conflict", "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/ApiErrorResponse" } } } }, "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" } } } } } } }, "/v1/product-reviews/{review_id}": { "get": { "summary": "Get product review", "description": "Returns one product review and its public replies.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "required": true, "description": "Opaque Cevoid identifier.", "name": "review_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Presentation market. Defaults to the workspace default; does not filter collection origin." }, "required": false, "description": "Presentation market. Defaults to the workspace default; does not filter collection origin.", "name": "market", "in": "query" }, { "schema": { "type": "string", "enum": [ "localization" ], "example": "localization", "description": "Include compact original content alongside localized fields. Review reads include reviews, public replies, visible media accessibility text, and returned questions. Summary reads include returned questions only." }, "required": false, "description": "Include compact original content alongside localized fields. Review reads include reviews, public replies, visible media accessibility text, and returned questions. Summary reads include returned questions only.", "name": "include", "in": "query" } ], "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 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DisplayProductReview" }, "included": { "type": "object", "properties": { "localization": { "type": "object", "properties": { "product_reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "example": "Comfortable everyday fit", "description": "Reviewer-supplied headline. In localized responses, title and body both use source text unless a complete translation is available." }, "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reviewer-supplied text. Absent for star-only reviews. In localized responses, title and body both use source text unless a complete translation is available." } }, "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "review_responses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reply text as published." } }, "required": [ "body" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "review_media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "alt": { "type": "string", "example": "Blue shirt worn outdoors", "description": "Available image alternative text, localized with source fallback." }, "thumbnail_alt": { "type": "string", "example": "Blue shirt video preview", "description": "Available video poster alternative text." }, "video_description": { "type": "string", "example": "A shopper shows the fit of a blue shirt.", "description": "Available description of video imagery." }, "video_captions": { "type": "string", "example": "WEBVTT\n\n00:00.000 --> 00:01.000\nThe fit is comfortable.", "description": "Available WebVTT captions with cue timing, localized with source fallback." } }, "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "string", "example": "How does it fit?" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "scale": { "type": "object", "properties": { "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "start_label", "end_label" ] } }, "required": [ "prompt" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } } } } }, "required": [ "localization" ] } }, "required": [ "data" ], "example": { "data": { "rating": 5, "title": "Bekväm passform varje dag", "body": "Bekväm och normal i storleken.", "language": "en", "purchase_verification": "UNVERIFIED", "is_incentivized": false, "is_insider": false, "channel": "IMPORT", "submitted_at": "2026-09-01T10:00:00.000Z", "media": [], "answers": [], "responses": [], "id": "rev_abc123", "published_at": "2026-09-01T10:00:00.000Z", "reviewer": { "display_name": "Jane S" }, "is_pinned": false, "product": { "id": "prd_abc123", "title": "Everyday shirt", "url": "https://example.com/products/everyday-shirt" }, "variant": { "id": "var_abc123", "title": "Blue / Medium" } }, "included": { "localization": { "product_reviews": [ { "id": "rev_abc123", "has_translations": true, "original": { "title": "Comfortable everyday fit", "body": "Comfortable and true to size." } } ], "review_responses": [], "review_media": [], "questions": [] } } } } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } }, "409": { "description": "Conflict", "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/ApiErrorResponse" } } } }, "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" } } } } } } }, "/v1/company-reviews/summary": { "get": { "summary": "Get company review summary", "description": "Returns the rating breakdown, answer summaries, and media previews for the company.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Presentation market. Defaults to the workspace default; does not filter collection origin." }, "required": false, "description": "Presentation market. Defaults to the workspace default; does not filter collection origin.", "name": "market", "in": "query" }, { "schema": { "type": "string", "enum": [ "localization" ], "example": "localization", "description": "Include original prompts and labels for the returned question definitions. Does not include originals for AI summary text or preview media." }, "required": false, "description": "Include original prompts and labels for the returned question definitions. Does not include originals for AI summary text or preview media.", "name": "include", "in": "query" } ], "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 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rating_count": { "type": "integer", "minimum": 0, "example": 2, "description": "Number of published, visible ratings, including reviews without text. Independent of review-list filters and presentation market." }, "text_review_count": { "type": "integer", "minimum": 0, "example": 2, "description": "Public reviews with a non-blank title or body." }, "average_rating": { "type": "number", "nullable": true, "example": 4.5, "description": "Arithmetic mean of all public ratings; null when empty." }, "rating_distribution": { "type": "object", "properties": { "1": { "type": "number", "example": 0 }, "2": { "type": "number", "example": 0 }, "3": { "type": "number", "example": 0 }, "4": { "type": "number", "example": 1 }, "5": { "type": "number", "example": 1 } }, "required": [ "1", "2", "3", "4", "5" ] }, "verified_purchase_count": { "type": "integer", "minimum": 0, "example": 1, "description": "Public reviews with a verified purchase." }, "reviews_with_media_count": { "type": "integer", "minimum": 0, "example": 1, "description": "Public reviews with at least one displayable image or video." }, "media_count": { "type": "integer", "minimum": 0, "example": 1, "description": "Displayable images and videos across all public reviews, not only the preview." }, "languages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "example": "en" }, "rating_count": { "type": "number", "example": 2 } }, "required": [ "language", "rating_count" ] } }, "question_summaries": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rvq_abc123", "description": "Opaque Cevoid identifier." }, "answer_count": { "type": "integer", "minimum": 0, "example": 2, "description": "Public responses counted for this question. Summaries require at least two responses." }, "average": { "type": "number", "example": 4.5 }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "example": "blue" }, { "type": "number", "example": 4 } ] }, "count": { "type": "integer", "minimum": 0, "example": 1 } }, "required": [ "value", "count" ] } }, "yes_count": { "type": "integer", "minimum": 0, "example": 2 }, "no_count": { "type": "integer", "minimum": 0, "example": 0 }, "type": { "type": "string", "enum": [ "PRODUCT_ATTRIBUTE", "COMPANY_ATTRIBUTE", "PROFILE_PROPERTY" ], "example": "PRODUCT_ATTRIBUTE" }, "prompt": { "type": "string", "example": "How does it fit?" }, "format": { "type": "string", "enum": [ "SCALE", "CENTERED_RANGE", "SINGLE_SELECT", "MULTI_SELECT", "WOULD_RECOMMEND", "NUMERIC" ], "example": "SCALE" }, "scale": { "type": "object", "properties": { "steps": { "type": "number", "example": 5 }, "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "steps", "start_label", "end_label" ], "description": "Current scale size and labels, localized for the selected market. Not a submission-time snapshot." }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "numeric": { "type": "object", "properties": { "unit": { "type": "string", "example": "cm" } } } }, "required": [ "question_id", "answer_count", "type", "prompt", "format" ] } }, "media_preview": { "type": "array", "items": { "type": "object", "properties": { "review_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "media": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "IMAGE", "VIDEO" ], "example": "IMAGE", "description": "Whether the item is an image or a video." }, "url": { "type": "string", "example": "https://example.com/reviews/123", "description": "Delivery URL for the full asset." }, "thumbnail_url": { "type": "string", "example": "https://example.com/reviews/123", "description": "Delivery URL for the thumbnail." }, "aspect_ratio": { "type": "number", "example": 1.5, "description": "Width divided by height." }, "aspect_ratio_type": { "type": "string", "enum": [ "LANDSCAPE", "PORTRAIT", "SQUARE" ], "example": "LANDSCAPE", "description": "Coarse orientation bucket." }, "video_length": { "type": "number", "example": 12, "description": "Video duration in seconds." }, "id": { "type": "string", "example": "rmed_abc123", "description": "Stable opaque asset identity shared by detail and preview." }, "alt": { "type": "string", "example": "Blue shirt worn outdoors", "description": "Available image alternative text, localized with source fallback." }, "thumbnail_alt": { "type": "string", "example": "Blue shirt video preview", "description": "Available video poster alternative text." }, "video_description": { "type": "string", "example": "A shopper shows the fit of a blue shirt.", "description": "Available description of video imagery." }, "video_captions": { "type": "string", "example": "WEBVTT\n\n00:00.000 --> 00:01.000\nThe fit is comfortable.", "description": "Available WebVTT captions with cue timing, localized with source fallback." } }, "required": [ "type", "url", "thumbnail_url", "aspect_ratio", "aspect_ratio_type", "id" ] } }, "required": [ "review_id", "media" ] }, "maxItems": 4 }, "ai_summary": { "type": "object", "properties": { "text": { "type": "string", "example": "Shoppers praise the comfortable fit." }, "language": { "type": "string", "example": "en" }, "generated_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" }, "review_count": { "type": "number", "example": 2 } }, "required": [ "text", "language", "generated_at", "review_count" ] } }, "required": [ "rating_count", "text_review_count", "average_rating", "rating_distribution", "verified_purchase_count", "reviews_with_media_count", "media_count", "languages", "question_summaries", "media_preview" ] }, "included": { "type": "object", "properties": { "localization": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "string", "example": "How does it fit?" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "scale": { "type": "object", "properties": { "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "start_label", "end_label" ] } }, "required": [ "prompt" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } } } } }, "required": [ "localization" ] } }, "required": [ "data" ], "example": { "data": { "rating_count": 2, "text_review_count": 2, "average_rating": 4.5, "rating_distribution": { "1": 0, "2": 0, "3": 0, "4": 1, "5": 1 }, "verified_purchase_count": 0, "reviews_with_media_count": 0, "media_count": 0, "languages": [ { "language": "en", "rating_count": 2 } ], "question_summaries": [], "media_preview": [], "ai_summary": { "text": "Reviewers describe a positive overall experience, with ratings of four and five stars.", "language": "en", "generated_at": "2026-09-01T10:00:00.000Z", "review_count": 2 } } } } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } }, "409": { "description": "Conflict", "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/ApiErrorResponse" } } } }, "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" } } } } } } }, "/v1/company-reviews": { "get": { "summary": "List company reviews", "description": "Returns company reviews and their submitted content.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Presentation market. Defaults to the workspace default; does not filter collection origin." }, "required": false, "description": "Presentation market. Defaults to the workspace default; does not filter collection origin.", "name": "market", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "example": 25, "description": "Maximum page size; does not limit total traversal." }, "required": false, "description": "Maximum page size; does not limit total traversal.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 3000, "example": "eyJ2IjoxLCJjdXJzb3IiOiJyZXZfYWJjMTIzIn0", "description": "Opaque next-page cursor. Keep filters and market fixed." }, "required": false, "description": "Opaque next-page cursor. Keep filters and market fixed.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "latest", "oldest", "highest", "lowest" ], "default": "latest", "example": "latest", "description": "Latest and oldest order by creation in Cevoid, not submission date. Highest and lowest order by rating, then newest creation. Ties use stable review identity." }, "required": false, "description": "Latest and oldest order by creation in Cevoid, not submission date. Highest and lowest order by rating, then newest creation. Ties use stable review identity.", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 5, "example": 5, "description": "Return reviews with exactly this star rating, from 1 to 5." }, "required": false, "description": "Return reviews with exactly this star rating, from 1 to 5.", "name": "rating", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "example": "true", "description": "True selects reviews with at least one non-processing asset that is neither pending nor declined. False selects reviews without such assets." }, "required": false, "description": "True selects reviews with at least one non-processing asset that is neither pending nor declined. False selects reviews without such assets.", "name": "with_media", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "example": "true", "description": "True selects verified purchases. False selects every other purchase-verification state. This does not filter author identity verification." }, "required": false, "description": "True selects verified purchases. False selects every other purchase-verification state. This does not filter author identity verification.", "name": "verified", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "Include reviews submitted at or after this UTC timestamp, using the original submission date for imports." }, "required": false, "description": "Include reviews submitted at or after this UTC timestamp, using the original submission date for imports.", "name": "submitted_after", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "Include reviews submitted strictly before this UTC timestamp, using the original submission date for imports." }, "required": false, "description": "Include reviews submitted strictly before this UTC timestamp, using the original submission date for imports.", "name": "submitted_before", "in": "query" }, { "schema": { "type": "string", "enum": [ "localization" ], "example": "localization", "description": "Include compact original content alongside localized fields. Review reads include reviews, public replies, visible media accessibility text, and returned questions. Summary reads include returned questions only." }, "required": false, "description": "Include compact original content alongside localized fields. Review reads include reviews, public replies, visible media accessibility text, and returned questions. Summary reads include returned questions only.", "name": "include", "in": "query" } ], "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 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/DisplayCompanyReview" } }, "matched_count": { "type": "number", "example": 1, "description": "Total reviews matching the active filters, across all pages. Overall ratings are available from the separate summary endpoint." } }, "required": [ "reviews", "matched_count" ] }, "has_more": { "type": "boolean", "example": false }, "next_cursor": { "type": "string", "nullable": true, "example": "eyJ2IjoxLCJjdXJzb3IiOiJyZXZfYWJjMTIzIn0" }, "included": { "type": "object", "properties": { "localization": { "type": "object", "properties": { "company_reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "example": "Comfortable everyday fit", "description": "Reviewer-supplied headline. In localized responses, title and body both use source text unless a complete translation is available." }, "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reviewer-supplied text. Absent for star-only reviews. In localized responses, title and body both use source text unless a complete translation is available." } }, "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "review_responses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reply text as published." } }, "required": [ "body" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "review_media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "alt": { "type": "string", "example": "Blue shirt worn outdoors", "description": "Available image alternative text, localized with source fallback." }, "thumbnail_alt": { "type": "string", "example": "Blue shirt video preview", "description": "Available video poster alternative text." }, "video_description": { "type": "string", "example": "A shopper shows the fit of a blue shirt.", "description": "Available description of video imagery." }, "video_captions": { "type": "string", "example": "WEBVTT\n\n00:00.000 --> 00:01.000\nThe fit is comfortable.", "description": "Available WebVTT captions with cue timing, localized with source fallback." } }, "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "string", "example": "How does it fit?" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "scale": { "type": "object", "properties": { "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "start_label", "end_label" ] } }, "required": [ "prompt" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } } } } }, "required": [ "localization" ] } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": { "reviews": [ { "rating": 5, "title": "Comfortable everyday fit", "body": "Comfortable and true to size.", "language": "en", "purchase_verification": "UNVERIFIED", "is_incentivized": false, "is_insider": false, "channel": "IMPORT", "submitted_at": "2026-09-01T10:00:00.000Z", "media": [], "answers": [], "responses": [], "id": "crv_abc123", "published_at": "2026-09-01T10:00:00.000Z", "reviewer": { "display_name": "Jane S" } } ], "matched_count": 1 }, "has_more": false, "next_cursor": null } } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } }, "409": { "description": "Conflict", "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/ApiErrorResponse" } } } }, "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" } } } } } } }, "/v1/company-reviews/{review_id}": { "get": { "summary": "Get company review", "description": "Returns one company review and its public replies.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "required": true, "description": "Opaque Cevoid identifier.", "name": "review_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Presentation market. Defaults to the workspace default; does not filter collection origin." }, "required": false, "description": "Presentation market. Defaults to the workspace default; does not filter collection origin.", "name": "market", "in": "query" }, { "schema": { "type": "string", "enum": [ "localization" ], "example": "localization", "description": "Include compact original content alongside localized fields. Review reads include reviews, public replies, visible media accessibility text, and returned questions. Summary reads include returned questions only." }, "required": false, "description": "Include compact original content alongside localized fields. Review reads include reviews, public replies, visible media accessibility text, and returned questions. Summary reads include returned questions only.", "name": "include", "in": "query" } ], "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 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DisplayCompanyReview" }, "included": { "type": "object", "properties": { "localization": { "type": "object", "properties": { "company_reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "example": "Comfortable everyday fit", "description": "Reviewer-supplied headline. In localized responses, title and body both use source text unless a complete translation is available." }, "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reviewer-supplied text. Absent for star-only reviews. In localized responses, title and body both use source text unless a complete translation is available." } }, "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "review_responses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reply text as published." } }, "required": [ "body" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "review_media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "alt": { "type": "string", "example": "Blue shirt worn outdoors", "description": "Available image alternative text, localized with source fallback." }, "thumbnail_alt": { "type": "string", "example": "Blue shirt video preview", "description": "Available video poster alternative text." }, "video_description": { "type": "string", "example": "A shopper shows the fit of a blue shirt.", "description": "Available description of video imagery." }, "video_captions": { "type": "string", "example": "WEBVTT\n\n00:00.000 --> 00:01.000\nThe fit is comfortable.", "description": "Available WebVTT captions with cue timing, localized with source fallback." } }, "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Public ID matching the returned entity or nested item." }, "has_translations": { "type": "boolean", "example": true, "description": "True when the returned translatable content differs from its source representation. Does not mean every field was translated." }, "original": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "string", "example": "How does it fit?" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Current selection options. Labels are localized; values remain stable selection keys." }, "scale": { "type": "object", "properties": { "start_label": { "type": "string", "example": "Too small" }, "end_label": { "type": "string", "example": "Too large" }, "center_label": { "type": "string", "example": "Just right" }, "step_labels": { "type": "array", "items": { "type": "string", "example": "Just right" } } }, "required": [ "start_label", "end_label" ] } }, "required": [ "prompt" ], "description": "Complete source projection of translatable fields, with the same visibility and masking rules. Null when no returned content differs. Not edit history." } }, "required": [ "id", "has_translations", "original" ] } } } } }, "required": [ "localization" ] } }, "required": [ "data" ], "example": { "data": { "rating": 5, "title": "Comfortable everyday fit", "body": "Comfortable and true to size.", "language": "en", "purchase_verification": "UNVERIFIED", "is_incentivized": false, "is_insider": false, "channel": "IMPORT", "submitted_at": "2026-09-01T10:00:00.000Z", "media": [], "answers": [], "responses": [], "id": "crv_abc123", "published_at": "2026-09-01T10:00:00.000Z", "reviewer": { "display_name": "Jane S" } }, "included": { "localization": { "company_reviews": [ { "id": "crv_abc123", "has_translations": false, "original": null } ], "review_responses": [], "review_media": [], "questions": [] } } } } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } }, "409": { "description": "Conflict", "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/ApiErrorResponse" } } } }, "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" } } } } } } }, "/v1/products/{productRef}/rich-snippet": { "get": { "summary": "Render a product Rich Snippet", "description": "Returns visible product-rating HTML and matching Product JSON-LD.", "tags": [ "Storefront rendering" ], "security": [ { "BearerAuth": [] } ], "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" } } } } } } }, "/v1/posts": { "get": { "summary": "List posts", "description": "Returns approved posts that match the requested filters.", "tags": [ "Storefront UGC" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Market identifier used for localized product data.", "example": "mar_sweden" }, "required": true, "description": "Market identifier used for localized product data.", "name": "market", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Return posts attributed to this profile.", "example": "prf_jane" }, "required": false, "description": "Return posts attributed to this profile.", "name": "profile_id", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable public label identifier.", "example": "lbl_summer" }, "minItems": 1, "maxItems": 50, "description": "Return posts with these labels. Repeat the parameter to provide more than one label.", "example": [ "lbl_summer", "lbl_featured" ] }, "required": false, "description": "Return posts with these labels. Repeat the parameter to provide more than one label.", "name": "label_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "any", "all" ], "description": "Match any requested label (default) or require all requested labels. Requires label_id. Unknown labels are ignored for any; all returns no posts if any label is unknown. If no labels resolve, no posts are returned.", "example": "any" }, "required": false, "description": "Match any requested label (default) or require all requested labels. Requires label_id. Unknown labels are ignored for any; all returns no posts if any label is unknown. If no labels resolve, no posts are returned.", "name": "label_match", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Return posts selected by this published gallery, newest first. Applies gallery filters but not pinned layout order.", "example": "gal_summer" }, "required": false, "description": "Return posts selected by this published gallery, newest first. Applies gallery filters but not pinned layout order.", "name": "gallery_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A Cevoid product or variant ID, provider-native ID, SKU, or barcode. Resolves within this workspace and market and selects the product family, including variants and existing tags. Unknown, ambiguous, or more than 100 candidate matches return an empty page; use a Cevoid product ID to disambiguate. Families with more than 1,000 product records return 400 with product_too_broad.", "example": "gid://shopify/Product/123" }, "required": false, "description": "A Cevoid product or variant ID, provider-native ID, SKU, or barcode. Resolves within this workspace and market and selects the product family, including variants and existing tags. Unknown, ambiguous, or more than 100 candidate matches return an empty page; use a Cevoid product ID to disambiguate. Families with more than 1,000 product records return 400 with product_too_broad.", "name": "product_ref", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Return posts containing products in this market-specific external collection.", "example": "summer-sale" }, "required": false, "description": "Return posts containing products in this market-specific external collection.", "name": "external_collection_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Opaque cursor returned by the previous page. Keep all other query parameters unchanged.", "example": "eyJjcmVhdGVkQXQiOiIyMDI2LTA4LTAxVDEwOjAwOjAwLjAwMFoifQ" }, "required": false, "description": "Opaque cursor returned by the previous page. Keep all other query parameters unchanged.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Number of posts to return, from 1 to 50.", "example": 20 }, "required": false, "description": "Number of posts to return, from 1 to 50.", "name": "limit", "in": "query" } ], "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 credential headers included in the shared-cache key.", "schema": { "type": "string", "example": "Authorization" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetPostsPage" } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } } } } }, "/v1/posts/{post_id}": { "get": { "summary": "Get post", "description": "Returns information about a specific approved post.", "tags": [ "Storefront UGC" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable public Post identifier.", "example": "pst_summerlook" }, "required": true, "description": "Stable public Post identifier.", "name": "post_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Market identifier used for localized product data.", "example": "mar_sweden" }, "required": true, "description": "Market identifier used for localized product data.", "name": "market", "in": "query" } ], "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 credential headers included in the shared-cache key.", "schema": { "type": "string", "example": "Authorization" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetPostResponse" } } } }, "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" } } } }, "403": { "description": "Forbidden", "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" } } } } } } } } }