{"openapi":"3.1.0","info":{"title":"Niche King YouTube Strategy API","version":"1.0.0","description":"AI-powered YouTube content strategy and generation API for creators. Access niche research, generate video titles, scripts, thumbnails, descriptions, and more. All content is personalized to your niche, audience, and brand voice.","contact":{"name":"Niche King Support","url":"https://app.nicheking.video","email":"support@nicheking.video"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://app.nicheking.video/api/v1","description":"Production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication. Use either a JWT session token or an API key with sk-nk- prefix."}},"schemas":{"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code for programmatic handling","enum":["VALIDATION_ERROR","UNAUTHORIZED","ACCESS_EXPIRED","RATE_LIMIT","USAGE_LIMIT","GENERATION_FAILED","NOT_FOUND","CONFLICT"]},"detail":{"type":"string","description":"Additional error details (development mode only)"}}},"NicheProfile":{"type":"object","properties":{"broadNiche":{"type":"string","description":"Broad niche category (e.g., \"YouTube Growth & Creator Education\")"},"focusedNiche":{"type":"string","description":"Specific niche focus"},"slogan":{"type":"string","description":"Channel slogan or tagline"},"nicheStatement":{"type":"string","description":"Identity statement (e.g., \"I am the ___ for ___\")"},"mission":{"type":"string","description":"Channel mission statement"},"purpose":{"type":"string","description":"Why the channel exists"},"passion":{"type":"string","description":"What the creator is passionate about"},"keywords":{"type":"array","items":{"type":"string"},"description":"SEO keywords (4 required)","minItems":4,"maxItems":4},"insiderTerms":{"type":"array","items":{"type":"string"},"description":"Industry-specific terminology"},"targetAudience":{"type":"string","description":"Description of ideal viewer"},"channelGoals":{"type":"string","description":"Primary channel goals"},"painPoints":{"type":"string","description":"Audience pain points"},"profitModel":{"type":"string","description":"How the channel makes money"},"topCompetitors":{"type":"array","items":{"type":"string"},"description":"Competing channels or creators"},"conferences":{"type":"array","items":{"type":"string"},"description":"Industry conferences in the niche"},"industrySpeakers":{"type":"array","items":{"type":"string"},"description":"Notable speakers and influencers"},"podcasters":{"type":"array","items":{"type":"string"},"description":"Relevant podcasts and hosts"},"sponsors":{"type":"array","items":{"type":"string"},"description":"Brands sponsoring content in the niche"},"contentLanguage":{"type":"string","description":"Content language for AI generation","enum":["english","spanish","portuguese","hindi","arabic","french","japanese","korean","german","indonesian"],"default":"english"}}},"NicheScore":{"type":"object","required":["overallScore","dimensions"],"properties":{"overallScore":{"type":"number","minimum":0,"maximum":100,"description":"Overall niche clarity score"},"letterGrade":{"type":"string","enum":["A+","A","A-","B+","B","B-","C+","C","C-","D","F"],"description":"Letter grade equivalent"},"dimensions":{"type":"array","minItems":5,"maxItems":5,"items":{"type":"object","required":["name","score","feedback"],"properties":{"name":{"type":"string","enum":["Niche Clarity","Brand Identity","Audience Understanding","Competitive Edge","Monetization Readiness"]},"score":{"type":"number","minimum":1,"maximum":10,"description":"Score for this dimension"},"feedback":{"type":"string","description":"Actionable feedback for improvement"}}}},"topStrength":{"type":"string","description":"Your strongest dimension"},"topImprovement":{"type":"string","description":"Area with most impact potential"},"keywordValidation":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"quality":{"type":"string","enum":["excellent","good","fair","weak"]},"feedback":{"type":"string"}}},"description":"Validation of each keyword"}}},"MyVideo":{"type":"object","required":["id","title","contentType","formulaType","status","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Video idea ID"},"title":{"type":"string","description":"Working title"},"contentType":{"type":"string","enum":["Long","Short","Live Stream","Podcast","Community Post","Film"],"description":"Type of content"},"formulaType":{"type":"string","description":"Script formula or structure"},"status":{"type":"string","enum":["planned","scripted","filmed","edited","published"],"description":"Current pipeline status"},"seriesId":{"type":"string","format":"uuid","description":"Series ID if part of recurring series","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"When the video was committed"}}},"VideoIdea":{"type":"object","required":["id","title","contentType","formulaType","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"contentType":{"type":"string","enum":["Long","Short","Live Stream","Podcast","Community Post","Film"]},"formulaType":{"type":"string"},"inspiredBy":{"type":"string","description":"Video that inspired this idea","nullable":true},"viewCount":{"type":"number","description":"Views of inspired-by video","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"ScheduleSlot":{"type":"object","required":["dayOfWeek","slotType"],"properties":{"dayOfWeek":{"type":"number","minimum":0,"maximum":6,"description":"0=Sunday, 1=Monday, ..., 6=Saturday"},"slotType":{"type":"string","enum":["publish","batch_film","edit","prep","rest"],"description":"Type of activity for this day"},"contentType":{"type":"string","enum":["Long","Short","Live Stream","Podcast","Community Post","Film"],"description":"For publish slots only","nullable":true},"publishTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"HH:MM format for publish slots","nullable":true},"assignedVideoId":{"type":"string","format":"uuid","description":"Video assigned to this publish slot","nullable":true}}},"ContentSeries":{"type":"object","required":["id","name","description","scriptFormula","isActive"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":200,"description":"Series name"},"description":{"type":"string","maxLength":2000,"description":"Series description and theme"},"scriptFormula":{"type":"string","maxLength":5000,"description":"Plain-text script structure and beats"},"isActive":{"type":"boolean","description":"Whether series is currently in use"},"videoCount":{"type":"number","description":"Number of videos assigned to this series"},"createdAt":{"type":"string","format":"date-time"}}},"ResearchPatterns":{"type":"object","properties":{"titles":{"type":"string","description":"Title pattern insights from research"},"thumbnails":{"type":"string","description":"Thumbnail design patterns"},"longScripts":{"type":"string","description":"Long-form script structure patterns"},"shortScripts":{"type":"string","description":"Short-form script patterns"},"descriptions":{"type":"string","description":"Description writing patterns"},"ideas":{"type":"string","description":"Video idea patterns and gaps"}}},"ToolRun":{"type":"object","required":["id","toolName","status","generatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique generation ID"},"toolName":{"type":"string","description":"Which AI tool was used"},"status":{"type":"string","enum":["success","failed","pending"]},"input":{"type":"object","description":"Input parameters used"},"output":{"description":"Generated content (varies by tool)"},"inputTokens":{"type":"number","description":"AI tokens used for input","nullable":true},"outputTokens":{"type":"number","description":"AI tokens used for output","nullable":true},"model":{"type":"string","description":"AI model used (e.g., claude-sonnet-4-5)","nullable":true},"generatedAt":{"type":"string","format":"date-time"}}},"CreatorNote":{"type":"object","required":["id","category","content"],"properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["preference","decision","feedback","insight","style","general"],"description":"Type of note for organization"},"content":{"type":"string","maxLength":2000,"description":"Note content"},"source":{"type":"string","enum":["mcp","app"],"description":"Where the note came from"},"createdAt":{"type":"string","format":"date-time"}}},"GeneratedTitle":{"type":"object","required":["title","grade"],"properties":{"title":{"type":"string","description":"The generated title"},"grade":{"type":"string","enum":["A+","A","A-","B+","B","B-","C+","C","C-","D","F"],"description":"Quality grade"},"score":{"type":"number","minimum":0,"maximum":100,"description":"Numeric score"},"feedback":{"type":"string","description":"Why this title scored as it did"},"dimensions":{"type":"object","properties":{"nicheRelevance":{"type":"number","minimum":1,"maximum":10},"researchAlignment":{"type":"number","minimum":1,"maximum":10},"rulesCompliance":{"type":"number","minimum":1,"maximum":10},"hookStrength":{"type":"number","minimum":1,"maximum":10},"brandVoice":{"type":"number","minimum":1,"maximum":10}},"description":"5 dimension scores"}}},"GeneratedScript":{"type":"object","required":["script","grade"],"properties":{"script":{"type":"string","description":"Full script text with production cues"},"grade":{"type":"string","enum":["A+","A","A-","B+","B","B-","C+","C","C-","D","F"]},"score":{"type":"number","minimum":0,"maximum":100},"feedback":{"type":"string"},"wordCount":{"type":"number"},"estimatedDuration":{"type":"string","pattern":"^\\d{1,2}:\\d{2}$","description":"MM:SS format"}}},"ThumbnailStrategy":{"type":"object","required":["strategy","imageUrl"],"properties":{"strategy":{"type":"string","description":"Design concept and composition details"},"imageUrl":{"type":"string","format":"uri","description":"Generated thumbnail image"},"designConcept":{"type":"string","description":"Visual style and approach"},"colorPalette":{"type":"array","items":{"type":"string"},"description":"Recommended colors"},"textOverlay":{"type":"string","description":"Suggested text to overlay"},"grade":{"type":"string","enum":["A+","A","A-","B+","B","B-","C+","C","C-","D","F"]}}},"Hook":{"type":"object","required":["approach","first5Seconds","first30Seconds","whyItWorks"],"properties":{"approach":{"type":"string","enum":["Curiosity","Bold Claim/Contrarian","Story/Pattern Interrupt"]},"first5Seconds":{"type":"string","description":"Exact first 5 seconds of script"},"first30Seconds":{"type":"string","description":"First 30 seconds including setup"},"whyItWorks":{"type":"string","description":"Psychological explanation"}}},"CTA":{"type":"object","required":["slotPosition","label","text"],"properties":{"slotPosition":{"type":"string","enum":["early","middle","end","extra_1","extra_2"],"description":"When in video to place this CTA"},"label":{"type":"string","description":"Short label (e.g., \"30s Hook CTA\")"},"text":{"type":"string","description":"Full CTA copy"}}},"PodcastPrep":{"type":"object","properties":{"episodeTitle":{"type":"string"},"episodeDescription":{"type":"string"},"openingHook":{"type":"string"},"talkingPoints":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string"},"keyPoints":{"type":"array","items":{"type":"string"}},"goldenNugget":{"type":"string","description":"Most clip-worthy moment"}}}},"guestQuestions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"clipPotential":{"type":"number","minimum":1,"maximum":5,"description":"Stars for viral potential"},"clipHook":{"type":"string","description":"Exact hook phrase for Shorts"}}}},"closingCTA":{"type":"string"},"showNotes":{"type":"string"}}},"Newsletter":{"type":"object","required":["subject","preheader","bodyHtml","bodyText"],"properties":{"subject":{"type":"string","description":"Email subject line"},"preheader":{"type":"string","description":"Preview text shown in email client"},"bodyHtml":{"type":"string","description":"Full HTML email body"},"bodyText":{"type":"string","description":"Plain text fallback"},"estimatedReadTime":{"type":"number","description":"Minutes to read"}}},"Clip":{"type":"object","properties":{"startTime":{"type":"string","pattern":"^\\d{1,2}:\\d{2}:\\d{2}$","description":"HH:MM:SS"},"endTime":{"type":"string","pattern":"^\\d{1,2}:\\d{2}:\\d{2}$"},"duration":{"type":"string","pattern":"^\\d{1,2}:\\d{2}$","description":"MM:SS"},"hook":{"type":"string","description":"Rewritten hook optimized for Shorts"},"textOverlay":{"type":"string","description":"Suggested text overlay"},"clipScript":{"type":"object","properties":{"hook":{"type":"string"},"body":{"type":"string"},"cta":{"type":"string"}},"description":"[HOOK]/[BODY]/[CTA] structure"},"platforms":{"type":"array","items":{"type":"string","enum":["YouTube Shorts","TikTok","Instagram Reels","Facebook Reels","LinkedIn"]}}}},"CommunityPost":{"type":"object","properties":{"postType":{"type":"string","enum":["poll","question","quiz","announcement","behind-the-scenes","hot-take"]},"content":{"type":"string","description":"Post text"},"hashtags":{"type":"array","items":{"type":"string"}},"bestPostingTime":{"type":"string","description":"Recommended time to post"},"engagementTips":{"type":"string","description":"How to drive engagement"},"pollOptions":{"type":"array","items":{"type":"string"},"description":"For poll posts only"},"quizOptions":{"type":"array","items":{"type":"object","properties":{"option":{"type":"string"},"isCorrect":{"type":"boolean"}}},"description":"For quiz posts only"}}},"ChannelDescription":{"type":"object","properties":{"description":{"type":"string","maxLength":1000,"description":"SEO-optimized About section"}}},"PlaylistSuggestion":{"type":"object","properties":{"playlists":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"keyword":{"type":"string"}}},"maxItems":10}}},"BannerStrategy":{"type":"object","properties":{"strategy":{"type":"string","description":"Design concept for channel banner"},"imageUrl":{"type":"string","format":"uri","description":"2560x1440 banner image"},"safeZones":{"type":"object","description":"Safe area coordinates for mobile/desktop/TV"}}},"PerformanceData":{"type":"object","properties":{"monthlyReport":{"type":"object","description":"Latest monthly analytics"},"recentActivity":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"date":{"type":"string","format":"date-time"}}}},"topResearchVideos":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"views":{"type":"number"},"url":{"type":"string","format":"uri"}}},"maxItems":10},"pipelineStatus":{"type":"object","properties":{"ideas":{"type":"number"},"planned":{"type":"number"},"scripted":{"type":"number"},"filmed":{"type":"number"},"edited":{"type":"number"},"published":{"type":"number"}}},"generationStats":{"type":"object","properties":{"last30Days":{"type":"object","properties":{"titleRuns":{"type":"number"},"scriptRuns":{"type":"number"},"thumbnailRuns":{"type":"number"},"descriptionRuns":{"type":"number"},"totalRuns":{"type":"number"}}}}}}},"HealthStatus":{"type":"object","required":["status","version"],"properties":{"status":{"type":"string","enum":["ok","degraded","down"]},"version":{"type":"string","example":"1.0.0"},"timestamp":{"type":"string","format":"date-time"},"services":{"type":"object","properties":{"api":{"type":"string","enum":["ok","degraded","down"]},"database":{"type":"string","enum":["ok","degraded","down"]},"ai":{"type":"string","enum":["ok","degraded","down"]},"images":{"type":"string","enum":["ok","degraded","down"]}}}}}}},"tags":[{"name":"Context","description":"Retrieve creator profile, niche data, and content insights"},{"name":"Videos","description":"Manage committed videos and video ideas"},{"name":"Planning","description":"Weekly schedule and content series management"},{"name":"Memory","description":"Persistent creator notes and preferences"},{"name":"Generation","description":"AI content generation endpoints"},{"name":"Intelligence","description":"Performance data and content refinement"},{"name":"Utility","description":"Health checks and system status"}],"paths":{"/niche-profile":{"get":{"tags":["Context"],"summary":"Get niche profile","description":"Retrieve the creator's full niche profile with all positioning, keywords, and audience data.","operationId":"getNicheProfile","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheProfile"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/niche-score":{"post":{"tags":["Context"],"summary":"Score niche clarity","description":"AI-powered evaluation of niche clarity across 5 dimensions: Niche Clarity, Brand Identity, Audience Understanding, Competitive Edge, Monetization Readiness.","operationId":"getNicheScore","requestBody":{"description":"Optional refinement context","content":{"application/json":{"schema":{"type":"object","properties":{"context":{"type":"string","description":"Additional context for scoring"}}}}}},"responses":{"200":{"description":"Scorecard with all dimensions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheScore"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/my-videos":{"get":{"tags":["Videos"],"summary":"List committed videos","description":"Get all videos in the creator's active pipeline (My Videos).","operationId":"getMyVideos","parameters":[{"name":"status","in":"query","description":"Filter by pipeline status","schema":{"type":"string","enum":["planned","scripted","filmed","edited","published"]}},{"name":"contentType","in":"query","schema":{"type":"string","enum":["Long","Short","Live Stream","Podcast","Community Post","Film"]}}],"responses":{"200":{"description":"List of committed videos","content":{"application/json":{"schema":{"type":"object","properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/MyVideo"}},"total":{"type":"number"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Videos"],"summary":"Commit video or create new","description":"Move a video idea from backlog to active pipeline, or create a new video idea.","operationId":"commitVideo","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["ideaId"],"properties":{"ideaId":{"type":"string","format":"uuid","description":"ID of idea to commit"}}},{"type":"object","required":["title","contentType","formulaType"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"contentType":{"type":"string","enum":["Long","Short","Live Stream","Podcast","Community Post","Film"]},"formulaType":{"type":"string","description":"Script formula or structure type"}}}]}}}},"responses":{"200":{"description":"Video committed to pipeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MyVideo"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/my-videos/status":{"post":{"tags":["Videos"],"summary":"Update video status","description":"Move a video through the pipeline: planned → scripted → filmed → edited → published","operationId":"updateVideoStatus","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["videoId","status"],"properties":{"videoId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["planned","scripted","filmed","edited","published"]}}}}}},"responses":{"200":{"description":"Status updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MyVideo"}}}},"404":{"description":"Video not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/video-ideas":{"get":{"tags":["Videos"],"summary":"List video idea backlog","description":"Get uncommitted video ideas from research.","operationId":"getVideoIdeas","parameters":[{"name":"contentType","in":"query","schema":{"type":"string","enum":["Long","Short","Live Stream","Podcast","Community Post","Film"]}},{"name":"limit","in":"query","schema":{"type":"number","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"number","default":0}}],"responses":{"200":{"description":"List of video ideas","content":{"application/json":{"schema":{"type":"object","properties":{"ideas":{"type":"array","items":{"$ref":"#/components/schemas/VideoIdea"}},"total":{"type":"number"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/video-ideas/{id}":{"delete":{"tags":["Videos"],"summary":"Dismiss video idea","description":"Permanently remove an idea from the backlog.","operationId":"dismissIdea","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Idea dismissed"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Idea not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/schedule":{"get":{"tags":["Planning"],"summary":"Get weekly schedule","description":"Retrieve the creator's publishing schedule and activity plan for a given week.","operationId":"getSchedule","parameters":[{"name":"weekStart","in":"query","description":"Monday date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Weekly schedule with slots and assigned videos","content":{"application/json":{"schema":{"type":"object","properties":{"slots":{"type":"array","items":{"$ref":"#/components/schemas/ScheduleSlot"}},"weeklyVideos":{"type":"array","items":{"$ref":"#/components/schemas/MyVideo"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Planning"],"summary":"Create or update schedule slot","description":"Add a publish slot, batch film day, editing day, prep day, or rest day.","operationId":"updateScheduleSlot","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dayOfWeek","slotType"],"properties":{"dayOfWeek":{"type":"number","minimum":0,"maximum":6,"description":"0=Sunday through 6=Saturday"},"slotType":{"type":"string","enum":["publish","batch_film","edit","prep","rest"]},"contentType":{"type":"string","enum":["Long","Short","Live Stream","Podcast","Community Post","Film"],"description":"Required for publish slots"},"publishTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"HH:MM format, required for publish slots"}}}}}},"responses":{"200":{"description":"Slot created or updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleSlot"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/series":{"get":{"tags":["Planning"],"summary":"List recurring series","description":"Get all content series (pillars, buckets, shows) for the project.","operationId":"getSeries","responses":{"200":{"description":"List of series","content":{"application/json":{"schema":{"type":"object","properties":{"series":{"type":"array","items":{"$ref":"#/components/schemas/ContentSeries"}},"total":{"type":"number"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Planning"],"summary":"Create or update series","description":"Create a new recurring content series with script formula. Max 10 per project.","operationId":"createSeries","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","description","scriptFormula"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"scriptFormula":{"type":"string","maxLength":5000,"description":"Plain-text beat structure"},"isActive":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Series created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentSeries"}}}},"400":{"description":"Validation error or max series reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/research-insights":{"get":{"tags":["Context"],"summary":"Get research patterns","description":"Retrieve AI-extracted patterns from niche research across titles, thumbnails, scripts, and descriptions.","operationId":"getResearchInsights","responses":{"200":{"description":"Research patterns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchPatterns"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history":{"get":{"tags":["Context"],"summary":"Get generation history","description":"Browse all AI-generated content with filtering and search.","operationId":"getHistory","parameters":[{"name":"tool","in":"query","description":"Filter by tool type","schema":{"type":"string","enum":["titles","thumbnails","long_scripts","short_scripts","descriptions","reoptimize","hooks","ctas","podcast_prep","newsletter","clips","community_posts","channel_optimize","ideas","all"]}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"number","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"number","default":0}}],"responses":{"200":{"description":"Generation history","content":{"application/json":{"schema":{"type":"object","properties":{"history":{"type":"array","items":{"$ref":"#/components/schemas/ToolRun"}},"total":{"type":"number"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notes":{"get":{"tags":["Memory"],"summary":"Get creator notes","description":"Retrieve persistent memory notes (preferences, decisions, feedback, insights, style notes).","operationId":"getNotes","parameters":[{"name":"category","in":"query","schema":{"type":"string","enum":["preference","decision","feedback","insight","style","general"]}}],"responses":{"200":{"description":"List of notes","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"$ref":"#/components/schemas/CreatorNote"}},"total":{"type":"number"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Memory"],"summary":"Save creator note","description":"Create a persistent note in one of six categories.","operationId":"saveNote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["category","content"],"properties":{"category":{"type":"string","enum":["preference","decision","feedback","insight","style","general"]},"content":{"type":"string","minLength":1,"maxLength":2000}}}}}},"responses":{"201":{"description":"Note saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorNote"}}}},"400":{"description":"Validation error or max notes reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notes/{id}":{"delete":{"tags":["Memory"],"summary":"Delete note","operationId":"deleteNote","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Note deleted"},"404":{"description":"Note not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/titles":{"post":{"tags":["Generation"],"summary":"Generate video titles","description":"AI-powered title generation with 10 formulas, graded by quality. Returns 10 Long and 10 Short title options.","operationId":"generateTitles","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","type"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Video topic"},"type":{"type":"string","enum":["question","how-to","listicle","challenge","story","myth-buster","comparison","review","behind-the-scenes","news"],"description":"Title formula type"},"videoType":{"type":"string","enum":["Long","Short","Both"],"default":"Both","description":"Filter titles by content length"},"context":{"type":"string","description":"Additional direction or guidelines"}}}}}},"responses":{"200":{"description":"Generated titles with grades","content":{"application/json":{"schema":{"type":"object","properties":{"titles":{"type":"array","items":{"$ref":"#/components/schemas/GeneratedTitle"}},"generated":{"type":"number","description":"Total generated before filtering"},"filtered":{"type":"number","description":"Returned after quality filter"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Generation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/long-script":{"post":{"tags":["Generation"],"summary":"Generate long-form script","description":"AI-powered 8-15 minute script generation with [B-ROLL] and [GRAPHIC] markers.","operationId":"generateLongScript","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","type"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Video topic"},"type":{"type":"string","enum":["how-to","listicle","story","deep-dive","review","comparison","challenge","vlog","case-study","news"],"description":"Script framework"},"seriesId":{"type":"string","format":"uuid","description":"Recurring series formula to apply"},"context":{"type":"string","description":"Custom direction or tone"}}}}}},"responses":{"200":{"description":"Generated script","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratedScript"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Generation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/short-script":{"post":{"tags":["Generation"],"summary":"Generate short-form script","description":"AI-powered 30-60 second script for Shorts, Reels, TikToks with [VISUAL] markers.","operationId":"generateShortScript","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","type"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","enum":["quick-tip","myth-buster","hot-take","before-after","story","hack","reaction","challenge","fact","question"]},"seriesId":{"type":"string","format":"uuid"},"context":{"type":"string"}}}}}},"responses":{"200":{"description":"Generated short script","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratedScript"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Generation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/description":{"post":{"tags":["Generation"],"summary":"Generate YouTube description","description":"AI-powered description with Hero's Journey formula, AI Discovery FAQ, and hashtags. YouTube-only.","operationId":"generateDescription","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"youtubeUrl":{"type":"string","format":"uri","description":"For auto-generating timestamps/chapters"},"context":{"type":"string"}}}}}},"responses":{"200":{"description":"Generated description","content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"},"maxItems":3},"faqSection":{"type":"string","description":"AI Discovery FAQ for LLM citation"},"grade":{"type":"string","enum":["A+","A","A-","B+","B","B-","C+","C","C-","D","F"]}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/thumbnail":{"post":{"tags":["Generation"],"summary":"Generate thumbnail strategy and image","description":"AI-powered thumbnail design with Gemini image generation. Supports 6 people modes and custom backgrounds.","operationId":"generateThumbnail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","type"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","enum":["question","facts-stats","compare","emotions","focus","scale"]},"peopleMode":{"type":"string","enum":["you","both","guest","no_person","object","object_only"],"default":"you","description":"Who appears in the thumbnail"},"hasBackground":{"type":"boolean","description":"Use uploaded background image"},"context":{"type":"string"}}}}}},"responses":{"200":{"description":"Generated thumbnail design and image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThumbnailStrategy"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Image generation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/hooks":{"post":{"tags":["Generation"],"summary":"Generate opening hooks","description":"Generate 3 scroll-stopping hooks for the first 5-30 seconds with different psychological approaches.","operationId":"generateHooks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"currentHook":{"type":"string","description":"Current hook transcript for improvement analysis"},"context":{"type":"string"}}}}}},"responses":{"200":{"description":"Three hooks with different approaches","content":{"application/json":{"schema":{"type":"object","properties":{"hooks":{"type":"array","items":{"$ref":"#/components/schemas/Hook"},"minItems":3,"maxItems":3}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/ctas":{"post":{"tags":["Generation"],"summary":"Generate calls-to-action","description":"AI-powered 5 CTAs: early hook, middle value, end closing, extra_1 lead magnet, extra_2 community.","operationId":"generateCTAs","requestBody":{"description":"No parameters required","content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"5 CTAs for different placement points","content":{"application/json":{"schema":{"type":"object","properties":{"ctas":{"type":"array","items":{"$ref":"#/components/schemas/CTA"},"minItems":5,"maxItems":5}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/podcast-prep":{"post":{"tags":["Generation"],"summary":"Prepare podcast episode","description":"Golden Nugget Viral Formula for podcast prep. Every question engineered for 15-60 second clips.","operationId":"generatePodcastPrep","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["episodeType","topic"],"properties":{"episodeType":{"type":"string","enum":["solo","interview","collaboration","q_and_a","deep_dive"]},"topic":{"type":"string","minLength":1},"guestName":{"type":"string"},"guestBio":{"type":"string"}}}}}},"responses":{"200":{"description":"Episode prep with clip-engineered questions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PodcastPrep"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/newsletter":{"post":{"tags":["Generation"],"summary":"Convert video to email newsletter","description":"Transform video script or transcript into ready-to-send email in 5 styles.","operationId":"generateNewsletter","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","style"],"properties":{"title":{"type":"string","minLength":1},"style":{"type":"string","enum":["value-first","story","teaser","recap","personal"]},"youtubeUrl":{"type":"string","format":"uri","description":"Auto-fetch transcript via Supadata"},"transcript":{"type":"string","description":"Or paste transcript directly"}}}}}},"responses":{"200":{"description":"Email newsletter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Newsletter"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/clips":{"post":{"tags":["Generation"],"summary":"Analyze video for clip opportunities","description":"Find best moments in long-form video for short-form clips with hooks and scripts.","operationId":"analyzeClips","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1},"youtubeUrl":{"type":"string","format":"uri"},"transcript":{"type":"string"},"clipCount":{"type":"number","minimum":1,"maximum":10,"default":5}}}}}},"responses":{"200":{"description":"Clip suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"clips":{"type":"array","items":{"$ref":"#/components/schemas/Clip"}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/community-posts":{"post":{"tags":["Generation"],"summary":"Generate community posts","description":"Create 3 YouTube Community tab posts for engagement between uploads.","operationId":"generateCommunityPosts","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["postType"],"properties":{"postType":{"type":"string","enum":["poll","question","quiz","announcement","behind-the-scenes","hot-take"]},"title":{"type":"string"},"youtubeUrl":{"type":"string","format":"uri"},"context":{"type":"string"}}}}}},"responses":{"200":{"description":"3 community posts","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"$ref":"#/components/schemas/CommunityPost"},"minItems":3,"maxItems":3}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/channel-optimize":{"post":{"tags":["Generation"],"summary":"Optimize YouTube channel","description":"Generate channel description, playlist suggestions, or banner.","operationId":"generateChannelOptimize","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["description","playlists","banner"]},"context":{"type":"string"}}}}}},"responses":{"200":{"description":"Channel optimization output","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ChannelDescription"},{"$ref":"#/components/schemas/PlaylistSuggestion"},{"$ref":"#/components/schemas/BannerStrategy"}]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generate/reoptimize":{"post":{"tags":["Generation"],"summary":"Reoptimize published video","description":"Regenerate titles, thumbnails, and descriptions for existing published videos.","operationId":"generateReoptimize","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["youtubeUrl"],"properties":{"youtubeUrl":{"type":"string","format":"uri"},"context":{"type":"string"}}}}}},"responses":{"200":{"description":"Regenerated titles, thumbnail, and description","content":{"application/json":{"schema":{"type":"object","properties":{"titles":{"type":"array","items":{"$ref":"#/components/schemas/GeneratedTitle"}},"thumbnail":{"$ref":"#/components/schemas/ThumbnailStrategy"},"description":{"type":"string"}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/performance":{"get":{"tags":["Intelligence"],"summary":"Get performance data","description":"Aggregated monthly report, recent activity, top videos, pipeline status, and generation stats.","operationId":"getPerformance","responses":{"200":{"description":"Performance data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerformanceData"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/refine":{"post":{"tags":["Intelligence"],"summary":"Refine previous generation","description":"Iterate on a previous AI generation with feedback.","operationId":"refineGeneration","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["generationId","feedback"],"properties":{"generationId":{"type":"string","format":"uuid"},"feedback":{"type":"string","description":"What to improve"},"specificItem":{"type":"string","description":"Specific item to refine (e.g., title index)"}}}}}},"responses":{"200":{"description":"Refined content","content":{"application/json":{"schema":{"type":"object","properties":{"output":{},"originalGenerationId":{"type":"string","format":"uuid"}}}}}},"404":{"description":"Generation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"tags":["Utility"],"summary":"Health check","description":"Public health status — no authentication required.","operationId":"health","security":[],"responses":{"200":{"description":"Health status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}}}}}}}