hooklayer

{'type': 'object', 'required': ['handle'], 'properties': {'since': {'type': 'string', 'description': 'Optional ISO date (e.g. "2026-04-01"). Filter the candidate video pool to those posted on/after this date. Useful when the user asks "show me what they\'ve done THIS month" — the route returns honest empty + warning when the filter matches 0, no credits charged. Use either `since` or `window`, not both.'}, 'handle': {'type': 'string', 'description': 'Creator handle (with or without @ prefix) or YouTube channel ID. Examples: "@mrbeast", "mrbeast", "UCX6OQ3DkcsbYNE6H8uQQuVA".'}, 'window': {'enum': ['24h', '7d', '30d', '90d', '6m', '12m', 'this-month'], 'type': 'string', 'description': 'Recency sugar — same effect as `since` but takes a friendlier bucket. Maps to a since-cutoff at request time. Use either `since` or `window`, not both.'}, 'platform': {'enum': ['tiktok', 'youtube', 'instagram'], 'type': 'string', 'description': 'Platform to analyze. "tiktok" (default) returns full pipeline with transcripts. "youtube" analyzes recent Shorts via YouTube Data API + Innertube caption extraction — videos with captions disabled or geoblocked resolve to transcript: null. "instagram" (shipped 2026-07-06) fetches the creator\'s reels via ScrapeCreators Instagram API + best-effort reel transcripts on the top 5 — Instagram data lacks lifetime totalLikes so that field defaults to 0.'}, 'recent_only': {'type': 'boolean', 'description': 'When true, hard-cap the candidate pool to videos posted in the last 90 days. Stricter than `window=90d` because it never falls through to archival data on a thin recent corpus.'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'profile': {'type': 'object', 'description': 'Creator profile (handle, bio, followers, following, total_likes, total_videos)'}, 'from_payg': {'type': 'boolean', 'description': 'Whether credits came from pay-as-you-go balance'}, 'steal_map': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Actionable elements to replicate from this creator'}, 'viral_dna': {'type': 'object', 'properties': {'viral_dna_score': {'type': 'number'}, 'audience_fatigue': {'type': 'number'}, 'consistency_score': {'type': 'number'}, 'originality_score': {'type': 'number'}, 'replicability_score': {'type': 'number'}}, 'description': 'Five viral DNA scores (0-100 each)'}, 'content_gaps': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Untapped content opportunities the creator is missing'}, 'recent_videos': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Top recent videos with view counts, transcripts, and engagement'}, 'headline_insight': {'type': 'object', 'properties': {'wow': {'type': 'string', 'description': "The single most material finding in the account's data: the dimension (video length, hook type, format, posting cadence, or topic) with the largest quantified performance gap, stated with two real numbers from the creator's videos. Not a restated score."}, 'so_what': {'type': 'string', 'description': 'The one concrete change the wow gap implies, stated in a single line.'}, 'confidence': {'enum': ['high', 'medium', 'low'], 'type': 'string', 'description': 'Confidence in the headline insight; lower on thin (<8 videos) or stale (>30 days) samples.'}}, 'description': 'The largest quantified performance gap for this creator, plus its implication. Presentation-neutral data — the caller decides whether and how to surface it.'}, 'pattern_analysis': {'type': 'object', 'description': 'Content pattern breakdown (posting cadence, topic clusters)'}, 'credits_remaining': {'type': 'number', 'description': 'Credits remaining after this call'}, 'from_subscription': {'type': 'boolean', 'description': 'Whether credits came from subscription'}, 'recommended_chain': {'type': 'array', 'items': {'type': 'object', 'properties': {'cost': {'type': 'number', 'description': 'Credit cost for this tool call'}, 'tool': {'type': 'string', 'description': 'Exact tool name to call'}, 'params': {'type': 'object', 'description': 'Pre-filled parameters for the tool'}, 'reason': {'type': 'string', 'description': 'Why this step is recommended'}, 'confidence': {'enum': ['high', 'medium', 'low'], 'type': 'string', 'description': 'Signal-derived confidence that this step will produce useful results'}, 'action_class': {'enum': ['research', 'synthesize', 'draft', 'publish', 'account'], 'type': 'string', 'description': 'Authority taxonomy: research (read-only data gathering, lowest authority), synthesize (generate content in-memory, low), draft (save to workspace, medium), publish (post to external platforms, HIGH), account (modify account/billing, HIGHEST). All Hooklayer v1 tools are research or synthesize.'}, 'side_effects': {'type': 'string', 'description': 'Always "none" — all tools are read-only'}, 'expected_output': {'type': 'string', 'description': 'One-line summary of what this tool returns'}}}, 'description': 'Suggested next tool calls with pre-filled parameters — advisory only, agent decides whether to execute'}, 'format_fingerprint': {'type': 'object', 'description': 'Dominant content format patterns (durations, styles, edit types)'}}}

{'type': 'object', 'required': ['product', 'product_category', 'niche'], 'properties': {'niche': {'enum': ['Beauty & Skincare', 'Fitness & Health', 'Food & Cooking', 'Fashion & Style', 'Tech & Gadgets', 'Finance & Business', 'Education & Learning', 'Travel & Adventure', 'Comedy & Entertainment', 'Gaming', 'Lifestyle & Wellness', 'Parenting & Family', 'DIY & Crafts', 'Music & Dance', 'Pets & Animals', 'Sports', 'Motivation & Self-Help', 'SaaS & AI Tools'], 'type': 'string', 'description': 'One of the 17 supported niches. Loose names like "beauty" or "fitness" are auto-mapped.'}, 'region': {'type': 'string', 'description': 'Optional 2-letter ISO country code (US, GB, CA, etc.). Threads to niche + trend upstreams.'}, 'product': {'type': 'string', 'description': 'What the brand sent (name + one line, e.g. "Athletic Greens AG1 travel packs — 30-count individual sachets for travel")'}, 'platform': {'enum': ['tiktok', 'instagram'], 'type': 'string', 'description': 'Target platform. Both TikTok and Instagram Reels supported (shipped 2026-07-06). When set to "instagram", the product-corpus lookup runs against Instagram Reels via ScrapeCreators, and the creator context (if creator_handle passed) fetches Instagram reels. Default: tiktok.'}, 'creator_handle': {'type': 'string', 'description': 'Optional creator handle (with or without @). If provided, the blueprint hook and script match THEIR voice patterns from recent videos. Highly recommended — a blueprint without creator context is generic.'}, 'deadline_hours': {'type': 'integer', 'maximum': 168, 'minimum': 1, 'description': 'How many hours until the video must be posted. Default 48. Affects trend-still-alive scoring — a 24-hour deadline needs a trend on the up-slope, not one that just plateaued.'}, 'product_category': {'type': 'string', 'description': 'Umbrella category (e.g. "greens powder", "sunscreen", "protein bar")'}}}

{'type': 'object', 'properties': {'as_of': {'type': 'string'}, 'stats': {'type': 'object', 'properties': {'rising_trends': {'type': 'integer'}, 'product_videos': {'type': 'integer'}, 'niche_templates': {'type': 'integer'}, 'creator_context_available': {'type': 'boolean'}}}, 'applied': {'type': 'object', 'description': 'Echo of parameters resolved after canonicalization'}, 'quality': {'type': 'object', 'properties': {'level': {'enum': ['full', 'partial', 'degraded'], 'type': 'string'}, 'reason': {'type': 'string'}}}, 'success': {'type': 'boolean'}, 'blueprint': {'type': 'object', 'properties': {'hook': {'type': 'object', 'properties': {'text': {'type': 'string'}, 'pattern': {'type': 'string'}, 'why_this_hook': {'type': 'string'}, 'trend_still_alive': {'enum': ['up-slope', 'plateau', 'fading', 'unknown'], 'type': 'string'}}}, 'script': {'type': 'object'}, 'verdict': {'enum': ['GO', 'NEEDS_MORE_DATA', 'NO_GO'], 'type': 'string'}, 'hashtags': {'type': 'array', 'items': {'type': 'string'}}, 'risk_flags': {'type': 'array', 'items': {'type': 'string'}}, 'shoot_notes': {'type': 'object'}, 'verdict_reason': {'type': 'string'}, 'why_this_will_land': {'type': 'array', 'items': {'type': 'string'}}, 'manager_talking_points': {'type': 'array', 'items': {'type': 'string'}}}}, 'provenance': {'type': 'object'}, 'credits_remaining': {'type': 'object', 'properties': {'payg': {'type': 'number'}, 'total': {'type': 'number'}, 'subscription': {'type': 'number'}}}}}

{'type': 'object', 'required': ['niche'], 'properties': {'niche': {'enum': ['Beauty & Skincare', 'Fitness & Health', 'Food & Cooking', 'Fashion & Style', 'Tech & Gadgets', 'Finance & Business', 'Education & Learning', 'Travel & Adventure', 'Comedy & Entertainment', 'Gaming', 'Lifestyle & Wellness', 'Parenting & Family', 'DIY & Crafts', 'Music & Dance', 'Pets & Animals', 'Sports', 'Motivation & Self-Help', 'SaaS & AI Tools'], 'type': 'string', 'description': 'One of the 17 supported niches. Loose names like "travel" or "fitness" are accepted but pass the canonical form when possible.'}, 'query': {'type': 'string', 'description': 'Optional angle narrowing within the niche. E.g. niche="Fitness & Health" + query="postpartum strength" returns only postpartum-strength templates, not generic gym. Templates are scored by query-token match against title+description+hashtags; zero-match templates are dropped. Leave empty for niche-wide top templates.'}, 'region': {'type': 'string', 'description': 'Optional 2-letter ISO country code (US, GB, BR, JP, IN, PH, etc.). Threads to YouTube Search regionCode + TikTok niche query. Reddit niche signals are global and ignore this param. Pass when the user wants templates that resonate with a specific local audience.'}, 'window': {'enum': ['24h', '7d', '30d', '90d', 'this-month'], 'type': 'string', 'description': 'Recency filter. Drops example videos older than the window. Note: TikTok hashtag-corpus rows often lack timestamps and are excluded when window is set — surfaces as a quality warning so callers can decide whether to broaden.'}, 'platform': {'enum': ['tiktok', 'instagram'], 'type': 'string', 'description': 'Platform to source templates from. "tiktok" (default) uses the full niche-aggregator (YouTube + Reddit + TikTok hashtags). "instagram" (2026-07-06) is keyword-search-only — the Instagram niche-aggregator isn\'t plumbed yet, so `query` becomes REQUIRED on IG. Output rubric_version signals which path ran: find_viral_template.v1 (main), .v2-keyword-fallback (TikTok fallback), .v3-instagram-keyword-only (IG-only path).'}, 'min_views': {'type': 'integer', 'minimum': 0, 'description': 'Optional filter — only return examples above this view count'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'niche': {'type': 'string', 'description': 'The niche searched'}, 'from_payg': {'type': 'boolean', 'description': 'Whether credits came from pay-as-you-go balance'}, 'templates': {'type': 'array', 'items': {'type': 'object', 'properties': {'url': {'type': 'string'}, 'format': {'type': 'string'}, 'avg_views': {'type': 'number'}, 'hook_pattern': {'type': 'string'}}}, 'description': 'Ranked viral templates with hook patterns and example URLs'}, 'credits_remaining': {'type': 'number', 'description': 'Credits remaining after this call'}, 'from_subscription': {'type': 'boolean', 'description': 'Whether credits came from subscription'}}}

{'type': 'object', 'properties': {'handle': {'type': 'string', 'description': 'Creator handle (with or without @). Required if watch_id is not provided.'}, 'platform': {'enum': ['tiktok', 'instagram', 'youtube'], 'type': 'string', 'description': 'Platform the tracked creator publishes on. Required if watch_id is not provided.'}, 'watch_id': {'type': 'string', 'description': 'Watch identifier returned by watch_account or list_watches. Preferred over (platform, handle) when you have it — the ownership check is exact.'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'status': {'enum': ['changes_found', 'no_meaningful_change', 'baseline_refreshed', 'not_tracked', 'no_baseline'], 'type': 'string', 'description': 'changes_found = meaningful shifts detected; no_meaningful_change = fresh analysis ran, nothing shifted enough to matter; baseline_refreshed = prior snapshot used an incompatible schema, new baseline saved; not_tracked = no active CreatorWatch for that creator; no_baseline = watch exists but has no snapshots yet.'}, 'changes': {'type': 'array', 'items': {'type': 'object', 'properties': {'after': {}, 'delta': {'type': 'number'}, 'before': {}, 'evidence': {'type': 'string'}, 'delta_pct': {'type': 'number'}, 'importance': {'enum': ['high', 'medium', 'low'], 'type': 'string'}, 'change_type': {'enum': ['viral_dna_shift', 'engagement_shift', 'follower_shift', 'format_shift', 'hook_pattern_shift', 'topic_shift', 'outlier_emergence'], 'type': 'string'}, 'why_it_matters': {'type': 'string'}, 'recommended_action': {'type': 'object', 'properties': {'tool': {'type': 'string'}, 'params': {'type': 'object'}, 'reason': {'type': 'string'}}}}}}, 'creator': {'type': 'string'}, 'platform': {'enum': ['tiktok', 'instagram', 'youtube'], 'type': 'string'}, 'top_action': {'type': 'object', 'properties': {'tool': {'type': 'string'}, 'params': {'type': 'object'}, 'reason': {'type': 'string'}}, 'description': 'Single most useful next tool call given the detected changes. null when nothing meaningful shifted.'}, 'snapshot_count': {'type': 'number', 'description': 'Total snapshots saved for this watch after this call.'}, 'credits_charged': {'type': 'number'}, 'high_importance': {'type': 'number'}, 'medium_importance': {'type': 'number'}, 'meaningful_changes': {'type': 'number', 'description': 'Count of high + medium importance changes.'}, 'current_snapshot_at': {'type': 'string'}, 'previous_snapshot_at': {'type': 'string'}}}

{'type': 'object', 'properties': {}, 'additionalProperties': False}

{'type': 'object', 'properties': {'total': {'type': 'number'}, 'watches': {'type': 'array', 'items': {'type': 'object', 'properties': {'handle': {'type': 'string'}, 'platform': {'enum': ['tiktok', 'instagram', 'youtube'], 'type': 'string'}, 'watch_id': {'type': 'string'}, 'is_active': {'type': 'boolean'}, 'created_at': {'type': 'string'}, 'updated_at': {'type': 'string'}, 'snapshot_count': {'type': 'number'}, 'last_snapshot_at': {'type': 'string', 'description': 'null when no snapshot exists (rare — only if a persistence race happened)'}}}}}}

{'type': 'object', 'required': ['draft', 'reference_samples'], 'properties': {'draft': {'type': 'string', 'description': 'The text to rewrite'}, 'reference_samples': {'type': 'array', 'items': {'type': 'string'}, 'minItems': 3, 'description': 'At least 3 reference samples — TikTok/YouTube/Instagram URLs or raw text'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'from_payg': {'type': 'boolean', 'description': 'Whether credits came from pay-as-you-go balance'}, 'voice_profile': {'type': 'object', 'properties': {'humor': {'type': 'string'}, 'energy': {'type': 'string'}, 'signatures': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Signature phrases and moves'}, 'vocabulary': {'type': 'string'}}, 'description': 'Extracted voice DNA profile'}, 'rewritten_draft': {'type': 'string', 'description': 'The input draft rewritten in the matched voice'}, 'credits_remaining': {'type': 'number', 'description': 'Credits remaining after this call'}, 'from_subscription': {'type': 'boolean', 'description': 'Whether credits came from subscription'}, 'prompt_instructions': {'type': 'string', 'description': 'Reusable prompt to replicate this voice'}}}

{'type': 'object', 'required': ['script'], 'properties': {'niche': {'type': 'string', 'description': 'Niche context'}, 'script': {'type': 'string', 'description': 'The draft script to predict on (or a video URL — auto-extracts transcript)'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'blueprint': {'type': 'object', 'description': 'Retention diagnosis with weak seconds identified'}, 'from_payg': {'type': 'boolean', 'description': 'Whether credits came from pay-as-you-go balance'}, 'viral_dna': {'type': 'object', 'description': 'Hook type, structure, emotional triggers breakdown'}, 'share_reason': {'type': 'string', 'description': 'Why viewers would share this content'}, 'target_emotion': {'type': 'string', 'description': 'Primary emotion the content targets'}, 'virality_score': {'type': 'number', 'description': 'Overall virality prediction (0-100)'}, 'credits_remaining': {'type': 'number', 'description': 'Credits remaining after this call'}, 'from_subscription': {'type': 'boolean', 'description': 'Whether credits came from subscription'}}}

{'type': 'object', 'required': ['text', 'platform'], 'properties': {'text': {'type': 'string', 'description': 'The hook to score (3-200 chars typical)'}, 'niche': {'type': 'string', 'description': 'Optional niche context (e.g. "Beauty & Skincare", "Finance & Business")'}, 'platform': {'enum': ['tiktok', 'reels', 'shorts'], 'type': 'string', 'description': 'Target platform — affects pattern matching'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'why': {'type': 'string', 'description': 'One-sentence verdict explaining the score'}, 'score': {'type': 'number', 'description': 'Hook quality score (0-100)'}, 'rewrites': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Three rewritten versions at higher quality'}, 'breakdown': {'type': 'object', 'properties': {'urgency': {'type': 'number'}, 'curiosity': {'type': 'number'}, 'specificity': {'type': 'number'}, 'emotional_pull': {'type': 'number'}, 'pattern_alignment': {'type': 'number'}}, 'description': 'Sub-scores (0-100) for five quality dimensions'}, 'from_payg': {'type': 'boolean', 'description': 'Whether credits came from pay-as-you-go balance'}, 'strengths': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What the hook does well'}, 'percentile': {'type': 'number', 'description': 'Percentile rank vs all scored hooks'}, 'weaknesses': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What could be improved'}, 'pattern_match': {'type': 'string', 'description': 'Matched viral pattern name'}, 'credits_remaining': {'type': 'number', 'description': 'Credits remaining after this call'}, 'from_subscription': {'type': 'boolean', 'description': 'Whether credits came from subscription'}}}

{'type': 'object', 'required': ['query'], 'properties': {'limit': {'type': 'integer', 'maximum': 20, 'minimum': 1, 'description': 'Max videos to return after filtering. Default 12, max 20.'}, 'niche': {'type': 'string', 'description': 'Optional — only return videos whose description contains niche-related tokens. Loose niche strings work ("fitness", "Beauty & Skincare").'}, 'query': {'type': 'string', 'description': 'Free-text search term. Examples: "morning routine", "iphone case", "passive income".'}, 'region': {'type': 'string', 'description': 'ISO country code (US, GB, BR, PH, JP, etc.). Note: corpus coverage varies by region — small regions may return zero results and a degraded quality flag.'}, 'window': {'enum': ['24h', '7d', '30d', 'this-month'], 'type': 'string', 'description': 'Recency filter. Maps to the closest ScrapeCreators date bucket AND applies a client-side cutoff for defense-in-depth.'}, 'platform': {'enum': ['tiktok', 'instagram'], 'type': 'string', 'description': 'Which platform to search. "tiktok" (default) hits ScrapeCreators TikTok keyword search. "instagram" (2026-07-06) hits Instagram Reels search — note IG upstream ignores region/date_posted params, so region enforcement is client-side only (region_verified_count in the response tells you how many results verifiably matched).'}, 'min_views': {'type': 'integer', 'minimum': 0, 'description': 'Optional view-count floor. Default 0.'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'videos': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'url': {'type': 'string'}, 'likes': {'type': 'number'}, 'saves': {'type': 'number'}, 'views': {'type': 'number'}, 'author': {'type': 'object', 'properties': {'nickname': {'type': 'string'}, 'username': {'type': 'string'}}}, 'shares': {'type': 'number'}, 'comments': {'type': 'number'}, 'duration': {'type': 'number'}, 'hashtags': {'type': 'array', 'items': {'type': 'string'}}, 'posted_at': {'type': 'string'}, 'thumbnail': {'type': 'string'}, 'description': {'type': 'string'}, 'engagement_score': {'type': 'number'}}}}, 'applied': {'type': 'object', 'description': 'Echo of the filters actually applied — useful for debugging when results look surprising'}, 'quality': {'type': 'object', 'properties': {'level': {'enum': ['full', 'partial', 'degraded'], 'type': 'string'}, 'reason': {'type': 'string'}}}, 'from_payg': {'type': 'boolean'}, 'filtered_count': {'type': 'number', 'description': 'Videos returned after filtering + cap'}, 'upstream_count': {'type': 'number', 'description': 'Videos returned by upstream before any filtering'}, 'credits_remaining': {'type': 'number', 'description': 'Credits remaining after this call'}, 'from_subscription': {'type': 'boolean'}}}

{'type': 'object', 'properties': {'niche': {'enum': ['Beauty & Skincare', 'Fitness & Health', 'Food & Cooking', 'Fashion & Style', 'Tech & Gadgets', 'Finance & Business', 'Education & Learning', 'Travel & Adventure', 'Comedy & Entertainment', 'Gaming', 'Lifestyle & Wellness', 'Parenting & Family', 'DIY & Crafts', 'Music & Dance', 'Pets & Animals', 'Sports', 'Motivation & Self-Help', 'SaaS & AI Tools'], 'type': 'string', 'description': 'One of the 17 supported niches. Loose names like "travel" or "fitness" are accepted but pass the canonical form when possible. Omit for broadly applicable trends.'}, 'region': {'type': 'string', 'description': 'Optional 2-letter ISO country code (US, GB, BR, JP, IN, PH, etc.). Threads to Google Trends geo + YouTube regionCode. Defaults to US when omitted. Reddit signals are global and ignore this param.'}, 'deadline_hours': {'type': 'integer', 'maximum': 168, 'minimum': 1, 'description': 'Optional (2026-07-06 magic-genie ritual): how many hours until the video posts. When set, each rising trend gets a trend_status (up-slope | plateau | fading | unknown) AND a deadline_verdict (safe | risky | no-go) so managers can answer "will this trend still be alive when the video posts?" without eyeballing the growth label. Use this on every brief-just-landed call — it turns trend_pulse from "what\'s trending" into "what\'s SAFE to bet on for MY post window."'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'niche': {'type': 'string', 'description': 'The niche these trends apply to'}, 'rising': {'type': 'array', 'items': {'type': 'object', 'properties': {'type': {'type': 'string'}, 'title': {'type': 'string'}, 'growth': {'type': 'string', 'description': 'Qualitative growth label ("Rising", "Early signal", "Accelerating"). NOT a numeric percentage — the upstream does not compute "+178%"-style rates. Use signal_strength as the quantitative anchor.'}, 'suggestion': {'type': 'string'}}}, 'description': 'Rising opportunities (format/hook/style) with qualitative growth labels + signal_strength numeric anchor (0-1) + suggestions'}, 'from_payg': {'type': 'boolean', 'description': 'Whether credits came from pay-as-you-go balance'}, 'saturated': {'type': 'array', 'items': {'type': 'object', 'properties': {'type': {'type': 'string'}, 'title': {'type': 'string'}, 'status': {'type': 'string'}}}, 'description': 'Saturated patterns to avoid'}, 'credits_remaining': {'type': 'number', 'description': 'Credits remaining after this call'}, 'from_subscription': {'type': 'boolean', 'description': 'Whether credits came from subscription'}}}

{'type': 'object', 'anyOf': [{'required': ['source_url']}, {'required': ['transcript']}], 'properties': {'niche': {'type': 'string', 'description': 'Optional niche hint'}, 'my_topic': {'type': 'string', 'description': 'DEPRECATED alias for target_topic. Legacy clients only. Normalized internally.'}, 'platform': {'enum': ['tiktok', 'reels', 'shorts'], 'type': 'string', 'description': 'Target platform for the remix. Adjusts pacing and CTA style if provided.'}, 'source_url': {'type': 'string', 'description': 'TikTok/YouTube/Instagram URL — transcript will be auto-extracted'}, 'transcript': {'type': 'string', 'description': 'Pre-extracted transcript (alternative to source_url, faster)'}, 'target_topic': {'type': 'string', 'description': 'What the remix should be about. Default: same niche as original.'}, 'target_product': {'type': 'string', 'description': 'The product the remix should promote. When provided, the generator will NOT invent product names, prices, timelines, features, or customer stories. Combined with verified_product_facts, this forces on-topic + grounded output.'}, 'verified_product_facts': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Facts the generator is allowed to cite about target_product (e.g. "runs inside ChatGPT and Claude", "12 tools for viral research"). Every specific product claim in the generated script is checked against this list — unsupported claims populate unsupported_claims[] and downgrade quality. If target_product is passed WITHOUT verified_product_facts, the response will land at degraded quality (generation cannot be grounded).'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'overlays': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Text overlay suggestions per scene'}, 'from_payg': {'type': 'boolean', 'description': 'Whether credits came from pay-as-you-go balance'}, 'verify_hook': {'type': 'object', 'description': 'The hook plus a suggested follow-up: the caller may pass it to score_hook for a structurally-independent score (the script generator deliberately does NOT self-rate). Informational only, not an instruction to call anything.'}, 'camera_shots': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Phone-native camera direction per scene'}, 'fresh_script': {'type': 'object', 'properties': {'cta': {'type': 'string', 'description': 'Call-to-action closing'}, 'hook': {'type': 'string', 'description': 'Opening hook line'}, 'scenes': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Scene-by-scene script with voiceover, visuals, and timing'}}, 'description': 'Complete scene-by-scene script mirroring the source structure'}, 'cta_archetype': {'enum': ['result_close', 'soft_bio_pointer', 'genuine_question', 'pinned_comment', 'comment_gate'], 'type': 'string', 'description': 'Which CTA archetype the generator picked. Comment_gate is the failure-mode default for AI script generators; rotation tells you whether the prompt is working.'}, 'ugc_authenticity': {'type': 'object', 'properties': {'level': {'enum': ['native', 'ad_leaning'], 'type': 'string', 'description': 'Honest signal of whether the generator drifted ad-ward'}, 'reasons': {'type': 'array', 'items': {'type': 'string'}, 'description': 'List of detected drift reasons (e.g. "hook is 22 words", "CTA is comment-gate")'}}, 'description': 'Tripwire for ad-shaped drift. Detected via regex on the produced script, not the model self-grade. If level=ad_leaning, surface to the user before shipping.'}, 'credits_remaining': {'type': 'number', 'description': 'Credits remaining after this call'}, 'extracted_formula': {'type': 'string', 'description': 'The viral DNA formula extracted from the source'}, 'from_subscription': {'type': 'boolean', 'description': 'Whether credits came from subscription'}, 'structural_skeleton': {'type': 'string', 'description': 'Which structural skeleton the generator used (confession_to_result, mistake_to_correction, etc). Surfaces rotation across the fleet.'}}}

{'type': 'object', 'required': ['handle', 'platform'], 'properties': {'handle': {'type': 'string', 'description': 'Creator handle (with or without @ prefix). Examples: "@mrbeast", "mrbeast".'}, 'platform': {'enum': ['tiktok', 'instagram', 'youtube'], 'type': 'string', 'description': 'Platform the creator publishes on. Same platforms as analyze_account.'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'status': {'enum': ['tracked', 'already_tracked'], 'type': 'string'}, 'creator': {'type': 'string', 'description': 'Normalized "@handle" the watch is stored under'}, 'message': {'type': 'string'}, 'platform': {'enum': ['tiktok', 'instagram', 'youtube'], 'type': 'string'}, 'watch_id': {'type': 'string'}, 'data_age_days': {'type': 'number', 'description': 'Age in days of the newest video in the baseline'}, 'snapshot_count': {'type': 'number', 'description': 'Total snapshots stored for this watch so far'}, 'baseline_source': {'enum': ['watch_snapshot', 'analysis_cache', 'fresh'], 'type': 'string', 'description': 'watch_snapshot = existing CreatorWatch already had a fresh snapshot (0 credits); analysis_cache = recent analyze_account response reused to build a new baseline (0 credits); fresh = analyze_account invoked, 5 credits charged.'}, 'credits_charged': {'type': 'number'}, 'baseline_created_at': {'type': 'string', 'description': 'ISO timestamp of the baseline snapshot'}}}