--- title: "A creator's top videos with sample-review intelligence" method: POST path: "/sample-review/creator-videos" tags: ["Sample Review Intelligence (internal)"] --- # A creator's top videos with sample-review intelligence `POST /sample-review/creator-videos` ## Request - Base URL: `https://api.reacherapp.com/public/v1` - URL: `https://api.reacherapp.com/public/v1/sample-review/creator-videos` - Auth: API key in header `x-api-key` and API key in header `x-shop-id` For deciding a creator's sample request: the creator's top videos over a recent window, each with the AI creative analysis, the internal metrics (GMV, views, engagement), plus a creator aggregate (lifetime GMV, video/live counts, followers, current status, samples already received, tags). Videos are ranked by `rank_by` (`gmv` or `views`) over the last `window_days` and capped at `limit`. A video the pipeline has not analyzed yet still appears with its metrics and `uvi_analyzed: false`. Set `include_full_features=true` to also receive the full scored-feature block per video. Recommended fields to weigh (also returned as `field_guide`): - `hook_summary` — How the video opens — the first seconds decide whether viewers stay, so a weak hook predicts weak reach. - `transcript` — What the creator actually says — check the product claims are accurate and the messaging fits the brand. - `on_screen_text` — On-screen captions/text (OCR) — catches claims, prices, or disclaimers shown but not spoken. - `structure_outline` — The beats of the video (hook, demo, CTA) — a clear structure signals a creator who can sell, not just post. - `detected_products` — Products the analyzer saw on screen — confirms the creator actually featured the product, i.e. product fit. - `vision_tags` — Visual tags for setting, style, and content type — a fast read on production quality and brand-safety. - `features.hook_present_first_3s` — Whether a real hook lands in the first three seconds — the single strongest retention signal. - `features.has_product_demo` — Whether the product is actually demonstrated — demos convert far better than mentions. - `features.solution_shown` — Whether the video shows the product solving a problem — the core of a persuasive sample video. - `features.has_voiceover` — Whether the creator narrates — voiceover content tends to feel more authentic and engaged. - `features.video_pace` — Editing pace — matches (or clashes with) the brand's desired energy and the platform's norms. - `features.content_summary` — A one-line summary of the video — the quickest gist before opening the full analysis. - `metrics.views / metrics.video_gmv` — Actual reach and sales this creator's recent content drove — the outcome the sample is betting on. - `creator.sample_received_num / creator.curr_status` — How many samples this creator already got and where they stand — flags repeat requesters and stalled relationships. ## Request body - SampleReviewCreatorVideosRequest: POST /sample-review/creator-videos body. - `shop_id` integer, nullable: Optional. The shop is taken from the request's shop (x-shop-id). If given, shop_id must equal that shop or the call is rejected; omit it to use the shop already set on the request. - `creator_id` string, required: Creator id, scoped to the shop. - `rank_by` 'gmv' | 'views': Rank the creator's videos by lifetime GMV or lifetime views. - `window_days` integer: Only videos posted within this many days back are considered. - `limit` integer: Number of top videos to return (1-50). - `include_full_features` boolean: When true, also return the full scored-feature block per video (`uvi_full_features`) in addition to the curated recommended set. ## Response `200` Successful Response - SampleReviewCreatorVideosResponse: POST /sample-review/creator-videos. - `shop_id` integer, required - `currency_code` string, required: ISO currency code for the shop's region (all GMV is in it). - `rank_by` 'gmv' | 'views', required - `window_days` integer, required - `creator` SampleReviewCreatorAggregate, required: Creator-level aggregate for the header of the creator-videos response. - `creator_id` string, required - `creator_name` string, nullable - `gmv` number, nullable: Creator lifetime GMV for this shop, in the shop's currency. - `video_num` integer, nullable: Number of videos. - `live_num` integer, nullable: Number of lives. - `follower_num` integer, nullable: Creator follower count. - `curr_status` string, nullable: Current relationship/sample status for this creator. - `sample_received_num` integer, nullable: How many samples this creator has already received. - `tags` string[]: Tags applied to this creator. - `crm_found` boolean, required: False when the creator has no CRM record yet — the aggregate fields are then null/empty and only the identity is populated. - `videos` SampleReviewVideo[], required - `video_id` string, required - `creator_id` string, required - `creator_name` string, nullable - `posted_date` string, nullable - `is_shoppable` boolean, nullable: Whether the video has a shoppable (affiliate) leg. Null on legacy videos where the source is unknown. - `metrics` SampleReviewVideoMetrics, required: Per-video internal metrics: GMV, views, and engagement counts. - `video_gmv` number, nullable: Total GMV attributed to this video, in the shop's currency. - `shoppable_gmv` number, nullable: GMV from the shoppable (affiliate) leg. Null on legacy videos that predate per-source GMV splitting. - `official_gmv` number, nullable: GMV from the Seller-Center (official) leg. Null on legacy videos that predate per-source GMV splitting. - `views` integer, nullable: Lifetime view count. - `units_sold` integer, nullable: Lifetime units sold. - `like_count` integer, nullable: Lifetime like count. - `comment_count` integer, nullable: Lifetime comment count. - `share_count` integer, nullable: Lifetime share count. - `uvi_analyzed` boolean, required: False when the shop owns this video but the UVI pipeline has not analyzed it yet — `uvi_recommended` and `uvi_full_features` are then null. Coverage is partial and grows over time. - `analyzed_at` string, nullable: When the UVI analysis ran. Null when unanalyzed. - `analysis_version` integer, nullable: Analyzer version that produced the analysis. - `uvi_recommended` SampleReviewUviRecommended: The curated 'recommended for sample review' UVI fields. Present only when the video has been analyzed. Individual members are null when the analyzer had no value for them (e.g. a thumbnail-only analysis carries no transcript); a null is 'not available', never a scored absence. - `hook_summary` string, nullable: One-line description of how the video opens. - `transcript` string, nullable: Spoken-audio transcript of the video. - `transcript_source` string, nullable: Where the transcript came from: the analyzer, or the shop's transcript store used as a fallback. - `on_screen_text` string, nullable: On-screen text (OCR), all segments joined. Null when there is none. - `structure_outline` string[], nullable: Ordered beats of the video (e.g. Hook, Demo, CTA). - `detected_products` unknown - `vision_tags` unknown - `features` object, nullable: Curated stable scored features: hook in the first three seconds, product demo present, solution shown, voiceover present, pace, and a content summary. Members the analyzer could not score are omitted. - `uvi_full_features` object, nullable: Only present with `include_full_features=true` on an analyzed video: the analyzer's full scored-feature block. Unstable across analyzer versions — pin the members you read. - `field_guide` SampleReviewFieldGuideItem[], required: Curated recommended fields and why each matters for sample review. - `field` string, required - `why` string, required ## Other responses - `422`: Validation Error ## Changes > 76 revisions in range; 1 not diffed. - **2026-09-19** `291230805105`: 1 info - endpoint added [Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/sample-review/creator-videos/post.md) --- [API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)