{"openapi":"3.0.3","info":{"title":"VTO Partner Analytics API","version":"1.0.0","description":"## Overview\n\nThe VTO Partner Analytics API provides resource-based, read-only analytics for authorized VTO experiences.\n\nThe contract is intentionally explicit: traffic, event activity, funnels, effectiveness reports, journeys, breakdowns, and retention are exposed as separate resources so clients can compose the views they need without depending on dashboard-shaped payloads.\n\n## Event Discovery\n\nUse `GET /v1/events` to discover the broader known set of SDK-emitted VTO analytics event keys, what they represent, and the known segmentation keys exposed by this API.\n\nEvent path parameters remain open strings in this API version so existing ingest-backed event keys continue to pass through without a breaking validation change.\n\n## Authentication\n\nAll app-scoped analytics endpoints require the `X-API-Key` header. The event catalog is public.\n\n## Authorization Model\n\nA partner API key can be linked to one or more VTO projects. Every analytics request must include an `app_key` path parameter, and the request is authorized only when that `app_key` belongs to a project linked to the provided API key.\n\n## Reporting Window\n\nDate-based routes require `start_date` and `end_date` in `YYYY-MM-DD` format.\n\nStandard routes support windows up to 93 days.\n\nHigh-cost exact routes are limited to 31 days: `events` (raw event list), `funnel`, `effectiveness`, `journeys`, `breakdowns/browser`, `events/*/segments/*`, and `activity/hourly`.\n\nRetention routes support an optional `as_of_date` parameter for reproducible reporting snapshots."},"servers":[{"url":"{base_url}/vto-partner-analytics","description":"API Server","variables":{"base_url":{"default":"https://api.pulpoar.com","description":"Base URL for the API"}}}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Health","description":"Service health endpoints"},{"name":"Catalog","description":"Public event catalog for documented VTO analytics events"},{"name":"Summary","description":"Headline traffic and engagement metrics for a date range"},{"name":"Time Series","description":"Daily traffic metrics and event activity over time"},{"name":"Funnel","description":"Event-backed VTO funnels with explicit step metrics"},{"name":"Effectiveness","description":"Entity-level VTO effectiveness reports for products and variants"},{"name":"Journeys","description":"Targeted journey drop-off reports for high-value VTO transitions"},{"name":"Breakdowns","description":"Dimension-based analytics with explicit session, user, and event metrics"},{"name":"Events","description":"Event-level analytics and segmentation"},{"name":"Activity","description":"Hourly activity distribution by day of week and hour"},{"name":"Retention","description":"User loyalty and slipping-away retention reports"}],"paths":{"/v1/health":{"get":{"operationId":"get-vto-partner-analytics-health","summary":"Health Check","tags":["Health"],"security":[],"responses":{"200":{"description":"Analytics endpoint health status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/events":{"get":{"operationId":"get-vto-partner-event-catalog","summary":"Get Event Catalog","description":"Returns the broader known VTO analytics event catalog with event descriptions, category groupings, and known segmentation keys emitted by the current SDK analytics mapping.","tags":["Catalog"],"security":[],"responses":{"200":{"description":"VTO event catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCatalogResponse"}}}}}}},"/v1/apps/{app_key}/summary":{"get":{"operationId":"get-vto-partner-summary","summary":"Get Summary","description":"Returns headline traffic and engagement metrics for the requested app and date range.","tags":["Summary"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Summary analytics payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummaryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/timeseries/{metric}":{"get":{"operationId":"get-vto-partner-metric-time-series","summary":"Get Metric Time Series","description":"Returns daily time-series points for an explicit traffic metric.","tags":["Time Series"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/TimeSeriesMetric"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Metric time-series analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricTimeSeriesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/events/{event_key}/timeseries":{"get":{"operationId":"get-vto-partner-event-time-series","summary":"Get Event Time Series","description":"Returns daily event and user counts for a specific event key. Use `GET /v1/events` to discover the broader set of known SDK-emitted VTO analytics event keys, descriptions, and known segmentation keys. Event path parameters remain open strings in this API version so existing ingest-backed event keys continue to pass through unchanged.","tags":["Events","Time Series"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/EventKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Event activity time-series analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventTimeSeriesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/funnel":{"get":{"operationId":"get-vto-partner-funnel","summary":"Get Funnel","description":"Returns the primary and variant-exploration VTO funnels with explicit step labels, event keys, reached users, reached sessions, and conversion rates. Funnel step labels are display-oriented; use `event_keys` and `GET /v1/events` for the canonical event vocabulary. This route is limited to 31 days.","tags":["Funnel"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Funnel analytics payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunnelResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/effectiveness/{dimension}":{"get":{"operationId":"get-vto-partner-effectiveness","summary":"Get Effectiveness Report","description":"Returns entity-level VTO effectiveness metrics for either products or variants, including ready, exploration, add-to-cart, and go-to-product activity. `exploration_events` counts actual rendered try-ons (`onTryOn`); use `GET /v1/events` for documented mappings. This route is limited to 31 days. Rows are ordered by add-to-cart, go-to-product, and try-on counts descending, then entity key ascending. Traverse using `meta.pagination.next_offset` until `has_next` is false, keeping app, dimension, and dates unchanged. `total` counts matching analytics entities, not catalog shades or events. Late events and backfills can change rankings between requests; `generated_at` is not a snapshot identifier. Empty pages may have `data_state: empty` even when total is positive.","tags":["Effectiveness"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/EffectivenessDimension"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/BreakdownLimit"},{"$ref":"#/components/parameters/EffectivenessOffset"}],"responses":{"200":{"description":"Effectiveness analytics payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EffectivenessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/journeys/{report}":{"get":{"operationId":"get-vto-partner-journey-report","summary":"Get Journey Report","description":"Returns a targeted journey drop-off report for a high-value VTO transition, including source totals and downstream drop-off rates. Journey labels are display-oriented; use `event_keys` and `GET /v1/events` for canonical event identifiers. This route is limited to 31 days.","tags":["Journeys"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/JourneyReport"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Journey report analytics payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneyReportResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/breakdowns/{dimension}":{"get":{"operationId":"get-vto-partner-breakdown","summary":"Get Breakdown","description":"Returns explicit session, user, and event totals for a supported breakdown dimension. The `browser` dimension is limited to 31 days; other breakdown dimensions support up to 93 days.","tags":["Breakdowns"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/BreakdownDimension"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/BreakdownLimit"}],"responses":{"200":{"description":"Breakdown analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreakdownResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/events/{event_key}/segments/{segment_key}":{"get":{"operationId":"get-vto-partner-event-segmentation","summary":"Get Event Segmentation","description":"Returns event counts and user counts grouped by a requested event segmentation key. Use `GET /v1/events` to discover the documented segmentation example and the known partner-facing event vocabulary. This route is limited to 31 days.","tags":["Events"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/EventSegmentationEventKey"},{"$ref":"#/components/parameters/EventSegmentationSegmentKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/BreakdownLimit"}],"responses":{"200":{"description":"Event segmentation analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventSegmentationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/activity/hourly":{"get":{"operationId":"get-vto-partner-hourly-activity","summary":"Get Hourly Activity","description":"Returns hourly event and user counts grouped by day of week and hour of day. This route is limited to 31 days.","tags":["Activity"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"}],"responses":{"200":{"description":"Hourly activity analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HourlyActivityResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/retention/loyalty":{"get":{"operationId":"get-vto-partner-user-loyalty","summary":"Get User Loyalty","description":"Returns user loyalty buckets for all-time, last-7-day, and last-30-day windows.","tags":["Retention"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/AsOfDate"}],"responses":{"200":{"description":"User loyalty analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLoyaltyResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/retention/slipping-away":{"get":{"operationId":"get-vto-partner-slipping-away","summary":"Get Slipping Away","description":"Returns slipping-away cohorts using the requested as-of date.","tags":["Retention"],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/AsOfDate"}],"responses":{"200":{"description":"Slipping-away retention analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlippingAwayResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/apps/{app_key}/events":{"get":{"operationId":"get-vto-partner-events","summary":"List Events","description":"Returns raw events newest first, one row per event, with the `partner_analytics_id` the plugin attached (or `null`). Filter by `partner_analytics_id` to read back one partner user's events. Follow `meta.next_cursor` with the same filters until it is `null`. Limited to 31 days inside the raw retention window (about 3 complete months plus the current month); older ranges return 422. Events sent before the id was set are not linked.","tags":["Events"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AppKey"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"name":"event_key","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":128,"example":"onAddToCart"}},{"name":"partner_analytics_id","in":"query","required":false,"description":"Exact match on the id passed via `#partnerAnalyticsId=` or `setPartnerAnalyticsId`.","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,128}$","example":"acct_12345"}},{"name":"cursor","in":"query","required":false,"description":"Opaque value from `meta.next_cursor` of the previous page.","schema":{"type":"string","maxLength":1024}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}}],"responses":{"200":{"description":"A page of raw events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/DataUnavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/ProviderError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key linked to one or more VTO projects."}},"parameters":{"AppKey":{"name":"app_key","in":"path","required":true,"description":"Analytics app key linked to an authorized VTO project.","schema":{"type":"string","minLength":48,"maxLength":48,"pattern":"^[a-f0-9]{48}$","example":"0123456789abcdef0123456789abcdef0123456789abcdef"}},"StartDate":{"name":"start_date","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2026-01-01"}},"EndDate":{"name":"end_date","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2026-01-31"}},"AsOfDate":{"name":"as_of_date","in":"query","required":false,"schema":{"type":"string","format":"date","example":"2026-01-31"}},"TimeSeriesMetric":{"name":"metric","in":"path","required":true,"schema":{"type":"string","enum":["sessions","users","new_users","events","avg_session_duration_seconds"],"example":"sessions"}},"BreakdownDimension":{"name":"dimension","in":"path","required":true,"schema":{"type":"string","enum":["browser","country","device","device_type","language","platform","platform_version","resolution"],"example":"country"}},"EffectivenessDimension":{"name":"dimension","in":"path","required":true,"schema":{"type":"string","enum":["product","variant"],"example":"product"}},"JourneyReport":{"name":"report","in":"path","required":true,"schema":{"type":"string","enum":["add_to_cart_without_go_to_product","ready_without_variant_apply","variant_apply_without_add_to_cart"],"example":"add_to_cart_without_go_to_product"}},"BreakdownLimit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"EffectivenessOffset":{"name":"offset","in":"query","required":false,"description":"Number of ranked entities to skip. An offset at or beyond total returns an empty terminal page.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"default":0}},"EventKey":{"name":"event_key","in":"path","required":true,"description":"Use `GET /v1/events` to discover the broader set of known SDK-emitted VTO analytics event keys, descriptions, and known segmentation keys. Event path parameters remain open strings in this API version so existing ingest-backed event keys continue to pass through unchanged.","schema":{"type":"string","minLength":1,"maxLength":128,"example":"onReady"}},"EventSegmentationEventKey":{"name":"event_key","in":"path","required":true,"description":"Example event key for event segmentation. The example pair here is `onProductSelect` + `productId`. Use `GET /v1/events` to discover the broader set of known SDK-emitted VTO analytics event keys, descriptions, and known segmentation keys. Event path parameters remain open strings in this API version so existing ingest-backed event keys continue to pass through unchanged.","schema":{"type":"string","minLength":1,"maxLength":128,"example":"onProductSelect"}},"EventSegmentationSegmentKey":{"name":"segment_key","in":"path","required":true,"description":"Example segment key matched to the documented event segmentation example event key. Use `GET /v1/events` to discover known segment keys for documented VTO events. For a documented VTO event, `segment_key` must be one of that event's `segmentation_keys`; other values return `400 validation_failed`.","schema":{"type":"string","minLength":1,"maxLength":128,"example":"productId"}}},"responses":{"BadRequest":{"description":"Request validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The API key is valid but does not have access to the requested app key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"DataUnavailable":{"description":"Raw analytics data is unavailable for part of the requested date range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ProviderError":{"description":"Analytics ingest provider failed to fulfill the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Analytics ingest is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"PartnerEvent":{"type":"object","required":["event_id","event_key","created_at","session_id","partner_analytics_id","device_type","os","country_code","properties"],"properties":{"event_id":{"type":"string"},"event_key":{"type":"string","example":"onSkinScoreCalculate"},"created_at":{"type":"string","format":"date-time","example":"2026-10-20T14:03:11.482Z"},"session_id":{"type":"string","nullable":true},"partner_analytics_id":{"type":"string","nullable":true,"example":"acct_12345"},"device_type":{"type":"string","nullable":true,"example":"mobile"},"os":{"type":"string","nullable":true,"example":"iOS"},"country_code":{"type":"string","nullable":true,"example":"BR"},"properties":{"type":"object","additionalProperties":true,"description":"Documented segmentation keys of the event, as listed by `GET /v1/events`."}}},"EventListResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["event_key","partner_analytics_id","limit","next_cursor"],"properties":{"event_key":{"type":"string","nullable":true},"partner_analytics_id":{"type":"string","nullable":true},"limit":{"type":"integer"},"next_cursor":{"type":"string","nullable":true}}}]},"data":{"type":"object","required":["events"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/PartnerEvent"}}}}}},"HealthResponse":{"type":"object","required":["status","timestamp","analytics_backend"],"properties":{"status":{"type":"string","example":"healthy"},"timestamp":{"type":"string","format":"date-time"},"analytics_backend":{"type":"string","enum":["postgres","unconfigured"]}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}},"data_available_from":{"type":"string","format":"date","description":"Earliest date for which the required raw analytics data is available"},"parent_table":{"type":"string","description":"Raw analytics source that limits the requested range","example":"analytics.sessions"},"retry_after":{"type":"integer","minimum":0},"valid_values":{"type":"array","items":{"type":"string"}}}}}},"DataState":{"type":"string","enum":["empty","ready"]},"AnalyticsRange":{"type":"object","required":["start_date","end_date"],"properties":{"start_date":{"type":"string","format":"date","example":"2026-01-01"},"end_date":{"type":"string","format":"date","example":"2026-01-31"}}},"RangeMeta":{"type":"object","required":["app_key","generated_at","data_state","range"],"properties":{"app_key":{"type":"string","example":"0123456789abcdef0123456789abcdef0123456789abcdef"},"generated_at":{"type":"string","format":"date-time"},"data_state":{"$ref":"#/components/schemas/DataState"},"range":{"$ref":"#/components/schemas/AnalyticsRange"}}},"AsOfMeta":{"type":"object","required":["app_key","generated_at","data_state","as_of_date"],"properties":{"app_key":{"type":"string","example":"0123456789abcdef0123456789abcdef0123456789abcdef"},"generated_at":{"type":"string","format":"date-time"},"data_state":{"$ref":"#/components/schemas/DataState"},"as_of_date":{"type":"string","format":"date","example":"2026-01-31"}}},"EventCatalogItem":{"type":"object","required":["event_key","category","description","segmentation_keys"],"properties":{"event_key":{"type":"string","enum":["onReady","onPathChange","onTryNowClick","onGdprApprove","onGdprLinkClick","onUploadPhoto","onModelSelect","onTakePhoto","onUsePhoto","onTakePhotoAgain","onCurtainToggle","onCurtainSlideStart","onCurtainSlideEnd","onOpacitySlideStart","onOpacitySlideEnd","onZoom","onCameraMirror","onCameraSwitch","onGoBack","onExperienceSelect","onLookSelect","onBrandSelect","onCategorySelect","onProductSelect","onVariantSelect","onTryOn","onAppliedVariantsChange","onAddToCart","onGoToProduct","onContinue"]},"category":{"type":"string"},"description":{"type":"string"},"segmentation_keys":{"type":"array","items":{"type":"string"}}}},"EventCategoryItem":{"type":"object","required":["category_key","event_keys"],"properties":{"category_key":{"type":"string"},"event_keys":{"type":"array","items":{"type":"string","enum":["onReady","onPathChange","onTryNowClick","onGdprApprove","onGdprLinkClick","onUploadPhoto","onModelSelect","onTakePhoto","onUsePhoto","onTakePhotoAgain","onCurtainToggle","onCurtainSlideStart","onCurtainSlideEnd","onOpacitySlideStart","onOpacitySlideEnd","onZoom","onCameraMirror","onCameraSwitch","onGoBack","onExperienceSelect","onLookSelect","onBrandSelect","onCategorySelect","onProductSelect","onVariantSelect","onTryOn","onAppliedVariantsChange","onAddToCart","onGoToProduct","onContinue"]}}}},"SummaryData":{"type":"object","required":["traffic","engagement"],"properties":{"traffic":{"type":"object","required":["sessions","users","new_users"],"properties":{"sessions":{"type":"integer","minimum":0},"users":{"type":"integer","minimum":0},"new_users":{"type":"integer","minimum":0}}},"engagement":{"type":"object","required":["avg_session_duration_seconds"],"properties":{"avg_session_duration_seconds":{"type":"number","minimum":0}}}}},"MetricPoint":{"type":"object","required":["date","value"],"properties":{"date":{"type":"string","format":"date"},"value":{"type":"number","minimum":0}}},"EventMetricPoint":{"type":"object","required":["date","event_count","user_count"],"properties":{"date":{"type":"string","format":"date"},"event_count":{"type":"integer","minimum":0},"user_count":{"type":"integer","minimum":0}}},"BreakdownItem":{"type":"object","required":["key","sessions","users","events"],"properties":{"key":{"type":"string"},"sessions":{"type":"integer","minimum":0},"users":{"type":"integer","minimum":0},"events":{"type":"integer","minimum":0}}},"EventSegmentationItem":{"type":"object","required":["value","event_count","user_count"],"properties":{"value":{"type":"string"},"event_count":{"type":"integer","minimum":0},"user_count":{"type":"integer","minimum":0}}},"HourlyActivityPoint":{"type":"object","required":["day_of_week","hour_of_day","event_count","user_count"],"properties":{"day_of_week":{"type":"integer","minimum":0,"maximum":6},"hour_of_day":{"type":"integer","minimum":0,"maximum":23},"event_count":{"type":"integer","minimum":0},"user_count":{"type":"integer","minimum":0}}},"UserLoyaltyBucket":{"type":"object","required":["bucket","user_count","index"],"properties":{"bucket":{"type":"string"},"user_count":{"type":"integer","minimum":0},"index":{"type":"integer","minimum":0}}},"SlippingAwayPoint":{"type":"object","required":["period_days","user_count","percentage"],"properties":{"period_days":{"type":"integer","minimum":0},"user_count":{"type":"integer","minimum":0},"percentage":{"type":"number","minimum":0}}},"FunnelStep":{"type":"object","required":["step_key","step_number","label","event_keys","reached_sessions","reached_users","session_conversion_rate","session_drop_off_rate","user_conversion_rate","user_drop_off_rate"],"properties":{"step_key":{"type":"string"},"step_number":{"type":"integer","minimum":1},"label":{"type":"string","description":"Display label from analytics-ingest. Use `event_keys` for canonical event identifiers."},"event_keys":{"type":"array","description":"Canonical event keys for this funnel step. Known keys are documented by `GET /v1/events`.","items":{"type":"string"}},"reached_sessions":{"type":"integer","minimum":0},"reached_users":{"type":"integer","minimum":0},"session_conversion_rate":{"type":"number","minimum":0},"session_drop_off_rate":{"type":"number","minimum":0},"user_conversion_rate":{"type":"number","minimum":0},"user_drop_off_rate":{"type":"number","minimum":0}}},"FunnelGroup":{"type":"object","required":["steps"],"properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/FunnelStep"}}}},"EffectivenessItem":{"type":"object","required":["entity_key","ready_events","exploration_events","add_to_cart_events","go_to_product_events"],"properties":{"entity_key":{"type":"string"},"ready_events":{"type":"integer","minimum":0,"description":"Always 0. `onReady` is a session-level lifecycle event with no product/variant segmentation, so it cannot attribute to an entity in this per-product/per-variant breakdown. Kept for response-shape stability; use `GET /v1/events` for `onReady` totals."},"exploration_events":{"type":"integer","minimum":0,"description":"Count of actual rendered try-ons, keyed by `onTryOn`."},"add_to_cart_events":{"type":"integer","minimum":0,"description":"Count of cart-add activity, typically keyed by `onAddToCart`."},"go_to_product_events":{"type":"integer","minimum":0,"description":"Count of product-page visits from VTO, typically keyed by `onGoToProduct`."},"unique_users":{"type":"integer","minimum":0,"description":"Exact distinct users when the requested range is fully covered by live raw data. Omitted for historical ranges served from additive rollups."}}},"JourneyStep":{"type":"object","required":["label","event_keys"],"properties":{"label":{"type":"string","description":"Display label from analytics-ingest. Use `event_keys` for canonical event identifiers."},"event_keys":{"type":"array","description":"Canonical event keys for this journey step. Known keys are documented by `GET /v1/events`.","items":{"type":"string"}}}},"JourneyReportData":{"type":"object","required":["report","source_step","downstream_step","totals","rates"],"properties":{"report":{"type":"string","enum":["add_to_cart_without_go_to_product","ready_without_variant_apply","variant_apply_without_add_to_cart"]},"source_step":{"$ref":"#/components/schemas/JourneyStep"},"downstream_step":{"$ref":"#/components/schemas/JourneyStep"},"totals":{"type":"object","required":["source_sessions","source_users","drop_off_sessions","drop_off_users"],"properties":{"source_sessions":{"type":"integer","minimum":0},"source_users":{"type":"integer","minimum":0},"drop_off_sessions":{"type":"integer","minimum":0},"drop_off_users":{"type":"integer","minimum":0}}},"rates":{"type":"object","required":["session_drop_off_rate","user_drop_off_rate"],"properties":{"session_drop_off_rate":{"type":"number","minimum":0},"user_drop_off_rate":{"type":"number","minimum":0}}}}},"EventCatalogResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"type":"object","required":["generated_at","total_events"],"properties":{"generated_at":{"type":"string","format":"date-time"},"total_events":{"type":"integer","minimum":0}}},"data":{"type":"object","required":["total_events","events","categories"],"properties":{"total_events":{"type":"integer","minimum":0},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventCatalogItem"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/EventCategoryItem"}}}}}},"SummaryResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/RangeMeta"},"data":{"$ref":"#/components/schemas/SummaryData"}}},"MetricTimeSeriesResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["metric"],"properties":{"metric":{"type":"string","enum":["sessions","users","new_users","events","avg_session_duration_seconds"]}}}]},"data":{"type":"object","required":["points"],"properties":{"points":{"type":"array","items":{"$ref":"#/components/schemas/MetricPoint"}}}}}},"EventTimeSeriesResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["event_key"],"properties":{"event_key":{"type":"string"}}}]},"data":{"type":"object","required":["points"],"properties":{"points":{"type":"array","items":{"$ref":"#/components/schemas/EventMetricPoint"}}}}}},"FunnelResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/RangeMeta"},"data":{"type":"object","required":["primary_funnel","variant_exploration_funnel"],"properties":{"primary_funnel":{"$ref":"#/components/schemas/FunnelGroup"},"variant_exploration_funnel":{"$ref":"#/components/schemas/FunnelGroup"}}}}},"EffectivenessPagination":{"type":"object","required":["total","limit","offset","has_next","next_offset"],"properties":{"total":{"type":"integer","minimum":0,"description":"Distinct matching analytics entities before pagination."},"limit":{"type":"integer","minimum":1,"maximum":100},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"has_next":{"type":"boolean"},"next_offset":{"type":"integer","minimum":0,"nullable":true,"description":"Next offset, or null on terminal pages."}}},"EffectivenessResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["dimension","limit","pagination"],"properties":{"pagination":{"$ref":"#/components/schemas/EffectivenessPagination"},"dimension":{"type":"string","enum":["product","variant"]},"limit":{"type":"integer","minimum":1,"maximum":100}}}]},"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EffectivenessItem"}}}}}},"JourneyReportResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["report"],"properties":{"report":{"type":"string","enum":["add_to_cart_without_go_to_product","ready_without_variant_apply","variant_apply_without_add_to_cart"]}}}]},"data":{"$ref":"#/components/schemas/JourneyReportData"}}},"BreakdownResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["dimension","limit"],"properties":{"dimension":{"type":"string","enum":["browser","country","device","device_type","language","platform","platform_version","resolution"]},"limit":{"type":"integer","minimum":1,"maximum":100}}}]},"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownItem"}}}}}},"EventSegmentationResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"allOf":[{"$ref":"#/components/schemas/RangeMeta"},{"type":"object","required":["event_key","segment_key","limit"],"properties":{"event_key":{"type":"string"},"segment_key":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":100}}}]},"data":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EventSegmentationItem"}}}}}},"HourlyActivityResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/RangeMeta"},"data":{"type":"object","required":["points"],"properties":{"points":{"type":"array","items":{"$ref":"#/components/schemas/HourlyActivityPoint"}}}}}},"UserLoyaltyResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/AsOfMeta"},"data":{"type":"object","required":["all_time","last_7_days","last_30_days"],"properties":{"all_time":{"type":"array","items":{"$ref":"#/components/schemas/UserLoyaltyBucket"}},"last_7_days":{"type":"array","items":{"$ref":"#/components/schemas/UserLoyaltyBucket"}},"last_30_days":{"type":"array","items":{"$ref":"#/components/schemas/UserLoyaltyBucket"}}}}}},"SlippingAwayResponse":{"type":"object","required":["meta","data"],"properties":{"meta":{"$ref":"#/components/schemas/AsOfMeta"},"data":{"type":"object","required":["points"],"properties":{"points":{"type":"array","items":{"$ref":"#/components/schemas/SlippingAwayPoint"}}}}}}}}}