{ "openapi": "3.1.0", "info": { "version": "0.1.0", "title": "Cevoid API", "description": "Manage profiles, loyalty data, labels, markets, products, posts, orders, and reviews." }, "servers": [ { "url": "https://api.cevoid.com", "description": "Production server" } ], "tags": [ { "name": "Authentication", "description": "API key details." }, { "name": "Labels", "description": "Labels for posts, profiles, and reviews." }, { "name": "Markets", "description": "Markets and storefront settings." }, { "name": "Profiles", "description": "Customer profiles." }, { "name": "Members", "description": "Loyalty members, points, rewards, and tier progress." }, { "name": "Tiers", "description": "Loyalty tiers." }, { "name": "Posts", "description": "Posts." }, { "name": "Products", "description": "Products and variants." }, { "name": "Orders", "description": "Orders." }, { "name": "Reviews", "description": "Product and company reviews, summaries, imports, and review requests." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API 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", "null" ], "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": [] } }, "ErrorResponse": { "type": "object", "properties": { "additional_data": { "type": "object", "additionalProperties": {}, "description": "Optional machine-readable error details.", "example": { "errors": [ { "field": "query.market", "message": "Invalid input: expected string, received array" } ] } }, "status": { "type": "number", "description": "HTTP status code for the error response.", "example": 404 }, "code": { "type": "string", "description": "Stable machine-readable error code.", "example": "not_found" }, "message": { "type": "string", "description": "Human-readable description of the error.", "example": "Route not found" }, "request_id": { "type": "string", "description": "Request identifier for support and tracing.", "example": "req_abc123" } }, "required": [ "status", "code", "message" ] }, "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", "null" ], "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 } } }, "ReviewQuestionDisplay": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "scope": { "type": "string", "enum": [ "PRODUCT", "COMPANY" ], "example": "PRODUCT" }, "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" } } }, "is_archived": { "type": "boolean", "example": false } }, "required": [ "id", "scope", "type", "prompt", "format", "is_archived" ], "description": "Current question wording and options, including archived questions referenced by reviews." }, "ProductReviewResource": { "type": "object", "properties": { "id": { "type": "string", "example": "rev_abc123", "description": "Cevoid public product review 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." }, "status": { "type": "string", "enum": [ "PENDING", "PUBLISHED", "REJECTED", "CONVERTED" ], "example": "PUBLISHED", "description": "Moderation and conversion state." }, "rejection_reasons": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "FAKE", "DUPLICATE", "OFF_TOPIC", "PROFANE", "ILLEGAL", "PII" ], "example": "SPAM" }, "description": "Policy reasons recorded when moderation rejected the review. Empty unless status is REJECTED; a single take-down can carry several." }, "identity_verification": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "EXPIRED" ], "example": "CONFIRMED", "description": "Author verification state. Public display requires CONFIRMED." }, "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." }, "source": { "type": "object", "properties": { "platform": { "type": "string", "example": "yotpo", "description": "Source-system slug, such as okendo or yotpo." }, "external_id": { "type": "string", "example": "review_123", "description": "Review identifier in the source system." }, "url": { "type": "string", "example": "https://example.com/reviews/123", "description": "Link to the review in its source system." } }, "required": [ "platform" ], "description": "External provenance. Present for imported or syndicated reviews." }, "profile_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "prf_abc123", "description": "Reviewer reference; null when the profile no longer resolves." }, "market_id": { "type": "string", "example": "mar_abc123", "description": "Cevoid public market identifier." }, "order_id": { "type": "string", "example": "ord_abc123", "description": "Cevoid public identifier of the matched order." }, "reward_id": { "type": "string", "example": "rwd_abc123", "description": "Granted reward, when the review was incentivized." }, "converted_from_id": { "type": "string", "example": "rev_original", "description": "Review this one was converted from." }, "converted_to_id": { "type": "string", "example": "crv_replacement", "description": "Replacement review created by conversion." }, "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." }, "moderation_status": { "type": "string", "enum": [ "PENDING", "APPROVED", "DECLINED" ], "example": "APPROVED", "description": "Moderation state for this asset, independent from the review itself." }, "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" ] } }, "responses": { "type": "array", "items": { "type": "object", "properties": { "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reply text as published." }, "author_type": { "type": "string", "enum": [ "WORKSPACE", "TEAM_MEMBER" ], "example": "WORKSPACE", "description": "Whether the workspace or a named team member authored the reply." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when the reply was created." }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when the reply was last edited." }, "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." } }, "required": [ "body", "author_type", "created_at", "id" ] } }, "helpful_up_count": { "type": "number", "example": 3, "description": "Positive helpful votes from shoppers." }, "helpful_down_count": { "type": "number", "example": 0, "description": "Negative helpful votes, when down-voting is enabled." }, "submitted_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when submission completed." }, "approved_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when moderation approved it." }, "published_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when it first became public." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when Cevoid created the review." }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when Cevoid last updated the review." }, "answers": { "type": "array", "items": { "type": "object", "properties": { "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" } } ], "description": "Original submitted value; selection keys are never translated." } }, "required": [ "question_id", "value" ] } }, "pinned_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when pinned to its product." }, "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." }, "product_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "prd_abc123", "description": "Opaque Cevoid identifier." }, "variant_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "var_abc123", "description": "Opaque Cevoid identifier." } }, "required": [ "id", "rating", "language", "status", "rejection_reasons", "identity_verification", "purchase_verification", "is_incentivized", "is_insider", "channel", "profile_id", "media", "responses", "helpful_up_count", "helpful_down_count", "created_at", "updated_at", "answers", "product_id", "variant_id" ], "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", "status": "PENDING", "rejection_reasons": [], "identity_verification": "CONFIRMED", "profile_id": "prf_abc123", "helpful_up_count": 0, "helpful_down_count": 0, "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z", "product_id": "prd_abc123", "variant_id": "var_abc123" } }, "SafeProductReview": { "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" ] } }, "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" ] }, "is_pinned": { "type": "boolean", "example": false }, "product_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "prd_abc123", "description": "Opaque Cevoid identifier." }, "variant_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "var_abc123", "description": "Opaque Cevoid identifier." }, "answers": { "type": "array", "items": { "type": "object", "properties": { "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" } } ], "description": "Original submitted value; selection keys are never translated." } }, "required": [ "question_id", "value" ] } } }, "required": [ "id", "rating", "language", "purchase_verification", "is_incentivized", "is_insider", "channel", "reviewer", "media", "responses", "is_pinned", "product_id", "variant_id", "answers" ] }, "Product": { "oneOf": [ { "type": "object", "properties": { "market_id": { "type": "string", "description": "Cevoid market ID for this product presentation.", "example": "mar_sweden" }, "external_id": { "type": "string", "description": "Product identifier from the connected commerce platform.", "example": "shopify_product_123" }, "title": { "type": "string", "description": "Market-specific product title.", "example": "Merino crew neck" }, "variant_title": { "type": "string", "description": "Market-specific variant option label.", "example": "Navy / M" }, "sku": { "type": "string", "description": "Market-specific stock keeping unit.", "example": "MERINO-NAVY-M" }, "url": { "type": "string", "format": "uri", "description": "Storefront URL for the selected market presentation.", "example": "https://shop.example/products/merino-crew" }, "image_url": { "type": "string", "format": "uri", "description": "Primary image for the selected market presentation.", "example": "https://cdn.cevoid.com/products/merino-crew/0.jpg" }, "availability": { "type": "string", "enum": [ "IN_STOCK", "OUT_OF_STOCK" ], "description": "Availability for the selected market presentation.", "example": "IN_STOCK" }, "id": { "type": "string", "description": "Cevoid product or variant ID.", "example": "prd_abc123def456gh" }, "type": { "type": "string", "enum": [ "PRODUCT" ], "description": "Product family.", "example": "PRODUCT" }, "price": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "SEK" }, "min_amount": { "type": "number", "minimum": 0, "description": "Lowest Variant price.", "example": 799 }, "max_amount": { "type": "number", "minimum": 0, "description": "Highest Variant price.", "example": 999 } }, "required": [ "currency", "min_amount", "max_amount" ], "description": "Market-specific Product price range." } }, "required": [ "market_id", "id", "type" ] }, { "type": "object", "properties": { "market_id": { "type": "string", "description": "Cevoid market ID for this product presentation.", "example": "mar_sweden" }, "external_id": { "type": "string", "description": "Product identifier from the connected commerce platform.", "example": "shopify_product_123" }, "title": { "type": "string", "description": "Market-specific product title.", "example": "Merino crew neck" }, "variant_title": { "type": "string", "description": "Market-specific variant option label.", "example": "Navy / M" }, "sku": { "type": "string", "description": "Market-specific stock keeping unit.", "example": "MERINO-NAVY-M" }, "url": { "type": "string", "format": "uri", "description": "Storefront URL for the selected market presentation.", "example": "https://shop.example/products/merino-crew" }, "image_url": { "type": "string", "format": "uri", "description": "Primary image for the selected market presentation.", "example": "https://cdn.cevoid.com/products/merino-crew/0.jpg" }, "availability": { "type": "string", "enum": [ "IN_STOCK", "OUT_OF_STOCK" ], "description": "Availability for the selected market presentation.", "example": "IN_STOCK" }, "id": { "type": "string", "description": "Cevoid product or variant ID.", "example": "prd_abc123def456gh" }, "type": { "type": "string", "enum": [ "VARIANT" ], "description": "Purchasable Product variant.", "example": "VARIANT" }, "parent_product_id": { "type": "string", "description": "Cevoid product ID. Present when type is VARIANT.", "example": "prd_abc123def456gh" }, "price": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "SEK" }, "amount": { "type": "number", "minimum": 0, "description": "Current Variant price.", "example": 899 }, "sale_amount": { "type": "number", "minimum": 0, "description": "Sale price when active.", "example": 799 } }, "required": [ "currency", "amount" ], "description": "Market-specific Variant price." } }, "required": [ "market_id", "id", "type", "parent_product_id" ] } ], "example": { "id": "prd_abc123def456gh", "type": "PRODUCT", "market_id": "mar_sweden", "external_id": "shopify_product_123", "title": "Merino crew neck", "sku": "MERINO-CREW", "url": "https://shop.example.com/products/merino-crew", "image_url": "https://cdn.cevoid.com/products/merino-crew/0.jpg", "availability": "IN_STOCK", "price": { "currency": "SEK", "min_amount": 799, "max_amount": 999 } } }, "ImportProductReview": { "allOf": [ { "$ref": "#/components/schemas/ImportCompanyReview" }, { "type": "object", "properties": { "product_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "prd_abc123", "description": "Opaque Cevoid identifier." }, "variant_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "var_abc123", "description": "Opaque Cevoid identifier." } }, "required": [ "product_id" ], "additionalProperties": false } ], "example": { "reviewer": { "email": "jane@example.com", "name": "Jane Smith" }, "rating": 5, "body": "Comfortable and true to size.", "language": "en", "submitted_at": "2026-09-01T10:00:00.000Z", "is_incentivized": false, "is_insider": false, "source": { "platform": "yotpo", "external_id": "review_123" }, "product_id": "prd_abc123" } }, "ImportCompanyReview": { "type": "object", "properties": { "reviewer": { "anyOf": [ { "type": "object", "properties": { "profile_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "prf_abc123", "description": "Opaque Cevoid identifier." } }, "required": [ "profile_id" ], "additionalProperties": false }, { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "example": "jane@example.com" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Jane Smith" } }, "required": [ "email", "name" ], "additionalProperties": false } ] }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "example": 5 }, "title": { "type": "string", "maxLength": 300, "example": "Comfortable everyday fit" }, "body": { "type": "string", "maxLength": 10000, "example": "Comfortable and true to size." }, "language": { "type": "string", "minLength": 2, "maxLength": 35, "pattern": "^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$", "example": "en" }, "submitted_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" }, "market_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Opaque Cevoid identifier." }, "is_incentivized": { "type": "boolean", "default": false, "example": false }, "is_insider": { "type": "boolean", "default": false, "example": false }, "source": { "type": "object", "properties": { "platform": { "type": "string", "minLength": 1, "maxLength": 100, "example": "yotpo" }, "external_id": { "type": "string", "minLength": 1, "maxLength": 255, "example": "review_123" }, "url": { "type": "string", "maxLength": 2000, "format": "uri", "example": "https://example.com/reviews/123" } }, "required": [ "platform", "external_id" ], "additionalProperties": false } }, "required": [ "reviewer", "rating", "language", "submitted_at", "source" ], "additionalProperties": false, "example": { "reviewer": { "email": "jane@example.com", "name": "Jane Smith" }, "rating": 5, "body": "Comfortable and true to size.", "language": "en", "submitted_at": "2026-09-01T10:00:00.000Z", "is_incentivized": false, "is_insider": false, "source": { "platform": "yotpo", "external_id": "review_123" } } }, "CompanyReviewResource": { "allOf": [ { "$ref": "#/components/schemas/CompanyReview" }, { "type": "object", "properties": { "profile_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "prf_abc123", "description": "Reviewer reference; null when the profile no longer resolves." }, "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." }, "moderation_status": { "type": "string", "enum": [ "PENDING", "APPROVED", "DECLINED" ], "example": "APPROVED", "description": "Moderation state for this asset, independent from the review itself." }, "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" ] } }, "responses": { "type": "array", "items": { "type": "object", "properties": { "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reply text as published." }, "author_type": { "type": "string", "enum": [ "WORKSPACE", "TEAM_MEMBER" ], "example": "WORKSPACE", "description": "Whether the workspace or a named team member authored the reply." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when the reply was created." }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when the reply was last edited." }, "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." } }, "required": [ "body", "author_type", "created_at", "id" ] } }, "answers": { "type": "array", "items": { "type": "object", "properties": { "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" } } ], "description": "Original submitted value; selection keys are never translated." } }, "required": [ "question_id", "value" ] } }, "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." } } } ], "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", "status": "PENDING", "rejection_reasons": [], "identity_verification": "CONFIRMED", "profile_id": "prf_abc123", "helpful_up_count": 0, "helpful_down_count": 0, "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z" } }, "CompanyReview": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid public company review identifier.", "example": "crv_abc123" }, "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." }, "status": { "type": "string", "enum": [ "PENDING", "PUBLISHED", "REJECTED", "CONVERTED" ], "example": "PUBLISHED", "description": "Moderation and conversion state." }, "rejection_reasons": { "type": "array", "items": { "type": "string", "enum": [ "SPAM", "FAKE", "DUPLICATE", "OFF_TOPIC", "PROFANE", "ILLEGAL", "PII" ], "example": "SPAM" }, "description": "Policy reasons recorded when moderation rejected the review. Empty unless status is REJECTED; a single take-down can carry several." }, "identity_verification": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "EXPIRED" ], "example": "CONFIRMED", "description": "Author verification state. Public display requires CONFIRMED." }, "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." }, "source": { "type": "object", "properties": { "platform": { "type": "string", "example": "yotpo", "description": "Source-system slug, such as okendo or yotpo." }, "external_id": { "type": "string", "example": "review_123", "description": "Review identifier in the source system." }, "url": { "type": "string", "example": "https://example.com/reviews/123", "description": "Link to the review in its source system." } }, "required": [ "platform" ], "description": "External provenance. Present for imported or syndicated reviews." }, "profile_id": { "type": "string", "example": "prf_abc123", "description": "Cevoid public identifier of the reviewer." }, "market_id": { "type": "string", "example": "mar_abc123", "description": "Cevoid public market identifier." }, "order_id": { "type": "string", "example": "ord_abc123", "description": "Cevoid public identifier of the matched order." }, "reward_id": { "type": "string", "example": "rwd_abc123", "description": "Granted reward, when the review was incentivized." }, "converted_from_id": { "type": "string", "example": "rev_original", "description": "Review this one was converted from." }, "converted_to_id": { "type": "string", "example": "crv_replacement", "description": "Replacement review created by conversion." }, "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." }, "moderation_status": { "type": "string", "enum": [ "PENDING", "APPROVED", "DECLINED" ], "example": "APPROVED", "description": "Moderation state for this asset, independent from the review itself." } }, "required": [ "type", "url", "thumbnail_url", "aspect_ratio", "aspect_ratio_type" ] } }, "responses": { "type": "array", "items": { "type": "object", "properties": { "body": { "type": "string", "example": "Comfortable and true to size.", "description": "Reply text as published." }, "author_type": { "type": "string", "enum": [ "WORKSPACE", "TEAM_MEMBER" ], "example": "WORKSPACE", "description": "Whether the workspace or a named team member authored the reply." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when the reply was created." }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when the reply was last edited." } }, "required": [ "body", "author_type", "created_at" ] }, "description": "Public workspace replies. Private replies are never exposed." }, "helpful_up_count": { "type": "number", "example": 3, "description": "Positive helpful votes from shoppers." }, "helpful_down_count": { "type": "number", "example": 0, "description": "Negative helpful votes, when down-voting is enabled." }, "submitted_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when submission completed." }, "approved_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when moderation approved it." }, "published_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when it first became public." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when Cevoid created the review." }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z", "description": "ISO 8601 timestamp when Cevoid last updated the review." }, "answers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMPANY_ATTRIBUTE", "PROFILE_PROPERTY" ], "example": "PRODUCT_ATTRIBUTE", "description": "What the question was about." }, "prompt": { "type": "string", "example": "How does it fit?", "description": "Question wording as shown at submission time." }, "format": { "type": "string", "enum": [ "SCALE", "CENTERED_RANGE", "SINGLE_SELECT", "MULTI_SELECT", "WOULD_RECOMMEND", "NUMERIC" ], "example": "SCALE", "description": "Input shape used to interpret `value`." }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "blue" }, "label": { "type": "string", "example": "Blue" } }, "required": [ "value", "label" ] }, "description": "Options as shown at submission time." }, "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": "Scale definition as shown at submission time." }, "value": { "anyOf": [ { "type": "number", "example": 4 }, { "type": "string", "example": "blue" }, { "type": "boolean", "example": true }, { "type": "array", "items": { "type": "string", "example": "blue" } } ], "description": "Submitted scalar or selection, interpreted per `format`." } }, "required": [ "type", "prompt", "format", "value" ] } } }, "required": [ "id", "rating", "language", "status", "rejection_reasons", "identity_verification", "purchase_verification", "is_incentivized", "is_insider", "channel", "profile_id", "media", "responses", "helpful_up_count", "helpful_down_count", "created_at", "updated_at", "answers" ] }, "SafeCompanyReview": { "allOf": [ { "$ref": "#/components/schemas/DisplayCompanyReview" }, { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "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" } } ], "description": "Original submitted value; selection keys are never translated." } }, "required": [ "question_id", "value" ] } } } } ], "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" } } }, "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" } } }, "OrderReviewStatus": { "type": "object", "properties": { "order_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "ord_abc123", "description": "Opaque Cevoid identifier." }, "profile_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "prf_abc123", "description": "Opaque Cevoid identifier." }, "items": { "type": "array", "items": { "type": "object", "properties": { "external_line_id": { "type": "string", "example": "line_1", "description": "Source order line identifier, matching Orders. Product references here use Cevoid catalog identifiers." }, "product_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "prd_abc123", "description": "Opaque Cevoid identifier." }, "variant_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "var_abc123", "description": "Opaque Cevoid identifier." }, "has_review": { "type": [ "boolean", "null" ], "example": true, "description": "Whether the profile has an active review for the product, including unpublished reviews. Null when the profile or product cannot be resolved." }, "review_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "review_attribution": { "type": [ "string", "null" ], "enum": [ "THIS_ORDER", "OTHER_OCCASION", null ], "example": "THIS_ORDER" }, "can_review": { "type": "boolean", "example": true, "description": "Whether the shopper can submit a review now. This does not authorize sending an invitation." }, "reasons": { "type": "array", "items": { "type": "string", "example": "ALREADY_REVIEWED" } } }, "required": [ "external_line_id", "product_id", "variant_id", "has_review", "review_id", "review_attribution", "can_review", "reasons" ] } } }, "required": [ "order_id", "profile_id", "items" ], "example": { "order_id": "ord_abc123", "profile_id": "prf_abc123", "items": [ { "external_line_id": "line_1", "product_id": "prd_abc123", "variant_id": "var_abc123", "has_review": false, "review_id": null, "review_attribution": null, "can_review": true, "reasons": [] } ] } }, "ReviewRequest": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "kind": { "type": "string", "enum": [ "PRODUCT", "COMPANY" ], "example": "PRODUCT" }, "state": { "type": "string", "enum": [ "SCHEDULED", "ACTIVE", "EXPIRED", "CANCELLED" ], "example": "SCHEDULED" }, "profile_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "prf_abc123", "description": "Opaque Cevoid identifier." }, "order_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "ord_abc123", "description": "Opaque Cevoid identifier." }, "market_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "mar_abc123", "description": "Opaque Cevoid identifier." }, "language": { "type": "string", "example": "en" }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "prd_abc123", "description": "Opaque Cevoid identifier." }, "variant_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "example": "var_abc123", "description": "Opaque Cevoid identifier." }, "external_line_id": { "type": "string", "example": "line_1" }, "review_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "completed_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" } }, "required": [ "product_id", "variant_id" ] } }, "company_review_id": { "type": "string", "minLength": 1, "maxLength": 200, "example": "crv_abc123", "description": "Opaque Cevoid identifier." }, "company_completed_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" }, "invited_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" }, "responded_at": { "type": "string", "format": "date-time", "example": "2026-09-01T10:00:00.000Z" }, "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" } }, "required": [ "id", "kind", "state", "profile_id", "order_id", "market_id", "language", "items", "created_at", "updated_at" ], "example": { "id": "rrq_abc123", "kind": "PRODUCT", "state": "ACTIVE", "profile_id": "prf_abc123", "order_id": "ord_abc123", "market_id": "mar_abc123", "language": "en", "items": [ { "product_id": "prd_abc123", "variant_id": "var_abc123", "external_line_id": "line_1" } ], "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z" } }, "MeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } }, "required": [ "data" ], "example": { "data": { "id": "6648c0f7bb9fd2d956fb0a42", "name": "Production integration", "type": "secret", "scopes": [ "profiles:read", "members:read", "points:read" ], "workspace": { "id": "6648c0f7bb9fd2d956fb0a42", "name": "Cevoid Demo" }, "rate_limits": { "reads": 25, "writes": 10 } } } }, "Me": { "type": "object", "properties": { "id": { "type": "string", "example": "6648c0f7bb9fd2d956fb0a42" }, "name": { "type": "string", "example": "Production integration" }, "type": { "type": "string", "enum": [ "secret" ], "example": "secret" }, "scopes": { "type": "array", "items": { "type": "string", "example": "profiles:read" }, "description": "Authorization scopes granted to this secret API key.", "example": [ "profiles:read", "members:read", "points:read" ] }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "example": "6648c0f7bb9fd2d956fb0a42" }, "name": { "type": "string", "example": "Cevoid Demo" } }, "required": [ "id", "name" ] }, "rate_limits": { "$ref": "#/components/schemas/PublicApiRateLimits" } }, "required": [ "id", "name", "type", "scopes", "workspace", "rate_limits" ], "description": "Requested resource." }, "PublicApiRateLimits": { "type": "object", "properties": { "reads": { "type": "number", "description": "Read requests per second shared by all workspace keys. Each request counts once, regardless of page size.", "example": 25 }, "writes": { "type": "number", "description": "Write requests per second shared by all workspace keys, independent of the read limit. Each request counts once.", "example": 10 } }, "required": [ "reads", "writes" ], "description": "Independent read and write capacities, refilled continuously at the same number of requests per second. These values do not report remaining allowances." }, "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": {}, "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 } } }, "ApiErrorResponse": { "type": "object", "properties": { "additional_data": { "type": "object", "additionalProperties": {}, "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" ] }, "LabelsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "lbl_featured", "name": "Featured", "description": "Content selected for featured placements.", "type": "POST", "color": "#7C3AED", "emoji": "⭐", "created_at": "2026-01-10T08:00:00.000Z", "updated_at": "2026-01-10T08:00:00.000Z" } ], "has_more": true, "next_cursor": "eyJpZCI6IjY4YmYxYjE0MTQyOWExZDVjMTJmYzA0ZiJ9" } }, "Label": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid label ID.", "example": "lbl_featured" }, "name": { "type": "string", "description": "Display name of the label.", "example": "Featured" }, "description": { "type": "string", "description": "Optional explanation of how the label is used.", "example": "Content selected for featured placements." }, "type": { "type": "string", "enum": [ "POST", "MEMBER", "REVIEW" ], "description": "Resource type that can use the label.", "example": "POST" }, "color": { "type": "string", "description": "Hex color used to display the label when no emoji is set.", "example": "#7C3AED" }, "emoji": { "type": "string", "description": "Emoji used to display the label instead of its color.", "example": "⭐" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the label was created.", "example": "2026-01-10T08:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the label was last updated.", "example": "2026-01-10T08:00:00.000Z" } }, "required": [ "id", "name", "type", "created_at", "updated_at" ], "example": { "id": "lbl_featured", "name": "Featured", "description": "Content selected for featured placements.", "type": "POST", "color": "#7C3AED", "emoji": "⭐", "created_at": "2026-01-10T08:00:00.000Z", "updated_at": "2026-01-10T08:00:00.000Z" } }, "LabelResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Label" }, { "description": "Requested resource." } ] } }, "required": [ "data" ], "example": { "data": { "id": "lbl_featured", "name": "Featured", "description": "Content selected for featured placements.", "type": "POST", "color": "#7C3AED", "emoji": "⭐", "created_at": "2026-01-10T08:00:00.000Z", "updated_at": "2026-01-10T08:00:00.000Z" } } }, "CreateLabelRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name of the label.", "example": "Featured" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Explanation of how the label is used.", "example": "Content selected for featured placements." }, "type": { "type": "string", "enum": [ "POST", "MEMBER", "REVIEW" ], "description": "Resource type that can use the label.", "example": "POST" }, "color": { "type": "string", "pattern": "^#(?:[\\dA-Fa-f]{3}|[\\dA-Fa-f]{4}|[\\dA-Fa-f]{6}|[\\dA-Fa-f]{8})$", "description": "Hex color used to display the label when no emoji is set.", "example": "#7C3AED" }, "emoji": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Emoji used to display the label instead of its color.", "example": "⭐" } }, "required": [ "name", "type" ], "additionalProperties": false, "example": { "name": "Featured", "description": "Content selected for featured placements.", "type": "POST", "color": "#7C3AED", "emoji": "⭐" } }, "UpdateLabelRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name of the label.", "example": "Featured" }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000, "description": "Explanation of how the label is used, or null to remove it.", "example": null }, "type": { "type": "string", "enum": [ "POST", "MEMBER", "REVIEW" ], "description": "Resource type that can use the label.", "example": "POST" }, "color": { "type": [ "string", "null" ], "pattern": "^#(?:[\\dA-Fa-f]{3}|[\\dA-Fa-f]{4}|[\\dA-Fa-f]{6}|[\\dA-Fa-f]{8})$", "description": "Hex color used to display the label, or null to remove it.", "example": null }, "emoji": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 32, "description": "Emoji used to display the label, or null to remove it.", "example": "🔥" } }, "additionalProperties": false, "minProperties": 1, "example": { "name": "Homepage featured", "description": null, "color": null, "emoji": "🔥" } }, "MarketsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Market" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "mar_sweden", "name": "Sweden", "currency": "SEK", "country": "SE", "language": "sv-SE", "domain": "https://store.example.com", "staging_domain": "https://staging.store.example.com", "default": true, "settings": { "hide_prices": false, "round_prices": false, "display_decimals": true, "currency_position": "after", "currency_display": "kr", "decimal_delimiter": ",", "thousand_separator": " ", "unavailable_product_behavior": "hide", "out_of_stock_behavior": "show_out_of_stock_text" }, "created_at": "2026-01-10T08:00:00.000Z", "updated_at": "2026-01-10T08:00:00.000Z" } ], "has_more": true, "next_cursor": "eyJpZCI6Im1hcl9zd2VkZW4ifQ" } }, "Market": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid market ID.", "example": "mar_sweden" }, "name": { "type": "string", "description": "Display name of the Market.", "example": "Sweden" }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "SEK" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code.", "example": "SE" }, "language": { "type": "string", "description": "IETF BCP 47 locale.", "example": "sv-SE" }, "domain": { "type": "string", "description": "Production storefront URL, when configured.", "example": "https://store.example.com" }, "staging_domain": { "type": "string", "description": "Staging storefront URL, when configured.", "example": "https://staging.store.example.com" }, "default": { "type": "boolean", "description": "Whether this is the workspace fallback Market.", "example": true }, "settings": { "$ref": "#/components/schemas/MarketSettings" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the Market was created.", "example": "2024-01-10T08:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the Market was last updated.", "example": "2024-01-10T08:00:00.000Z" } }, "required": [ "id", "name", "currency", "country", "language", "default", "settings", "created_at", "updated_at" ], "example": { "id": "mar_sweden", "name": "Sweden", "currency": "SEK", "country": "SE", "language": "sv-SE", "domain": "https://store.example.com", "staging_domain": "https://staging.store.example.com", "default": true, "settings": { "hide_prices": false, "round_prices": false, "display_decimals": true, "currency_position": "after", "currency_display": "kr", "decimal_delimiter": ",", "thousand_separator": " ", "unavailable_product_behavior": "hide", "out_of_stock_behavior": "show_out_of_stock_text" }, "created_at": "2026-01-10T08:00:00.000Z", "updated_at": "2026-01-10T08:00:00.000Z" } }, "MarketSettings": { "type": "object", "properties": { "hide_prices": { "type": "boolean", "description": "Whether storefront prices are hidden.", "example": false }, "round_prices": { "type": "boolean", "description": "Whether displayed prices are rounded.", "example": false }, "display_decimals": { "type": "boolean", "description": "Whether prices include decimals.", "example": true }, "currency_position": { "type": "string", "enum": [ "before", "after" ], "description": "Whether the currency symbol appears before or after the amount.", "example": "after" }, "currency_display": { "type": "string", "description": "Currency symbol or display text.", "example": "kr" }, "decimal_delimiter": { "type": "string", "enum": [ " ", ",", "." ], "description": "Price decimal delimiter.", "example": "," }, "thousand_separator": { "type": "string", "enum": [ " ", ",", "." ], "description": "Price thousands separator.", "example": " " }, "unavailable_product_behavior": { "type": "string", "enum": [ "hide", "show_as_normal", "show_as_unavailable" ], "description": "How unavailable products are presented.", "example": "hide" }, "out_of_stock_behavior": { "type": "string", "enum": [ "show_as_normal", "hide", "show_out_of_stock_text" ], "description": "How out-of-stock products are presented.", "example": "show_out_of_stock_text" } }, "required": [ "hide_prices", "round_prices", "display_decimals", "currency_position", "currency_display", "decimal_delimiter", "thousand_separator", "unavailable_product_behavior", "out_of_stock_behavior" ], "description": "Storefront formatting and product display settings." }, "MarketResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Market" }, { "description": "Requested resource." } ] } }, "required": [ "data" ], "example": { "data": { "id": "mar_sweden", "name": "Sweden", "currency": "SEK", "country": "SE", "language": "sv-SE", "domain": "https://store.example.com", "staging_domain": "https://staging.store.example.com", "default": true, "settings": { "hide_prices": false, "round_prices": false, "display_decimals": true, "currency_position": "after", "currency_display": "kr", "decimal_delimiter": ",", "thousand_separator": " ", "unavailable_product_behavior": "hide", "out_of_stock_behavior": "show_out_of_stock_text" }, "created_at": "2026-01-10T08:00:00.000Z", "updated_at": "2026-01-10T08:00:00.000Z" } } }, "ProfilesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "prf_sarah", "external_id": "customer_7391056823401", "name": "Sarah Johnson", "first_name": "Sarah", "last_name": "Johnson", "email": "sarah.johnson@example.com", "avatar_url": "https://cdn.cevoid.com/avatars/prf_sarah/profile.jpg", "country": "US", "language": "en", "location": "San Francisco, CA", "social_instagram_handle": "sarah.lifestyle", "social_tiktok_handle": "sarah.creates", "social_x_handle": "sarah_j", "birthday": "1992-04-18", "name_display_format": "FIRST_LAST_INITIAL", "bio": "Lifestyle creator and photography enthusiast", "notes": "VIP customer; prefers email communication", "created_at": "2026-01-15T09:30:00.000Z", "updated_at": "2026-01-20T14:22:15.000Z" } ], "has_more": true, "next_cursor": "eyJpZCI6InByZl9zYXJhaCJ9" } }, "Profile": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid profile ID.", "example": "prf_abc123" }, "external_id": { "type": "string", "description": "Identifier this profile carries in the workspace source system, when known. Secret-key only.", "example": "7391056823401" }, "name": { "type": "string", "description": "Display name of the profile.", "example": "Sarah Johnson" }, "first_name": { "type": "string", "description": "First name of the profile.", "example": "Sarah" }, "last_name": { "type": "string", "description": "Last name of the profile.", "example": "Johnson" }, "email": { "type": "string", "description": "Email address for the profile. Secret-key only.", "example": "sarah.johnson@example.com" }, "avatar_url": { "type": "string", "description": "Profile image URL.", "example": "https://cdn.cevoid.com/avatars/profile123/profile.jpg" }, "country": { "type": "string", "description": "Country code associated with the profile.", "example": "US" }, "language": { "type": "string", "description": "Preferred language code associated with the profile.", "example": "en" }, "location": { "type": "string", "description": "Free-form location associated with the profile. Secret-key only.", "example": "San Francisco, CA" }, "social_instagram_handle": { "type": "string", "description": "Instagram handle associated with the profile.", "example": "sarah.lifestyle" }, "social_tiktok_handle": { "type": "string", "description": "TikTok handle associated with the profile.", "example": "sarah.creates" }, "social_x_handle": { "type": "string", "description": "X handle associated with the profile.", "example": "sarah_j" }, "birthday": { "type": "string", "format": "date", "description": "Birthday in YYYY-MM-DD format. Secret-key only.", "example": "1992-04-18" }, "name_display_format": { "type": "string", "enum": [ "FULL", "FIRST_LAST_INITIAL", "FIRST", "ANONYMOUS" ], "description": "Preferred format for displaying the profile name.", "example": "FIRST_LAST_INITIAL" }, "bio": { "type": "string", "description": "Profile biography text. Secret-key only.", "example": "Lifestyle blogger and photography enthusiast" }, "notes": { "type": "string", "description": "Notes visible only to secret keys.", "example": "VIP customer, prefers email communication" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the profile was created.", "example": "2024-01-15T09:30:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the profile was last updated.", "example": "2024-01-20T14:22:15.000Z" } }, "required": [ "id", "created_at", "updated_at" ], "example": { "id": "prf_sarah", "external_id": "customer_7391056823401", "name": "Sarah Johnson", "first_name": "Sarah", "last_name": "Johnson", "email": "sarah.johnson@example.com", "avatar_url": "https://cdn.cevoid.com/avatars/prf_sarah/profile.jpg", "country": "US", "language": "en", "location": "San Francisco, CA", "social_instagram_handle": "sarah.lifestyle", "social_tiktok_handle": "sarah.creates", "social_x_handle": "sarah_j", "birthday": "1992-04-18", "name_display_format": "FIRST_LAST_INITIAL", "bio": "Lifestyle creator and photography enthusiast", "notes": "VIP customer; prefers email communication", "created_at": "2026-01-15T09:30:00.000Z", "updated_at": "2026-01-20T14:22:15.000Z" } }, "ProfileResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Profile" }, { "description": "Requested resource." } ] } }, "required": [ "data" ], "example": { "data": { "id": "prf_sarah", "external_id": "customer_7391056823401", "name": "Sarah Johnson", "first_name": "Sarah", "last_name": "Johnson", "email": "sarah.johnson@example.com", "avatar_url": "https://cdn.cevoid.com/avatars/prf_sarah/profile.jpg", "country": "US", "language": "en", "location": "San Francisco, CA", "social_instagram_handle": "sarah.lifestyle", "social_tiktok_handle": "sarah.creates", "social_x_handle": "sarah_j", "birthday": "1992-04-18", "name_display_format": "FIRST_LAST_INITIAL", "bio": "Lifestyle creator and photography enthusiast", "notes": "VIP customer; prefers email communication", "created_at": "2026-01-15T09:30:00.000Z", "updated_at": "2026-01-20T14:22:15.000Z" } } }, "MembersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "profile_id": "prf_sarah", "status": "ACTIVE", "joined_at": "2026-01-15T09:30:00.000Z" } ], "has_more": true, "next_cursor": "eyJpZCI6InByZl9zYXJhaCJ9" } }, "Member": { "type": "object", "properties": { "profile_id": { "type": "string", "description": "Cevoid profile ID.", "example": "prf_abc123" }, "status": { "type": "string", "enum": [ "ACTIVE", "PASSIVE" ], "description": "Whether the loyalty membership currently consumes active program capacity.", "example": "ACTIVE" }, "joined_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the Profile joined the loyalty program.", "example": "2026-01-15T09:30:00.000Z" } }, "required": [ "profile_id", "status", "joined_at" ], "example": { "profile_id": "prf_sarah", "status": "ACTIVE", "joined_at": "2026-01-15T09:30:00.000Z" } }, "MemberResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Member" }, { "description": "Requested resource." } ] } }, "required": [ "data" ], "example": { "data": { "profile_id": "prf_sarah", "status": "ACTIVE", "joined_at": "2026-01-15T09:30:00.000Z" } } }, "MemberPointsSummaryResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberPointsSummary" } }, "required": [ "data" ], "example": { "data": { "total": 1250, "spendable": 1150, "pending": 100, "expiring_30d": 400, "expiring_60d": 650, "expiring_90d": 750, "lifetime_earned": 5400, "lifetime_spent": 4150, "next_expiration_at": "2026-12-31T00:00:00.000Z" } } }, "MemberPointsSummary": { "type": "object", "properties": { "total": { "type": "number", "description": "Total active and pending points.", "example": 1250 }, "spendable": { "type": "number", "description": "Active points available to spend.", "example": 1150 }, "pending": { "type": "number", "description": "Earned points not active yet.", "example": 100 }, "expiring_30d": { "type": "number", "description": "Points expiring within 30 days.", "example": 400 }, "expiring_60d": { "type": "number", "description": "Points expiring within 60 days.", "example": 650 }, "expiring_90d": { "type": "number", "description": "Points expiring within 90 days.", "example": 750 }, "lifetime_earned": { "type": "number", "description": "Points earned over the membership lifetime.", "example": 5400 }, "lifetime_spent": { "type": "number", "description": "Points spent over the membership lifetime.", "example": 4150 }, "next_expiration_at": { "type": "string", "format": "date-time", "description": "Earliest upcoming active-points expiration.", "example": "2026-12-31T00:00:00.000Z" } }, "required": [ "total", "spendable", "pending", "expiring_30d", "expiring_60d", "expiring_90d", "lifetime_earned", "lifetime_spent" ], "example": { "total": 1250, "spendable": 1150, "pending": 100, "expiring_30d": 400, "expiring_60d": 650, "expiring_90d": 750, "lifetime_earned": 5400, "lifetime_spent": 4150, "next_expiration_at": "2026-12-31T00:00:00.000Z" }, "description": "Requested resource." }, "MemberPointsTransactionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberPointTransaction" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "ptx_01hzy3d4mk8w2q", "amount": 100, "transaction_type": "EARNED", "status": "ACTIVE", "source": "ACTIVITY", "source_title": "Share a photo", "reason": "Completed mission", "earned_at": "2026-01-15T09:30:00.000Z", "activated_at": "2026-01-15T09:30:00.000Z", "expires_at": "2026-12-31T23:59:59.999Z" } ], "has_more": true, "next_cursor": "eyJpZCI6InB0eF8wMWh6eTNkNG1rOHcycSJ9" } }, "MemberPointTransaction": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid point transaction ID.", "example": "ptx_01hzy3d4mk8w2q" }, "amount": { "type": "number", "description": "Signed number of points changed by the transaction.", "example": 100 }, "transaction_type": { "type": "string", "enum": [ "EARNED", "SPENT", "EXPIRED", "ADJUSTED", "MIGRATED" ], "description": "How the transaction changed the member balance.", "example": "EARNED" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "EXPIRED", "SPENT", "CANCELLED" ], "description": "Current lifecycle status of the point transaction.", "example": "ACTIVE" }, "source": { "type": "string", "enum": [ "PURCHASE_INCENTIVE", "ACTIVITY", "REWARD_REDEMPTION", "TIER", "ADMIN", "MIGRATION" ], "description": "Program source responsible for the transaction.", "example": "ACTIVITY" }, "source_title": { "type": "string", "description": "Localized title of the source when one can be resolved.", "example": "Share a photo" }, "reason": { "type": "string", "description": "Member-facing reason for the transaction.", "example": "Completed mission" }, "additional_reason": { "type": "string", "description": "Additional audit reason recorded by an operator or migration.", "example": "Manual adjustment note" }, "earned_at": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was earned or created.", "example": "2024-01-15T09:30:00.000Z" }, "activates_at": { "type": "string", "format": "date-time", "description": "Scheduled timestamp when pending points become active.", "example": "2024-01-20T09:30:00.000Z" }, "activated_at": { "type": "string", "format": "date-time", "description": "Timestamp when pending points became active.", "example": "2024-01-20T09:30:00.000Z" }, "expires_at": { "type": "string", "format": "date-time", "description": "Scheduled timestamp when active points expire.", "example": "2025-01-31T23:59:59.999Z" }, "expired_at": { "type": "string", "format": "date-time", "description": "Timestamp when points expired.", "example": "2025-01-31T23:59:59.999Z" }, "spent_at": { "type": "string", "format": "date-time", "description": "Timestamp when points were spent.", "example": "2024-01-22T10:00:00.000Z" }, "cancelled_at": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was cancelled.", "example": "2024-01-18T09:00:00.000Z" } }, "required": [ "id", "amount", "status", "earned_at" ], "example": { "id": "ptx_01hzy3d4mk8w2q", "amount": 100, "transaction_type": "EARNED", "status": "ACTIVE", "source": "ACTIVITY", "source_title": "Share a photo", "reason": "Completed mission", "earned_at": "2026-01-15T09:30:00.000Z", "activated_at": "2026-01-15T09:30:00.000Z", "expires_at": "2026-12-31T23:59:59.999Z" } }, "MemberRewardsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberReward" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "rwd_01hzy3d4mk8w2q", "title": "10% Off Reward", "description": "Get 10% off your next order.", "type": "DISCOUNT_CODE", "icon_url": "https://cdn.cevoid.com/rewards/reward-icon.png", "fulfillment_status": "FULFILLED_AUTO", "fulfilled_at": "2026-01-15T10:00:00.000Z", "awarded_at": "2026-01-15T09:30:00.000Z", "discount_code": { "code": "SUMMER10", "external_discount_code_id": "discount-code-12345", "expires_at": "2026-12-31T23:59:59.999Z", "one_time_use_per_customer": true, "value_type": "PERCENTAGE" }, "usages": [] } ], "has_more": true, "next_cursor": "eyJpZCI6InJ3ZF8wMWh6eTNkNG1rOHcycSJ9" } }, "MemberReward": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid earned reward ID.", "example": "rwd_01hzy3d4mk8w2q" }, "title": { "type": "string", "description": "Reward title at the time it was awarded.", "example": "10% Off Reward" }, "description": { "type": "string", "description": "Member-facing reward description.", "example": "Get 10% off your next order." }, "type": { "type": "string", "enum": [ "BADGE", "DISCOUNT_CODE", "CUSTOM", "POINTS", "PRODUCT" ], "description": "Reward type.", "example": "DISCOUNT_CODE" }, "icon_url": { "type": "string", "format": "uri", "description": "Reward icon URL.", "example": "https://cdn.cevoid.com/rewards/reward-icon.png" }, "svg_icon": { "type": "string", "description": "Inline SVG icon markup.", "example": "..." }, "fulfillment_status": { "type": "string", "enum": [ "UNFULFILLED", "IN_PROGRESS", "RETRYING", "FAILED_AUTO", "FAILED_THIRD_PARTY", "FULFILLED_MANUAL", "FULFILLED_AUTO", "FULFILLED_THIRD_PARTY", "CANCELLED", "EXPIRED" ], "description": "Current fulfillment state.", "example": "FULFILLED_AUTO" }, "fulfilled_at": { "type": "string", "format": "date-time", "description": "Timestamp when fulfillment completed.", "example": "2026-01-15T10:00:00.000Z" }, "failed_reason": { "type": "string", "description": "Reason fulfillment failed.", "example": "No discount codes available" }, "awarded_at": { "type": "string", "format": "date-time", "description": "Timestamp when the reward was awarded.", "example": "2026-01-15T09:30:00.000Z" }, "invalidated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the reward was invalidated.", "example": "2026-02-01T00:00:00.000Z" }, "badge": { "$ref": "#/components/schemas/MemberRewardBadge" }, "points": { "$ref": "#/components/schemas/MemberRewardPoints" }, "discount_code": { "$ref": "#/components/schemas/MemberRewardDiscountCode" }, "product": { "$ref": "#/components/schemas/MemberRewardProduct" }, "usages": { "type": "array", "items": { "$ref": "#/components/schemas/MemberRewardUsage" }, "description": "Recorded reward usages." } }, "required": [ "id", "title", "type", "fulfillment_status", "usages" ], "example": { "id": "rwd_01hzy3d4mk8w2q", "title": "10% Off Reward", "description": "Get 10% off your next order.", "type": "DISCOUNT_CODE", "icon_url": "https://cdn.cevoid.com/rewards/reward-icon.png", "fulfillment_status": "FULFILLED_AUTO", "fulfilled_at": "2026-01-15T10:00:00.000Z", "awarded_at": "2026-01-15T09:30:00.000Z", "discount_code": { "code": "SUMMER10", "external_discount_code_id": "discount-code-12345", "expires_at": "2026-12-31T23:59:59.999Z", "one_time_use_per_customer": true, "value_type": "PERCENTAGE" }, "usages": [] } }, "MemberRewardBadge": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DEFAULT", "CUSTOM" ], "description": "Badge presentation type.", "example": "DEFAULT" }, "location": { "type": "string", "description": "Badge placement metadata.", "example": "profile" }, "icon": { "type": "string", "description": "Badge icon identifier.", "example": "star" }, "color": { "type": "string", "description": "Badge accent color.", "example": "#ffb800" } }, "required": [ "type" ], "description": "Badge-specific reward details." }, "MemberRewardPoints": { "type": "object", "properties": { "amount": { "type": "number", "description": "Points granted by the reward.", "example": 100 } }, "required": [ "amount" ], "description": "Points-specific reward details." }, "MemberRewardDiscountCode": { "type": "object", "properties": { "code": { "type": "string", "description": "Discount code granted to the member.", "example": "SUMMER10" }, "external_discount_code_id": { "type": "string", "description": "Discount code identifier in the source system, when applicable.", "example": "discount-code-12345" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the discount code expires.", "example": "2026-12-31T23:59:59.999Z" }, "one_time_use_per_customer": { "type": "boolean", "description": "Whether the member can use the code only once.", "example": true }, "value_type": { "type": "string", "enum": [ "FIXED_AMOUNT", "PERCENTAGE", "FREE_SHIPPING" ], "description": "Discount value type.", "example": "PERCENTAGE" } }, "required": [ "code", "one_time_use_per_customer" ], "description": "Discount-code reward details." }, "MemberRewardProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid product ID. Omitted when the historical product can no longer be resolved.", "example": "7391056823401" }, "code": { "type": "string", "description": "Product reward code granted to the member.", "example": "FREE-MUG-001" }, "product_url": { "type": "string", "format": "uri", "description": "Resolved storefront URL for the rewarded product.", "example": "https://store.example.com/products/free-mug" }, "external_discount_code_id": { "type": "string", "description": "Discount code identifier in the source system, when applicable.", "example": "discount-code-12345" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the product reward code expires.", "example": "2026-12-31T23:59:59.999Z" }, "one_time_use_per_customer": { "type": "boolean", "description": "Whether the member can claim the reward only once.", "example": true } }, "required": [ "code", "one_time_use_per_customer" ], "description": "Product reward details." }, "MemberRewardUsage": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Cevoid order ID. Omitted when a historical order cannot be resolved.", "example": "ord_01hzy3d4mk8w2q" }, "order_number": { "type": "string", "description": "Human-readable Order number.", "example": "#1001" }, "domain": { "type": "string", "description": "Store domain where the reward was used.", "example": "store.example.com" }, "external_order_id": { "type": "string", "description": "Order identifier in the source system, when applicable.", "example": "order-12345" }, "used_at": { "type": "string", "format": "date-time", "description": "Timestamp when the usage was recorded.", "example": "2026-01-15T10:00:00.000Z" } } }, "MemberRewardResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/MemberReward" }, { "description": "Requested resource." } ] } }, "required": [ "data" ], "example": { "data": { "id": "rwd_01hzy3d4mk8w2q", "title": "10% Off Reward", "description": "Get 10% off your next order.", "type": "DISCOUNT_CODE", "icon_url": "https://cdn.cevoid.com/rewards/reward-icon.png", "fulfillment_status": "FULFILLED_AUTO", "fulfilled_at": "2026-01-15T10:00:00.000Z", "awarded_at": "2026-01-15T09:30:00.000Z", "discount_code": { "code": "SUMMER10", "external_discount_code_id": "discount-code-12345", "expires_at": "2026-12-31T23:59:59.999Z", "one_time_use_per_customer": true, "value_type": "PERCENTAGE" }, "usages": [] } } }, "MemberTierProgressResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MemberTierProgress" } }, "required": [ "data" ], "example": { "data": { "current_tier": { "id": "tier_silver", "name": "Silver", "icon_url": "https://cdn.cevoid.com/tiers/silver.png", "expires_at": "2026-12-31T23:59:59.999Z" }, "next_tier": { "id": "tier_gold", "name": "Gold", "icon_url": "https://cdn.cevoid.com/tiers/gold.png", "milestones": [ { "type": "POINTS", "required": 1000, "current": 750, "remaining": 250, "percent_complete": 75 } ], "entry_rewards": [ { "type": "DISCOUNT_CODE", "title": "10% Off Reward" } ], "perks": [ { "value": "Exclusive early access to launches" } ] } } } }, "MemberTierProgress": { "type": "object", "properties": { "current_tier": { "$ref": "#/components/schemas/MemberCurrentTier" }, "next_tier": { "$ref": "#/components/schemas/MemberNextTier" } }, "required": [ "current_tier", "next_tier" ], "example": { "current_tier": { "id": "tier_silver", "name": "Silver", "icon_url": "https://cdn.cevoid.com/tiers/silver.png", "expires_at": "2026-12-31T23:59:59.999Z" }, "next_tier": { "id": "tier_gold", "name": "Gold", "icon_url": "https://cdn.cevoid.com/tiers/gold.png", "milestones": [ { "type": "POINTS", "required": 1000, "current": 750, "remaining": 250, "percent_complete": 75 } ], "entry_rewards": [ { "type": "DISCOUNT_CODE", "title": "10% Off Reward" } ], "perks": [ { "value": "Exclusive early access to launches" } ] } }, "description": "Requested resource." }, "MemberCurrentTier": { "allOf": [ { "$ref": "#/components/schemas/TierIdentity" }, { "type": [ "object", "null" ], "properties": { "expires_at": { "type": "string", "format": "date-time", "description": "When the current tier expires, if tier evaluations expire.", "example": "2026-12-31T23:59:59.999Z" } } } ], "description": "Current tier, or null." }, "TierIdentity": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid tier ID.", "example": "tier_gold" }, "name": { "type": "string", "description": "Display name of the tier.", "example": "Gold" }, "icon_url": { "type": "string", "description": "Optional icon representing the tier.", "example": "https://cdn.cevoid.com/tiers/gold.png" } }, "required": [ "id", "name" ] }, "MemberNextTier": { "allOf": [ { "$ref": "#/components/schemas/TierIdentity" }, { "type": [ "object", "null" ], "properties": { "milestones": { "type": "array", "items": { "$ref": "#/components/schemas/MemberTierProgressMilestone" }, "description": "Progress required for the next tier." }, "entry_rewards": { "type": "array", "items": { "$ref": "#/components/schemas/TierReward" }, "description": "Rewards granted at the next tier." }, "perks": { "type": "array", "items": { "$ref": "#/components/schemas/TierPerk" }, "description": "Perks associated with the next tier." } }, "required": [ "milestones", "entry_rewards", "perks" ] } ], "description": "Next reachable tier, or null." }, "MemberTierProgressMilestone": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "POINTS", "AMOUNT_SPENT", "NUMBER_OF_PURCHASES" ], "description": "Metric used to qualify for the next tier.", "example": "POINTS" }, "required": { "type": "number", "description": "Required amount for the next tier. AMOUNT_SPENT values use major currency units.", "example": 1000 }, "current": { "type": "number", "description": "Current progress. AMOUNT_SPENT values use major currency units.", "example": 750 }, "remaining": { "type": "number", "description": "Remaining amount. AMOUNT_SPENT values use major currency units.", "example": 250 }, "percent_complete": { "type": "number", "description": "Progress percentage, capped at 100.", "example": 75 } }, "required": [ "type", "required", "current", "remaining", "percent_complete" ] }, "TierReward": { "type": "object", "properties": { "type": { "type": "string", "description": "Reward type granted when the tier is reached.", "example": "DISCOUNT_CODE" }, "title": { "type": "string", "description": "Human-readable reward title.", "example": "10% Off Reward" }, "icon_url": { "type": "string", "description": "Optional icon representing the reward.", "example": "https://cdn.cevoid.com/rewards/reward-icon.png" } }, "required": [ "type", "title" ] }, "TierPerk": { "type": "object", "properties": { "value": { "type": "string", "description": "Human-readable perk text.", "example": "Exclusive early access to launches" } }, "required": [ "value" ] }, "TiersPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tier" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "tier_gold", "name": "Gold", "icon_url": "https://cdn.cevoid.com/tiers/gold.png", "default": false, "rank": 2, "point_multiplier": { "value": 1.5, "applies_to": "ALL" }, "milestones": [ { "type": "POINTS", "required": 1000 } ], "entry_rewards": [ { "type": "DISCOUNT_CODE", "title": "10% Off Reward", "icon_url": "https://cdn.cevoid.com/rewards/reward-icon.png" } ], "perks": [ { "value": "Exclusive early access to launches" } ] } ], "has_more": true, "next_cursor": "eyJpZCI6InRpZXJfZ29sZCJ9" } }, "Tier": { "allOf": [ { "$ref": "#/components/schemas/TierIdentity" }, { "type": "object", "properties": { "default": { "type": "boolean", "description": "Whether this is the default entry tier.", "example": false }, "rank": { "type": "number", "description": "Tier order in the regular progression.", "example": 2 }, "point_multiplier": { "$ref": "#/components/schemas/TierPointMultiplier" }, "milestones": { "type": "array", "items": { "$ref": "#/components/schemas/TierMilestone" }, "description": "Requirements used to qualify for this tier." }, "entry_rewards": { "type": "array", "items": { "$ref": "#/components/schemas/TierReward" }, "description": "Rewards granted when the Member reaches this tier." }, "perks": { "type": "array", "items": { "$ref": "#/components/schemas/TierPerk" }, "description": "Perks associated with the tier." } }, "required": [ "default", "rank", "point_multiplier", "milestones", "entry_rewards", "perks" ] } ], "example": { "id": "tier_gold", "name": "Gold", "icon_url": "https://cdn.cevoid.com/tiers/gold.png", "default": false, "rank": 2, "point_multiplier": { "value": 1.5, "applies_to": "ALL" }, "milestones": [ { "type": "POINTS", "required": 1000 } ], "entry_rewards": [ { "type": "DISCOUNT_CODE", "title": "10% Off Reward", "icon_url": "https://cdn.cevoid.com/rewards/reward-icon.png" } ], "perks": [ { "value": "Exclusive early access to launches" } ] } }, "TierPointMultiplier": { "type": "object", "properties": { "value": { "type": "number", "description": "Multiplier applied to eligible points.", "example": 1.5 }, "applies_to": { "type": "string", "enum": [ "PURCHASE", "ACTIVITY", "ALL" ], "description": "Point sources affected by the multiplier.", "example": "ALL" } }, "required": [ "value", "applies_to" ], "description": "Points multiplier configured for this tier." }, "TierMilestone": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "POINTS", "AMOUNT_SPENT", "NUMBER_OF_PURCHASES" ], "description": "Metric used to qualify for the tier.", "example": "POINTS" }, "required": { "type": "number", "description": "Required amount. AMOUNT_SPENT values use major currency units.", "example": 1000 } }, "required": [ "type", "required" ] }, "TierResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Tier" }, { "description": "Requested resource." } ] } }, "required": [ "data" ], "example": { "data": { "id": "tier_gold", "name": "Gold", "icon_url": "https://cdn.cevoid.com/tiers/gold.png", "default": false, "rank": 2, "point_multiplier": { "value": 1.5, "applies_to": "ALL" }, "milestones": [ { "type": "POINTS", "required": 1000 } ], "entry_rewards": [ { "type": "DISCOUNT_CODE", "title": "10% Off Reward", "icon_url": "https://cdn.cevoid.com/rewards/reward-icon.png" } ], "perks": [ { "value": "Exclusive early access to launches" } ] } } }, "ProductsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "prd_abc123def456gh", "type": "PRODUCT", "market_id": "mar_sweden", "external_id": "shopify_product_123", "title": "Merino crew neck", "sku": "MERINO-CREW", "url": "https://shop.example.com/products/merino-crew", "image_url": "https://cdn.cevoid.com/products/merino-crew/0.jpg", "availability": "IN_STOCK", "price": { "currency": "SEK", "min_amount": 799, "max_amount": 999 } }, { "id": "var_abc123def456gh", "type": "VARIANT", "parent_product_id": "prd_abc123def456gh", "market_id": "mar_sweden", "external_id": "shopify_variant_456", "title": "Merino crew neck", "variant_title": "Navy / M", "sku": "MERINO-CREW-NAVY-M", "url": "https://shop.example.com/products/merino-crew?variant=navy-m", "image_url": "https://cdn.cevoid.com/products/merino-crew/navy-m.jpg", "availability": "IN_STOCK", "price": { "currency": "SEK", "amount": 899, "sale_amount": 799 } } ], "has_more": true, "next_cursor": "eyJpZCI6IjY4YTUwYjNkMWYwMDAwMDAwMDAwMDAwMCJ9" } }, "ProductResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Product" }, { "description": "Requested resource." } ] } }, "required": [ "data" ], "example": { "data": { "id": "prd_abc123def456gh", "type": "PRODUCT", "market_id": "mar_sweden", "external_id": "shopify_product_123", "title": "Merino crew neck", "sku": "MERINO-CREW", "url": "https://shop.example.com/products/merino-crew", "image_url": "https://cdn.cevoid.com/products/merino-crew/0.jpg", "availability": "IN_STOCK", "price": { "currency": "SEK", "min_amount": 799, "max_amount": 999 } } } }, "PostsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" }, "included": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" }, "description": "Products referenced by this page, localized to market. Join tagged_products.product_id to id.", "example": [ { "id": "prd_abc123def456gh", "type": "PRODUCT", "market_id": "mar_sweden", "external_id": "shopify_product_123", "title": "Merino crew neck", "sku": "MERINO-CREW", "url": "https://shop.example.com/products/merino-crew", "image_url": "https://cdn.cevoid.com/products/merino-crew/0.jpg", "availability": "IN_STOCK", "price": { "currency": "SEK", "min_amount": 799, "max_amount": 999 } } ] }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" }, "description": "Profiles referenced by this page. Join profile_id to id. Contains secret-key profile fields; keep server-side.", "example": [ { "id": "prf_sarah", "external_id": "customer_7391056823401", "name": "Sarah Johnson", "first_name": "Sarah", "last_name": "Johnson", "email": "sarah.johnson@example.com", "avatar_url": "https://cdn.cevoid.com/avatars/prf_sarah/profile.jpg", "country": "US", "language": "en", "location": "San Francisco, CA", "social_instagram_handle": "sarah.lifestyle", "social_tiktok_handle": "sarah.creates", "social_x_handle": "sarah_j", "birthday": "1992-04-18", "name_display_format": "FIRST_LAST_INITIAL", "bio": "Lifestyle creator and photography enthusiast", "notes": "VIP customer; prefers email communication", "created_at": "2026-01-15T09:30:00.000Z", "updated_at": "2026-01-20T14:22:15.000Z" } ] } } } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "pst_summerlook", "profile_id": "prf_sarah", "added_by_workspace": false, "origin": { "type": "INSTAGRAM_TAGGED" }, "type": "VIDEO", "status": "APPROVED", "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", "filename": "summer-look.jpg", "aspect_ratio": 1.25, "duration_seconds": 12.5, "has_audio": true }, "caption": "Summer outfit", "hide_caption": false, "language": "en", "alt": "Person wearing a linen shirt", "video_captions": "WEBVTT\n\n00:00.000 --> 00:02.000\nSummer outfit.", "video_description": "A person shows a summer outfit.", "source": { "platform": "INSTAGRAM", "external_id": "18000000000000000", "url": "https://www.instagram.com/p/example/", "posted_at": "2026-08-01T09:00:00.000Z" }, "custom_link": { "url": "https://shop.example.com/summer", "title": "Shop the summer edit", "description": "Explore the complete look.", "image_url": "https://cdn.cevoid.com/links/summer.jpg" }, "labels": [ "lbl_summer", "lbl_featured" ], "tagged_products": [ { "product_id": "prd_abc123def456gh", "x": 0.35, "y": 0.65 } ], "posted_at": "2026-08-01T09:00:00.000Z", "created_at": "2026-08-01T10:00:00.000Z", "updated_at": "2026-08-02T10:00:00.000Z" } ], "has_more": true, "next_cursor": "eyJpZCI6InBzdF9zdW1tZXJsb29rIn0" } }, "Post": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid post ID.", "example": "pst_abc123" }, "profile_id": { "type": "string", "description": "Cevoid profile ID for the contributor, when known.", "example": "prf_abc123" }, "added_by_workspace": { "type": "boolean", "description": "Whether the post was added by the workspace rather than a profile.", "example": false }, "custom_username": { "type": "string", "description": "Post-specific display-name override, when set.", "example": "The weekend crew" }, "type": { "type": "string", "enum": [ "IMAGE", "VIDEO" ], "description": "Primary media type.", "example": "IMAGE" }, "status": { "type": "string", "enum": [ "APPROVED", "PENDING", "DECLINED", "REMOVED", "NONE" ], "description": "Moderation state.", "example": "APPROVED" }, "media": { "$ref": "#/components/schemas/PostMedia" }, "caption": { "type": "string", "description": "Contributor caption.", "example": "Summer outfit" }, "hide_caption": { "type": "boolean", "description": "Whether clients should hide the caption.", "example": false }, "language": { "type": "string", "description": "IETF BCP 47 language tag for the caption.", "example": "en" }, "alt": { "type": "string", "description": "Alternative text for the media.", "example": "Person wearing a linen shirt" }, "video_captions": { "type": "string", "description": "WebVTT captions for video media.", "example": "WEBVTT\n\n00:00.000 --> 00:02.000\nSummer outfit." }, "video_description": { "type": "string", "description": "Accessible description of video content.", "example": "A person shows a summer outfit." }, "source": { "$ref": "#/components/schemas/PostSource" }, "origin": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "INSTAGRAM_FEED", "INSTAGRAM_HASHTAG", "INSTAGRAM_TAGGED", "INSTAGRAM_MENTIONED", "TIKTOK_FEED", "CEVOID_GENERAL", "CEVOID_CUSTOM", "WORKSPACE_UPLOADS", "WORKSPACE_COPIES", "WORKSPACE_IMPORTS", "ACTIVITIES" ], "description": "How the post entered the workspace. Omitted when the origin is unknown.", "example": "WORKSPACE_UPLOADS" } }, "required": [ "type" ] }, "custom_link": { "$ref": "#/components/schemas/PostCustomLink" }, "labels": { "type": "array", "items": { "type": "string", "description": "Cevoid label ID.", "example": "lbl_summer" }, "description": "Cevoid label IDs assigned to the post.", "example": [ "lbl_summer", "lbl_featured" ] }, "tagged_products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Cevoid product ID.", "example": "prd_abc123" }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized horizontal position.", "example": 0.35 }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized vertical position.", "example": 0.65 } }, "required": [ "product_id" ] } }, "posted_at": { "type": "string", "format": "date-time", "description": "Effective content date. Uses the stored posted date, falling back to the Instagram date, TikTok date, then creation date for legacy posts. Does not change list ordering.", "example": "2026-08-01T09:00:00.000Z" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the Post was created.", "example": "2026-08-01T10:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the Post was last updated.", "example": "2026-08-02T10:00:00.000Z" } }, "required": [ "id", "added_by_workspace", "type", "status", "media", "hide_caption", "labels", "tagged_products", "posted_at", "created_at", "updated_at" ], "example": { "id": "pst_summerlook", "profile_id": "prf_sarah", "added_by_workspace": false, "origin": { "type": "INSTAGRAM_TAGGED" }, "type": "VIDEO", "status": "APPROVED", "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", "filename": "summer-look.jpg", "aspect_ratio": 1.25, "duration_seconds": 12.5, "has_audio": true }, "caption": "Summer outfit", "hide_caption": false, "language": "en", "alt": "Person wearing a linen shirt", "video_captions": "WEBVTT\n\n00:00.000 --> 00:02.000\nSummer outfit.", "video_description": "A person shows a summer outfit.", "source": { "platform": "INSTAGRAM", "external_id": "18000000000000000", "url": "https://www.instagram.com/p/example/", "posted_at": "2026-08-01T09:00:00.000Z" }, "custom_link": { "url": "https://shop.example.com/summer", "title": "Shop the summer edit", "description": "Explore the complete look.", "image_url": "https://cdn.cevoid.com/links/summer.jpg" }, "labels": [ "lbl_summer", "lbl_featured" ], "tagged_products": [ { "product_id": "prd_abc123def456gh", "x": 0.35, "y": 0.65 } ], "posted_at": "2026-08-01T09:00:00.000Z", "created_at": "2026-08-01T10:00:00.000Z", "updated_at": "2026-08-02T10:00:00.000Z" } }, "PostMedia": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Delivery URL for the media asset.", "example": "https://cdn.cevoid.com/posts/pst_abc123.jpg" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Smaller preview image when available.", "example": "https://cdn.cevoid.com/posts/pst_abc123-thumbnail.jpg" }, "sprite_url": { "type": "string", "format": "uri", "description": "Video sprite image for timeline previews when available.", "example": "https://cdn.cevoid.com/posts/pst_abc123-sprite.jpg" }, "blurhash": { "type": "string", "description": "BlurHash placeholder for the media asset.", "example": "LEHV6nWB2yk8pyo0adR*.7kCMdnj" }, "filename": { "type": "string", "description": "Original filename, when available.", "example": "summer-look.jpg" }, "aspect_ratio": { "type": "number", "exclusiveMinimum": 0, "description": "Width divided by height.", "example": 1.25 }, "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" ] }, "PostSource": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "INSTAGRAM", "TIKTOK" ], "description": "External platform where the post originated.", "example": "INSTAGRAM" }, "carousel_index": { "type": "integer", "minimum": 0, "description": "Zero-based position within the source carousel. Omitted for standalone posts or unknown positions. Group slides by platform and external_id when available.", "example": 0 }, "username": { "type": "string", "description": "Source account username when stored with the post.", "example": "sarah.lifestyle" }, "external_id": { "type": "string", "description": "Post identifier from the external platform.", "example": "18000000000000000" }, "url": { "type": "string", "format": "uri", "description": "Original public post URL.", "example": "https://www.instagram.com/p/example/" }, "posted_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the external post was published.", "example": "2026-08-01T09:00:00.000Z" } }, "required": [ "platform" ] }, "PostCustomLink": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Destination URL.", "example": "https://shop.example.com/summer" }, "title": { "type": "string", "description": "Link title.", "example": "Shop the summer edit" }, "description": { "type": "string", "description": "Link description.", "example": "Explore the complete look." }, "image_url": { "type": "string", "format": "uri", "description": "Link preview image.", "example": "https://cdn.cevoid.com/links/summer.jpg" } }, "required": [ "url", "title" ] }, "PostResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Post" }, { "description": "Requested resource." } ] }, "included": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" }, "description": "Products referenced by this page, localized to market. Join tagged_products.product_id to id.", "example": [ { "id": "prd_abc123def456gh", "type": "PRODUCT", "market_id": "mar_sweden", "external_id": "shopify_product_123", "title": "Merino crew neck", "sku": "MERINO-CREW", "url": "https://shop.example.com/products/merino-crew", "image_url": "https://cdn.cevoid.com/products/merino-crew/0.jpg", "availability": "IN_STOCK", "price": { "currency": "SEK", "min_amount": 799, "max_amount": 999 } } ] }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" }, "description": "Profiles referenced by this page. Join profile_id to id. Contains secret-key profile fields; keep server-side.", "example": [ { "id": "prf_sarah", "external_id": "customer_7391056823401", "name": "Sarah Johnson", "first_name": "Sarah", "last_name": "Johnson", "email": "sarah.johnson@example.com", "avatar_url": "https://cdn.cevoid.com/avatars/prf_sarah/profile.jpg", "country": "US", "language": "en", "location": "San Francisco, CA", "social_instagram_handle": "sarah.lifestyle", "social_tiktok_handle": "sarah.creates", "social_x_handle": "sarah_j", "birthday": "1992-04-18", "name_display_format": "FIRST_LAST_INITIAL", "bio": "Lifestyle creator and photography enthusiast", "notes": "VIP customer; prefers email communication", "created_at": "2026-01-15T09:30:00.000Z", "updated_at": "2026-01-20T14:22:15.000Z" } ] } } } }, "required": [ "data" ], "example": { "data": { "id": "pst_summerlook", "profile_id": "prf_sarah", "added_by_workspace": false, "origin": { "type": "INSTAGRAM_TAGGED" }, "type": "VIDEO", "status": "APPROVED", "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", "filename": "summer-look.jpg", "aspect_ratio": 1.25, "duration_seconds": 12.5, "has_audio": true }, "caption": "Summer outfit", "hide_caption": false, "language": "en", "alt": "Person wearing a linen shirt", "video_captions": "WEBVTT\n\n00:00.000 --> 00:02.000\nSummer outfit.", "video_description": "A person shows a summer outfit.", "source": { "platform": "INSTAGRAM", "external_id": "18000000000000000", "url": "https://www.instagram.com/p/example/", "posted_at": "2026-08-01T09:00:00.000Z" }, "custom_link": { "url": "https://shop.example.com/summer", "title": "Shop the summer edit", "description": "Explore the complete look.", "image_url": "https://cdn.cevoid.com/links/summer.jpg" }, "labels": [ "lbl_summer", "lbl_featured" ], "tagged_products": [ { "product_id": "prd_abc123def456gh", "x": 0.35, "y": 0.65 } ], "posted_at": "2026-08-01T09:00:00.000Z", "created_at": "2026-08-01T10:00:00.000Z", "updated_at": "2026-08-02T10:00:00.000Z" } } }, "OrdersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "description": "Items returned for this page." }, "has_more": { "type": "boolean", "description": "Whether another page of results is available.", "example": true }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to request the next page, or null when the list is exhausted.", "example": "eyJpZCI6InJlc291cmNlXzI1In0" } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "ord_abc123", "ingestion_mode": "live", "source": { "type": "PUBLIC_API", "connection_id": "erp-production", "external_order_id": "order_123" }, "order_number": "#1001", "buyer": { "email": "buyer@example.com", "external_customer_id": "customer_123", "profile_id": "prf_sarah" }, "placed_at": "2026-07-24T09:00:00.000Z", "currency": "USD", "money": { "sub_total": 50, "discount": 5, "tax": 5, "shipping": 5, "total": 55, "refunded": 0 }, "fulfillment_status": "PENDING", "financial_status": "PAID", "paid_at": "2026-07-24T09:00:01.000Z", "cancelled": false, "market_id": "mar_us", "lines": [ { "external_line_id": "line_1", "product_id": "product_123", "variant_id": "variant_456", "sku": "TSHIRT-BLACK-M", "quantity": 1, "unit_price": 50, "discount": 0, "refund": 0, "returned_units": 0, "fulfillment_status": "PENDING" } ], "created_at": "2026-07-24T09:00:01.000Z", "updated_at": "2026-07-24T09:00:01.000Z" } ], "has_more": true, "next_cursor": "eyJpZCI6Im9yZF9hYmMxMjMifQ" } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "description": "Cevoid order ID.", "example": "ord_abc123" }, "ingestion_mode": { "type": "string", "enum": [ "live", "historical" ], "description": "Processing mode of the latest order write. Historical mode suppresses automatic Flows. Live mode allows new lifecycle transitions to trigger Flows. Absent for orders without a live or historical mode.", "example": "live" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SHOPIFY", "WOOCOMMERCE", "MYSTORE", "NORDISK_EHANDEL", "VISKAN", "CENTRA", "PUBLIC_API", "OTHER" ], "description": "System that owns this order. Absent when the order has no connected source.", "example": "PUBLIC_API" }, "connection_id": { "type": "string", "description": "Stable source namespace for the order. Absent when the order has no connected source.", "example": "erp-production" }, "external_order_id": { "type": "string", "description": "Order identifier in the source system.", "example": "order_123" } }, "required": [ "external_order_id" ] }, "order_number": { "type": "string", "description": "Customer-facing order number.", "example": "#1001" }, "buyer": { "type": "object", "properties": { "email": { "type": "string", "description": "Buyer email as supplied by the source system.", "example": "buyer@example.com" }, "external_customer_id": { "type": "string", "description": "Customer identifier in the source system.", "example": "customer_123" }, "profile_id": { "type": "string", "description": "Cevoid profile ID. Absent when no profile is linked to the order.", "example": "prf_sarah" } }, "description": "Buyer identity. Absent when the order carries no buyer information." }, "placed_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the order was placed.", "example": "2026-07-24T09:00:00.000Z" }, "currency": { "type": "string", "description": "Three-letter uppercase ISO currency code.", "example": "USD" }, "money": { "type": "object", "properties": { "total": { "type": "number", "description": "Current declared order total.", "example": 55 }, "sub_total": { "type": "number", "description": "Current merchandise subtotal.", "example": 50 }, "discount": { "type": "number", "description": "Current order-level discount total.", "example": 5 }, "tax": { "type": "number", "description": "Current order-level tax total.", "example": 5 }, "shipping": { "type": "number", "description": "Current order-level shipping total.", "example": 5 }, "refunded": { "type": "number", "description": "Cumulative refunded amount.", "example": 0 } }, "required": [ "total", "sub_total" ] }, "fulfillment_status": { "type": "string", "enum": [ "PENDING", "PARTIALLY_FULFILLED", "FULFILLED", "DELIVERED" ], "description": "Current order fulfillment state.", "example": "PENDING" }, "financial_status": { "type": "string", "enum": [ "PENDING", "PAID", "PARTIALLY_REFUNDED", "REFUNDED" ], "description": "Current order payment state.", "example": "PAID" }, "fulfilled_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the order was fulfilled.", "example": "2026-07-25T10:00:00.000Z" }, "delivered_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the order was delivered.", "example": "2026-07-26T14:00:00.000Z" }, "cancelled": { "type": "boolean", "description": "Whether the order is cancelled.", "example": false }, "cancelled_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the order was cancelled.", "example": "2026-07-24T10:00:00.000Z" }, "paid_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the order was paid.", "example": "2026-07-24T09:00:01.000Z" }, "last_refunded_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of the most recent refund.", "example": "2026-07-28T11:00:00.000Z" }, "market_id": { "type": "string", "description": "Cevoid market ID.", "example": "mar_us" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "external_line_id": { "type": "string", "description": "Stable line identifier within the source order.", "example": "line_1" }, "product_id": { "type": "string", "description": "Product identifier in the source catalog. Absent when the line names no product.", "example": "product_123" }, "variant_id": { "type": "string", "description": "Variant identifier in the source catalog.", "example": "variant_456" }, "sku": { "type": "string", "description": "Merchant SKU snapshot.", "example": "TSHIRT-BLACK-M" }, "quantity": { "type": "integer", "minimum": 0, "description": "Absolute ordered quantity.", "example": 1 }, "unit_price": { "type": "number", "description": "Price per unit in the order currency.", "example": 50 }, "discount": { "type": "number", "description": "Discount allocated to this line.", "example": 0 }, "refund": { "type": "number", "description": "Cumulative amount refunded for this line.", "example": 0 }, "returned_units": { "type": "integer", "minimum": 0, "description": "Absolute number of returned units.", "example": 0 }, "fulfillment_status": { "type": "string", "enum": [ "PENDING", "PARTIALLY_FULFILLED", "FULFILLED", "DELIVERED" ], "description": "Current fulfillment state for this line.", "example": "PENDING" }, "delivered_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when this line was delivered.", "example": "2026-07-26T14:00:00.000Z" }, "removed_at": { "type": "string", "format": "date-time", "description": "Time the line was removed from the order.", "example": "2026-07-27T14:00:00.000Z" } }, "required": [ "external_line_id", "quantity", "unit_price", "fulfillment_status" ] } }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when Cevoid created the order.", "example": "2026-07-24T09:00:01.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when Cevoid last updated the order.", "example": "2026-07-24T09:00:01.000Z" }, "removed_at": { "type": "string", "format": "date-time", "description": "Time the order was deleted.", "example": "2026-08-01T09:00:00.000Z" } }, "required": [ "id", "source", "placed_at", "currency", "money", "fulfillment_status", "financial_status", "cancelled", "lines", "created_at", "updated_at" ], "example": { "id": "ord_abc123", "ingestion_mode": "live", "source": { "type": "PUBLIC_API", "connection_id": "erp-production", "external_order_id": "order_123" }, "order_number": "#1001", "buyer": { "email": "buyer@example.com", "external_customer_id": "customer_123", "profile_id": "prf_sarah" }, "placed_at": "2026-07-24T09:00:00.000Z", "currency": "USD", "money": { "sub_total": 50, "discount": 5, "tax": 5, "shipping": 5, "total": 55, "refunded": 0 }, "fulfillment_status": "PENDING", "financial_status": "PAID", "paid_at": "2026-07-24T09:00:01.000Z", "cancelled": false, "market_id": "mar_us", "lines": [ { "external_line_id": "line_1", "product_id": "product_123", "variant_id": "variant_456", "sku": "TSHIRT-BLACK-M", "quantity": 1, "unit_price": 50, "discount": 0, "refund": 0, "returned_units": 0, "fulfillment_status": "PENDING" } ], "created_at": "2026-07-24T09:00:01.000Z", "updated_at": "2026-07-24T09:00:01.000Z" } }, "OrderResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Order" }, { "description": "Requested resource." } ] } }, "required": [ "data" ], "example": { "data": { "id": "ord_abc123", "ingestion_mode": "live", "source": { "type": "PUBLIC_API", "connection_id": "erp-production", "external_order_id": "order_123" }, "order_number": "#1001", "buyer": { "email": "buyer@example.com", "external_customer_id": "customer_123", "profile_id": "prf_sarah" }, "placed_at": "2026-07-24T09:00:00.000Z", "currency": "USD", "money": { "sub_total": 50, "discount": 5, "tax": 5, "shipping": 5, "total": 55, "refunded": 0 }, "fulfillment_status": "PENDING", "financial_status": "PAID", "paid_at": "2026-07-24T09:00:01.000Z", "cancelled": false, "market_id": "mar_us", "lines": [ { "external_line_id": "line_1", "product_id": "product_123", "variant_id": "variant_456", "sku": "TSHIRT-BLACK-M", "quantity": 1, "unit_price": 50, "discount": 0, "refund": 0, "returned_units": 0, "fulfillment_status": "PENDING" } ], "created_at": "2026-07-24T09:00:01.000Z", "updated_at": "2026-07-24T09:00:01.000Z" } } }, "IdempotencyConflictResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": {} } ], "example": { "status": 409, "code": "conflict", "message": "Idempotency-Key was already used for a different request", "request_id": "req_abc123" } } }, "parameters": {} }, "paths": { "/v2/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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/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", "maxLength": 100, "example": "questions,localization", "description": "Comma-separated includes: questions, localization. Localization returns originals for included question definitions only; request both to receive them." }, "required": false, "description": "Comma-separated includes: questions, localization. Localization returns originals for included question definitions only; request both to receive them.", "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/ReviewSummary" } }, "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", "null" ], "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" ] } } } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewQuestionDisplay" } } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/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", "maxLength": 100, "example": "questions,localization", "description": "Comma-separated includes: questions, localization. Localization returns originals for included question definitions only; request both to receive them." }, "required": false, "description": "Comma-separated includes: questions, localization. Localization returns originals for included question definitions only; request both to receive them.", "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/ReviewSummary" }, "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", "null" ], "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" ] } } } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewQuestionDisplay" } } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/product-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": "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", "minLength": 1, "maxLength": 200, "example": "prf_abc123", "description": "Filter by reviewer profile. An unknown or removed profile returns an empty list." }, "required": false, "description": "Filter by reviewer profile. An unknown or removed profile returns an empty list.", "name": "profile_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "prd_abc123", "description": "Filter by active product. An unknown or inactive product returns an empty list." }, "required": false, "description": "Filter by active product. An unknown or inactive product returns an empty list.", "name": "product_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "PENDING", "PUBLISHED", "REJECTED", "CONVERTED" ], "example": "PUBLISHED", "description": "Moderation and conversion state." }, "required": false, "description": "Moderation and conversion state.", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "private", "public" ], "default": "private", "example": "private", "description": "Private includes retained moderation states and operational references. Public applies shopper visibility, masking, and reviewer privacy." }, "required": false, "description": "Private includes retained moderation states and operational references. Public applies shopper visibility, masking, and reviewer privacy.", "name": "view", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "example": "products,questions,localization", "description": "Comma-separated includes: products, questions, localization. Products requires products:read. Question originals require questions and localization together." }, "required": false, "description": "Comma-separated includes: products, questions, localization. Products requires products:read. Question originals require questions and localization together.", "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": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ProductReviewResource" }, { "$ref": "#/components/schemas/SafeProductReview" } ] } }, "has_more": { "type": "boolean", "example": false, "description": "Whether another page is available." }, "next_cursor": { "type": [ "string", "null" ], "example": "eyJ2IjoxLCJjdXJzb3IiOiJyZXZfYWJjMTIzIn0", "description": "Pass unchanged as cursor to retrieve the next page. Null on the final page." }, "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", "null" ], "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", "null" ], "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", "null" ], "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", "null" ], "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" ] } } } }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewQuestionDisplay" } } } } }, "required": [ "data", "has_more", "next_cursor" ], "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": "rev_abc123", "status": "PENDING", "rejection_reasons": [], "identity_verification": "CONFIRMED", "profile_id": "prf_abc123", "helpful_up_count": 0, "helpful_down_count": 0, "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z", "product_id": "prd_abc123", "variant_id": "var_abc123" } ], "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } }, "post": { "summary": "Create product review", "description": "Creates a pending product review from imported text and source information.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Caller-generated key retained for seven days. An identical retry replays the original response; reuse for a different request returns 409.", "example": "01J3RZ0D4Q6J9T1R8M6E2P7W8X" }, "required": true, "description": "Caller-generated key retained for seven days. An identical retry replays the original response; reuse for a different request returns 409.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportProductReview" } } } }, "responses": { "201": { "description": "Created successfully", "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/ProductReviewResource" } }, "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": "rev_abc123", "status": "PENDING", "rejection_reasons": [], "identity_verification": "CONFIRMED", "profile_id": "prf_abc123", "helpful_up_count": 0, "helpful_down_count": 0, "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z", "product_id": "prd_abc123", "variant_id": "var_abc123" } } } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/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", "maxLength": 100, "example": "products,questions,localization", "description": "Comma-separated includes: products, questions, localization. Products requires products:read. Question originals require questions and localization together." }, "required": false, "description": "Comma-separated includes: products, questions, localization. Products requires products:read. Question originals require questions and localization together.", "name": "include", "in": "query" }, { "schema": { "type": "string", "enum": [ "private", "public" ], "default": "private", "example": "private", "description": "Private includes retained moderation states and operational references. Public applies shopper visibility, masking, and reviewer privacy." }, "required": false, "description": "Private includes retained moderation states and operational references. Public applies shopper visibility, masking, and reviewer privacy.", "name": "view", "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": { "anyOf": [ { "$ref": "#/components/schemas/ProductReviewResource" }, { "$ref": "#/components/schemas/SafeProductReview" } ] }, "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", "null" ], "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", "null" ], "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", "null" ], "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", "null" ], "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" ] } } } }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewQuestionDisplay" } } } } }, "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", "status": "PENDING", "rejection_reasons": [], "identity_verification": "CONFIRMED", "profile_id": "prf_abc123", "helpful_up_count": 0, "helpful_down_count": 0, "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z", "product_id": "prd_abc123", "variant_id": "var_abc123" }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/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", "maxLength": 100, "example": "questions,localization", "description": "Comma-separated includes: questions, localization. Localization returns originals for included question definitions only; request both to receive them." }, "required": false, "description": "Comma-separated includes: questions, localization. Localization returns originals for included question definitions only; request both to receive them.", "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", "null" ], "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" ] }, "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", "null" ], "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" ] } } } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewQuestionDisplay" } } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/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", "minLength": 1, "maxLength": 200, "example": "prf_abc123", "description": "Filter by reviewer profile. An unknown or removed profile returns an empty list." }, "required": false, "description": "Filter by reviewer profile. An unknown or removed profile returns an empty list.", "name": "profile_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "PENDING", "PUBLISHED", "REJECTED", "CONVERTED" ], "example": "PUBLISHED", "description": "Moderation and conversion state." }, "required": false, "description": "Moderation and conversion state.", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "private", "public" ], "default": "private", "example": "private", "description": "Private includes retained moderation states and operational references. Public applies shopper visibility, masking, and reviewer privacy." }, "required": false, "description": "Private includes retained moderation states and operational references. Public applies shopper visibility, masking, and reviewer privacy.", "name": "view", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "example": "questions,localization", "description": "Comma-separated includes: questions, localization. Question originals require both. Related products are not supported." }, "required": false, "description": "Comma-separated includes: questions, localization. Question originals require both. Related products are not supported.", "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": { "anyOf": [ { "$ref": "#/components/schemas/CompanyReviewResource" }, { "$ref": "#/components/schemas/SafeCompanyReview" } ] } }, "has_more": { "type": "boolean", "example": false, "description": "Whether another page is available." }, "next_cursor": { "type": [ "string", "null" ], "example": "eyJ2IjoxLCJjdXJzb3IiOiJyZXZfYWJjMTIzIn0", "description": "Pass unchanged as cursor to retrieve the next page. Null on the final page." }, "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", "null" ], "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", "null" ], "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", "null" ], "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", "null" ], "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" ] } } } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewQuestionDisplay" } } } } }, "required": [ "data", "has_more", "next_cursor" ], "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", "status": "PENDING", "rejection_reasons": [], "identity_verification": "CONFIRMED", "profile_id": "prf_abc123", "helpful_up_count": 0, "helpful_down_count": 0, "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z" } ], "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } }, "post": { "summary": "Create company review", "description": "Creates a pending company review from imported text and source information.", "tags": [ "Reviews" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Caller-generated key retained for seven days. An identical retry replays the original response; reuse for a different request returns 409.", "example": "01J3RZ0D4Q6J9T1R8M6E2P7W8X" }, "required": true, "description": "Caller-generated key retained for seven days. An identical retry replays the original response; reuse for a different request returns 409.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCompanyReview" } } } }, "responses": { "201": { "description": "Created successfully", "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/CompanyReviewResource" } }, "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", "status": "PENDING", "rejection_reasons": [], "identity_verification": "CONFIRMED", "profile_id": "prf_abc123", "helpful_up_count": 0, "helpful_down_count": 0, "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00: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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/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", "maxLength": 100, "example": "questions,localization", "description": "Comma-separated includes: questions, localization. Question originals require both. Related products are not supported." }, "required": false, "description": "Comma-separated includes: questions, localization. Question originals require both. Related products are not supported.", "name": "include", "in": "query" }, { "schema": { "type": "string", "enum": [ "private", "public" ], "default": "private", "example": "private", "description": "Private includes retained moderation states and operational references. Public applies shopper visibility, masking, and reviewer privacy." }, "required": false, "description": "Private includes retained moderation states and operational references. Public applies shopper visibility, masking, and reviewer privacy.", "name": "view", "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": { "anyOf": [ { "$ref": "#/components/schemas/CompanyReviewResource" }, { "$ref": "#/components/schemas/SafeCompanyReview" } ] }, "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", "null" ], "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", "null" ], "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", "null" ], "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", "null" ], "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" ] } } } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewQuestionDisplay" } } } } }, "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", "status": "PENDING", "rejection_reasons": [], "identity_verification": "CONFIRMED", "profile_id": "prf_abc123", "helpful_up_count": 0, "helpful_down_count": 0, "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z" }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/orders/{order_id}/review-status": { "get": { "summary": "Get order review status", "description": "Returns existing review references and shopper eligibility for each retained order line.", "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": "order_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", "maxLength": 100, "example": "products,reviews", "description": "Comma-separated includes: products, reviews. Products requires products:read. Reviews includes related product and company reviews and requires reviews:read. Questions and localization are not supported." }, "required": false, "description": "Comma-separated includes: products, reviews. Products requires products:read. Reviews includes related product and company reviews and requires reviews:read. Questions and localization are not supported.", "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/OrderReviewStatus" }, "included": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "product_reviews": { "type": "array", "items": { "$ref": "#/components/schemas/ProductReviewResource" } }, "company_reviews": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyReviewResource" } } } } }, "required": [ "data" ], "example": { "data": { "order_id": "ord_abc123", "profile_id": "prf_abc123", "items": [ { "external_line_id": "line_1", "product_id": "prd_abc123", "variant_id": "var_abc123", "has_review": false, "review_id": null, "review_attribution": null, "can_review": true, "reasons": [] } ] } } } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/review-requests": { "get": { "summary": "List review requests", "description": "Returns review invitations and their recorded completion state.", "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", "maxLength": 100, "example": "products,reviews", "description": "Comma-separated includes: products, reviews. Products requires products:read. Reviews includes related product and company reviews and requires reviews:read. Questions and localization are not supported." }, "required": false, "description": "Comma-separated includes: products, reviews. Products requires products:read. Reviews includes related product and company reviews and requires reviews:read. Questions and localization are not supported.", "name": "include", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "required": false, "description": "Opaque Cevoid identifier.", "name": "profile_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "rev_abc123", "description": "Opaque Cevoid identifier." }, "required": false, "description": "Opaque Cevoid identifier.", "name": "order_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "SCHEDULED", "ACTIVE", "EXPIRED", "CANCELLED" ], "example": "SCHEDULED" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "example": 25 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 3000, "example": "eyJ2IjoxLCJjdXJzb3IiOiJyZXZfYWJjMTIzIn0" }, "required": false, "name": "cursor", "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/ReviewRequest" } }, "has_more": { "type": "boolean", "example": false, "description": "Whether another page is available." }, "next_cursor": { "type": [ "string", "null" ], "example": "eyJ2IjoxLCJjdXJzb3IiOiJyZXZfYWJjMTIzIn0", "description": "Pass unchanged as cursor to retrieve the next page. Null on the final page." }, "included": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "product_reviews": { "type": "array", "items": { "$ref": "#/components/schemas/ProductReviewResource" } }, "company_reviews": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyReviewResource" } } } } }, "required": [ "data", "has_more", "next_cursor" ], "example": { "data": [ { "id": "rrq_abc123", "kind": "PRODUCT", "state": "ACTIVE", "profile_id": "prf_abc123", "order_id": "ord_abc123", "market_id": "mar_abc123", "language": "en", "items": [ { "product_id": "prd_abc123", "variant_id": "var_abc123", "external_line_id": "line_1" } ], "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00:00.000Z" } ], "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/review-requests/{request_id}": { "get": { "summary": "Get review request", "description": "Returns one review invitation and its recorded completion state.", "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": "request_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", "maxLength": 100, "example": "products,reviews", "description": "Comma-separated includes: products, reviews. Products requires products:read. Reviews includes related product and company reviews and requires reviews:read. Questions and localization are not supported." }, "required": false, "description": "Comma-separated includes: products, reviews. Products requires products:read. Reviews includes related product and company reviews and requires reviews:read. Questions and localization are not supported.", "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/ReviewRequest" }, "included": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "product_reviews": { "type": "array", "items": { "$ref": "#/components/schemas/ProductReviewResource" } }, "company_reviews": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyReviewResource" } } } } }, "required": [ "data" ], "example": { "data": { "id": "rrq_abc123", "kind": "PRODUCT", "state": "ACTIVE", "profile_id": "prf_abc123", "order_id": "ord_abc123", "market_id": "mar_abc123", "language": "en", "items": [ { "product_id": "prd_abc123", "variant_id": "var_abc123", "external_line_id": "line_1" } ], "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-01T10:00: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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/me": { "get": { "summary": "Get authentication details", "description": "Returns the authenticated API key, workspace, scopes, and rate limits.", "tags": [ "Authentication" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "mar_sweden", "description": "Market ID used to resolve localized data. Omit to use the default market." }, "required": false, "description": "Market ID used to resolve localized data. Omit to use the default market.", "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/labels": { "get": { "summary": "List labels", "description": "Returns a list of labels.", "tags": [ "Labels" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelsPage" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } }, "post": { "summary": "Create label", "description": "Creates a new label.", "tags": [ "Labels" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabelRequest" } } } }, "responses": { "201": { "description": "Created successfully", "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/LabelResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/labels/{id}": { "get": { "summary": "Get label", "description": "Returns information about a specific label.", "tags": [ "Labels" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid label ID.", "example": "lbl_featured" }, "required": true, "description": "Cevoid label ID.", "name": "id", "in": "path" } ], "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/LabelResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } }, "patch": { "summary": "Update label", "description": "Updates a specific label.", "tags": [ "Labels" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid label ID.", "example": "lbl_featured" }, "required": true, "description": "Cevoid label ID.", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLabelRequest" } } } }, "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/LabelResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } }, "delete": { "summary": "Delete label", "description": "Deletes a specific label.", "tags": [ "Labels" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid label ID.", "example": "lbl_featured" }, "required": true, "description": "Cevoid label ID.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content", "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 } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/markets": { "get": { "summary": "List markets", "description": "Returns a list of markets.", "tags": [ "Markets" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketsPage" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/markets/{id}": { "get": { "summary": "Get market", "description": "Returns information about a specific market.", "tags": [ "Markets" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid market ID.", "example": "mar_sweden" }, "required": true, "description": "Cevoid market ID.", "name": "id", "in": "path" } ], "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/MarketResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/profiles": { "get": { "summary": "List profiles", "description": "Returns a list of profiles, including profiles that have not joined the loyalty program.", "tags": [ "Profiles" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfilesResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/profiles/{id}": { "get": { "summary": "Get profile", "description": "Returns information about a specific profile.", "tags": [ "Profiles" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid profile ID.", "example": "prf_abc123" }, "required": true, "description": "Cevoid profile ID.", "name": "id", "in": "path" } ], "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/ProfileResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/members": { "get": { "summary": "List members", "description": "Returns a list of profiles that have joined the loyalty program.", "tags": [ "Members" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembersResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/members/{profile_id}": { "get": { "summary": "Get member", "description": "Returns membership information for a specific profile.", "tags": [ "Members" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid profile ID.", "example": "prf_abc123" }, "required": true, "description": "Cevoid profile ID.", "name": "profile_id", "in": "path" } ], "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/MemberResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/members/{profile_id}/points": { "get": { "summary": "Get member points summary", "description": "Returns the current points summary for a specific member.", "tags": [ "Members" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid profile ID.", "example": "prf_abc123" }, "required": true, "description": "Cevoid profile ID.", "name": "profile_id", "in": "path" } ], "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/MemberPointsSummaryResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/members/{profile_id}/points/transactions": { "get": { "summary": "List member points transactions", "description": "Returns a list of points transactions for a specific member.", "tags": [ "Members" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid profile ID.", "example": "prf_abc123" }, "required": true, "description": "Cevoid profile ID.", "name": "profile_id", "in": "path" }, { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "name": "limit", "in": "query" }, { "schema": { "type": "string", "example": "mar_sweden", "description": "Market ID used to resolve localized data. Omit to use the default market." }, "required": false, "description": "Market ID used to resolve localized data. Omit to use the default market.", "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberPointsTransactionsResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/members/{profile_id}/rewards": { "get": { "summary": "List member rewards", "description": "Returns a list of rewards earned by a specific member.", "tags": [ "Members" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid profile ID.", "example": "prf_abc123" }, "required": true, "description": "Cevoid profile ID.", "name": "profile_id", "in": "path" }, { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "name": "limit", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Optional list of reward types to include.", "example": [ "DISCOUNT_CODE", "PRODUCT" ] }, "required": false, "description": "Optional list of reward types to include.", "name": "type", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Optional list of fulfillment statuses to include.", "example": [ "FULFILLED_AUTO", "UNFULFILLED" ] }, "required": false, "description": "Optional list of fulfillment statuses to include.", "name": "fulfillment_status", "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/MemberRewardsResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/members/{profile_id}/rewards/{reward_id}": { "get": { "summary": "Get member reward", "description": "Returns information about a specific reward earned by a member.", "tags": [ "Members" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid profile ID.", "example": "prf_abc123" }, "required": true, "description": "Cevoid profile ID.", "name": "profile_id", "in": "path" }, { "schema": { "type": "string", "description": "Cevoid earned reward ID.", "example": "rwd_abc123" }, "required": true, "description": "Cevoid earned reward ID.", "name": "reward_id", "in": "path" } ], "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/MemberRewardResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/members/{profile_id}/tier-progress": { "get": { "summary": "Get member tier progress", "description": "Returns a member’s progress toward the next loyalty tier.", "tags": [ "Members" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid profile ID.", "example": "prf_abc123" }, "required": true, "description": "Cevoid profile ID.", "name": "profile_id", "in": "path" } ], "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/MemberTierProgressResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/tiers": { "get": { "summary": "List tiers", "description": "Returns a list of active loyalty tiers.", "tags": [ "Tiers" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TiersPage" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/tiers/{id}": { "get": { "summary": "Get tier", "description": "Returns information about a specific active loyalty tier.", "tags": [ "Tiers" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid tier ID.", "example": "tier_gold" }, "required": true, "description": "Cevoid tier ID.", "name": "id", "in": "path" } ], "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/TierResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/products": { "get": { "summary": "List products", "description": "Returns a list of products and product variants.", "tags": [ "Products" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "mar_sweden", "description": "Market ID used to resolve localized data. Omit to use the default market." }, "required": false, "description": "Market ID used to resolve localized data. Omit to use the default market.", "name": "market", "in": "query" }, { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductsPage" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/products/{id}": { "get": { "summary": "Get product", "description": "Returns information about a specific product or product variant.", "tags": [ "Products" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid product or variant ID.", "example": "prd_abc123def456gh" }, "required": true, "description": "Cevoid product or variant ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "mar_sweden", "description": "Market ID used to resolve localized data. Omit to use the default market." }, "required": false, "description": "Market ID used to resolve localized data. Omit to use the default market.", "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 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/posts": { "get": { "summary": "List posts", "description": "Returns a list of posts.", "tags": [ "Posts" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "name": "limit", "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, "example": "mar_sweden", "description": "Market for included product presentations. Required when including products." }, "required": false, "description": "Market for included product presentations. Required when including products.", "name": "market", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 2 } ], "example": "products,profiles", "description": "Comma-separated related data. Products requires an explicit market and products:read. Profiles requires profiles:read and returns canonical profiles referenced by profile_id." }, "required": false, "description": "Comma-separated related data. Products requires an explicit market and products:read. Profiles requires profiles:read and returns canonical profiles referenced by profile_id.", "name": "include", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "APPROVED", "PENDING", "DECLINED", "REMOVED", "NONE" ] }, { "type": "array", "items": { "type": "string", "enum": [ "APPROVED", "PENDING", "DECLINED", "REMOVED", "NONE" ] } } ], "default": [ "APPROVED", "PENDING", "DECLINED", "NONE" ], "example": [ "APPROVED", "PENDING" ], "description": "Moderation states to include. The REMOVED moderation state is excluded unless requested explicitly. Processing, archived, and removed documents are never returned." }, "required": false, "description": "Moderation states to include. The REMOVED moderation state is excluded unless requested explicitly. Processing, archived, and removed documents are never returned.", "name": "status", "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/PostsPage" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/posts/{id}": { "get": { "summary": "Get post", "description": "Returns information about a specific post.", "tags": [ "Posts" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cevoid post ID.", "example": "pst_abc123" }, "required": true, "description": "Cevoid post ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "example": "mar_sweden", "description": "Market for included product presentations. Required when including products." }, "required": false, "description": "Market for included product presentations. Required when including products.", "name": "market", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 2 } ], "example": "products,profiles", "description": "Comma-separated related data. Products requires an explicit market and products:read. Profiles requires profiles:read and returns canonical profiles referenced by profile_id." }, "required": false, "description": "Comma-separated related data. Products requires an explicit market and products:read. Profiles requires profiles:read and returns canonical profiles referenced by profile_id.", "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": { "$ref": "#/components/schemas/PostResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/orders": { "get": { "summary": "List orders", "description": "Returns a list of orders.", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "eyJpZCI6InBvc3RfMDEifQ", "description": "Opaque cursor returned from a previous list response" }, "required": false, "description": "Opaque cursor returned from a previous list response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 25, "description": "Page size between 1 and 100" }, "required": false, "description": "Page size between 1 and 100", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Search by order number, source order identifier, or buyer email.", "example": "#1001" }, "required": false, "description": "Search by order number, source order identifier, or buyer email.", "name": "query", "in": "query" }, { "schema": { "type": "string", "enum": [ "SHOPIFY", "WOOCOMMERCE", "MYSTORE", "NORDISK_EHANDEL", "VISKAN", "CENTRA", "PUBLIC_API", "OTHER" ], "description": "Filter by source system.", "example": "PUBLIC_API" }, "required": false, "description": "Filter by source system.", "name": "source_type", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filter by the exact source namespace supplied when the order was created.", "example": "erp-production" }, "required": false, "description": "Filter by the exact source namespace supplied when the order was created.", "name": "source_connection_id", "in": "query" }, { "schema": { "type": "string", "description": "Filter by Cevoid market ID.", "example": "mar_us" }, "required": false, "description": "Filter by Cevoid market ID.", "name": "market_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "PENDING", "PARTIALLY_FULFILLED", "FULFILLED", "DELIVERED" ], "description": "Filter by current fulfillment state.", "example": "PENDING" }, "required": false, "description": "Filter by current fulfillment state.", "name": "fulfillment_status", "in": "query" }, { "schema": { "type": "string", "enum": [ "PENDING", "PAID", "PARTIALLY_REFUNDED", "REFUNDED" ], "description": "Filter by current payment state.", "example": "PAID" }, "required": false, "description": "Filter by current payment state.", "name": "financial_status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Filter by an exact source product identifier on any active order line.", "example": "product_123" }, "required": false, "description": "Filter by an exact source product identifier on any active order line.", "name": "product_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound for placed_at.", "example": "2026-07-01T00:00:00.000Z" }, "required": false, "description": "Inclusive lower bound for placed_at.", "name": "placed_from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound for placed_at.", "example": "2026-07-31T23:59:59.999Z" }, "required": false, "description": "Inclusive upper bound for placed_at.", "name": "placed_to", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound for fulfilled_at.", "example": "2026-07-01T00:00:00.000Z" }, "required": false, "description": "Inclusive lower bound for fulfilled_at.", "name": "fulfilled_from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound for fulfilled_at.", "example": "2026-07-31T23:59:59.999Z" }, "required": false, "description": "Inclusive upper bound for fulfilled_at.", "name": "fulfilled_to", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound for delivered_at.", "example": "2026-07-01T00:00:00.000Z" }, "required": false, "description": "Inclusive lower bound for delivered_at.", "name": "delivered_from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound for delivered_at.", "example": "2026-07-31T23:59:59.999Z" }, "required": false, "description": "Inclusive upper bound for delivered_at.", "name": "delivered_to", "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/OrdersResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } }, "post": { "summary": "Create order", "description": "Creates a new order.", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Caller-generated key retained for seven days. An identical retry replays the original response; reuse for a different request returns 409.", "example": "01J3RZ0D4Q6J9T1R8M6E2P7W8X" }, "required": true, "description": "Caller-generated key retained for seven days. An identical retry replays the original response; reuse for a different request returns 409.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ingestion_mode": { "type": "string", "enum": [ "live", "historical" ], "default": "live", "description": "Use historical to import order history without automatic Flows or purchase-incentive points. Orders created as historical remain excluded from automatic purchase incentives after live updates. Defaults to live.", "example": "live" }, "source_connection_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Caller-owned stable source namespace, retained unchanged across credential rotations.", "example": "erp-production" }, "external_order_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Stable order identifier within source_connection_id.", "example": "order_123" }, "order_number": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Customer-facing order number.", "example": "#123" }, "domain": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Storefront domain or URL the order was placed on. Matched against market domains to assign the order to a market.", "example": "shop.example.com" }, "buyer": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Normalized buyer email. When supplied it must be valid.", "example": "buyer@example.com" }, "external_customer_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Customer identifier in the source system.", "example": "customer_123" } }, "additionalProperties": false, "description": "Buyer details set when you create the order. Cannot be changed through order updates." }, "placed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the order was placed.", "example": "2026-07-24T09:00:00.000Z" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Three-letter uppercase ISO currency code.", "example": "USD" }, "money": { "type": "object", "properties": { "total": { "type": "number", "minimum": 0, "description": "Declared order total in the order currency.", "example": 50 }, "sub_total": { "type": "number", "minimum": 0, "description": "Merchandise subtotal before order-level discount, tax, and shipping.", "example": 45 }, "discount": { "type": "number", "minimum": 0, "description": "Order-level discount total.", "example": 5 }, "tax": { "type": "number", "minimum": 0, "description": "Order-level tax total.", "example": 5 }, "shipping": { "type": "number", "minimum": 0, "description": "Order-level shipping total.", "example": 5 }, "refunded": { "type": "number", "minimum": 0, "description": "Cumulative refunded amount.", "example": 0 } }, "required": [ "total" ], "additionalProperties": false }, "fulfillment_status": { "type": "string", "enum": [ "PENDING", "PARTIALLY_FULFILLED", "FULFILLED", "DELIVERED" ], "description": "Order fulfillment state. When omitted, derived from the order lines.", "example": "PENDING" }, "financial_status": { "type": "string", "enum": [ "PENDING", "PAID", "PARTIALLY_REFUNDED", "REFUNDED" ], "default": "PENDING", "example": "PAID" }, "fulfilled_at": { "type": "string", "format": "date-time", "example": "2026-07-25T10:00:00.000Z" }, "delivered_at": { "type": "string", "format": "date-time", "example": "2026-07-26T14:00:00.000Z" }, "cancelled": { "type": "boolean", "default": false, "example": false }, "cancelled_at": { "type": "string", "format": "date-time", "example": "2026-07-24T10:00:00.000Z" }, "paid_at": { "type": "string", "format": "date-time", "example": "2026-07-24T09:00:01.000Z" }, "last_refunded_at": { "type": "string", "format": "date-time", "example": "2026-07-28T11:00:00.000Z" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "external_line_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Stable line identifier within the source order.", "example": "line_123" }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Product identifier in the source catalog.", "example": "product_123" }, "variant_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Variant identifier in the source catalog.", "example": "variant_123" }, "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Merchant SKU snapshot.", "example": "TSHIRT-BLACK-M" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "description": "Absolute ordered quantity.", "example": 2 }, "unit_price": { "type": "number", "minimum": 0, "description": "Non-negative price per unit in the order currency.", "example": 25 }, "discount": { "type": "number", "minimum": 0, "description": "Discount allocated to this line in the order currency.", "example": 5 }, "refund": { "type": "number", "minimum": 0, "description": "Amount refunded for this line in the order currency.", "example": 0 }, "returned_units": { "type": "integer", "minimum": 0, "description": "Absolute number of returned units.", "example": 0 }, "fulfillment_status": { "type": "string", "enum": [ "PENDING", "PARTIALLY_FULFILLED", "FULFILLED", "DELIVERED" ], "default": "PENDING", "description": "Absolute fulfillment state for this line.", "example": "PENDING" }, "delivered_at": { "type": "string", "format": "date-time", "description": "Delivery timestamp. Required when this line is explicitly delivered.", "example": "2026-07-24T10:00:00.000Z" } }, "required": [ "external_line_id", "quantity", "unit_price" ], "additionalProperties": false }, "minItems": 1, "description": "Order lines. At least one line is required." } }, "required": [ "source_connection_id", "external_order_id", "placed_at", "currency", "money", "lines" ], "additionalProperties": false, "example": { "ingestion_mode": "live", "source_connection_id": "erp-production", "external_order_id": "order_123", "order_number": "#1001", "domain": "shop.example.com", "buyer": { "email": "buyer@example.com", "external_customer_id": "customer_123" }, "placed_at": "2026-07-24T09:00:00.000Z", "currency": "USD", "money": { "sub_total": 50, "discount": 5, "tax": 5, "shipping": 5, "total": 55, "refunded": 0 }, "fulfillment_status": "PENDING", "financial_status": "PAID", "paid_at": "2026-07-24T09:00:01.000Z", "cancelled": false, "lines": [ { "external_line_id": "line_1", "product_id": "product_123", "variant_id": "variant_456", "sku": "TSHIRT-BLACK-M", "quantity": 1, "unit_price": 50, "discount": 0, "refund": 0, "returned_units": 0, "fulfillment_status": "PENDING" } ] } } } } }, "responses": { "201": { "description": "Created successfully", "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/OrderResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/IdempotencyConflictResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } }, "/v2/orders/{id}": { "get": { "summary": "Get order", "description": "Returns information about a specific order.", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Cevoid order ID.", "example": "ord_abc123" }, "required": true, "description": "Cevoid order ID.", "name": "id", "in": "path" } ], "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/OrderResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } }, "patch": { "summary": "Update order", "description": "Updates a specific order. Buyer details are fixed at creation; including buyer returns 422.", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Cevoid order ID.", "example": "ord_abc123" }, "required": true, "description": "Cevoid order ID.", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Caller-generated key retained for seven days. An identical retry replays the original response; reuse for a different request returns 409.", "example": "01J3RZ0D4Q6J9T1R8M6E2P7W8X" }, "required": true, "description": "Caller-generated key retained for seven days. An identical retry replays the original response; reuse for a different request returns 409.", "name": "idempotency-key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ingestion_mode": { "type": "string", "enum": [ "live", "historical" ], "description": "Omit to preserve the current mode. Historical suppresses automatic Flows; live allows new fulfillment or delivery transitions to trigger Flows. Changing only the mode does not replay past transitions or enable purchase incentives for imported orders.", "example": "live" }, "money": { "type": "object", "properties": { "total": { "type": "number", "minimum": 0, "description": "New declared order total in the order currency.", "example": 50 }, "sub_total": { "type": "number", "minimum": 0, "description": "New merchandise subtotal before order-level discount, tax, and shipping.", "example": 45 }, "discount": { "type": "number", "minimum": 0, "description": "New order-level discount total.", "example": 5 }, "tax": { "type": "number", "minimum": 0, "description": "New order-level tax total.", "example": 5 }, "shipping": { "type": "number", "minimum": 0, "description": "New order-level shipping total.", "example": 5 }, "refunded": { "type": "number", "minimum": 0, "description": "New cumulative refunded amount. This is an absolute value, not an increment.", "example": 0 } }, "additionalProperties": false }, "fulfillment_status": { "type": "string", "enum": [ "PENDING", "PARTIALLY_FULFILLED", "FULFILLED", "DELIVERED" ], "example": "FULFILLED" }, "financial_status": { "type": "string", "enum": [ "PENDING", "PAID", "PARTIALLY_REFUNDED", "REFUNDED" ], "example": "PARTIALLY_REFUNDED" }, "fulfilled_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-25T10:00:00.000Z" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-26T14:00:00.000Z" }, "cancelled": { "type": "boolean", "example": false }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time", "example": null }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-24T09:00:01.000Z" }, "last_refunded_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-28T11:00:00.000Z" }, "lines": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "upsert" ], "example": "upsert" }, "line": { "type": "object", "properties": { "external_line_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Stable line identifier within the source order.", "example": "line_123" }, "product_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Product identifier in the source catalog.", "example": "product_123" }, "variant_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Variant identifier in the source catalog.", "example": "variant_123" }, "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Merchant SKU snapshot.", "example": "TSHIRT-BLACK-M" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "description": "Absolute ordered quantity.", "example": 2 }, "unit_price": { "type": "number", "minimum": 0, "description": "Non-negative price per unit in the order currency.", "example": 25 }, "discount": { "type": "number", "minimum": 0, "description": "Discount allocated to this line in the order currency.", "example": 5 }, "refund": { "type": "number", "minimum": 0, "description": "Amount refunded for this line in the order currency.", "example": 0 }, "returned_units": { "type": "integer", "minimum": 0, "description": "Absolute number of returned units.", "example": 0 }, "fulfillment_status": { "type": "string", "enum": [ "PENDING", "PARTIALLY_FULFILLED", "FULFILLED", "DELIVERED" ], "default": "PENDING", "description": "Absolute fulfillment state for this line.", "example": "PENDING" }, "delivered_at": { "type": "string", "format": "date-time", "description": "Delivery timestamp. Required when this line is explicitly delivered.", "example": "2026-07-24T10:00:00.000Z" } }, "required": [ "external_line_id", "quantity", "unit_price" ], "additionalProperties": false } }, "required": [ "operation", "line" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "remove" ], "example": "remove" }, "external_line_id": { "type": "string", "minLength": 1, "maxLength": 255, "example": "line_legacy" } }, "required": [ "operation", "external_line_id" ], "additionalProperties": false } ] } } }, "additionalProperties": false, "example": { "money": { "refunded": 10 }, "financial_status": "PARTIALLY_REFUNDED", "last_refunded_at": "2026-07-28T11:00:00.000Z" } } } } }, "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/OrderResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/IdempotencyConflictResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } }, "delete": { "summary": "Delete order", "description": "Deletes and redacts a specific order while retaining its source identity for audit purposes.", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Cevoid order ID.", "example": "ord_abc123" }, "required": true, "description": "Cevoid order ID.", "name": "id", "in": "path" } ], "responses": { "204": { "description": "No content", "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 } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } }, "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/ErrorResponse" } } } } } } } }, "webhooks": {} }