{"openapi":"3.1.0","info":{"title":"Frankreel API","version":"1.0.0","description":"YouTube growth tools for your own channel: keyword scores, title and thumbnail scores, AI titles, descriptions, tags and ideas, outliers, competitors, a channel audit and an AI coach. Authenticate with a personal API key (Settings, AI & API) as \"Authorization: Bearer fr_live_...\", or with OAuth. AI operations cost 1 credit from your monthly allowance (the coach uses 1 coach message) and are never charged when they fail; everything else is free. Every success response includes credits.remaining. Rate limit: 60 requests a minute per key. Docs: https://frankreel.com/developers","contact":{"name":"Frankreel support","url":"https://frankreel.com/help"},"termsOfService":"https://frankreel.com/terms"},"servers":[{"url":"https://frankreel.com/api/v1"}],"security":[{"bearer":[]}],"paths":{"/me":{"get":{"operationId":"get_account","summary":"Account, plan and credits","description":"Who you are signed in as, your plan, the YouTube channels you have linked (the active one is used by every other tool), and how many AI credits and coach messages you have left this month. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/channel":{"get":{"operationId":"get_channel_overview","summary":"Channel stats and insights","description":"Stats for your connected YouTube channel (subscribers, views over the last 28 days, video count, with changes) plus the current insight cards: breakout videos, weak titles, upload gaps. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/channel/audit":{"get":{"operationId":"channel_audit","summary":"Channel audit","description":"A review of your channel's last 30, 60 or 90 days: subscriber and view change, upload rhythm, best and weakest videos, Shorts against long videos, and an SEO checklist over your last 20 uploads. Rule-based from public numbers. Needs the Creator or Studio plan. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"default":30,"description":"Period to review: 30, 60 or 90 days.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Period to review: 30, 60 or 90 days."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/videos":{"get":{"operationId":"list_videos","summary":"List my videos","description":"Videos on your connected channel, newest first, with views, views per hour and outlier score (how many times the channel's usual views a video got). Use the id with analyze_video, generate_titles and the other video tools. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"default":"long","description":"long = regular videos, short = Shorts.","type":"string","enum":["long","short"]},"description":"long = regular videos, short = Shorts."},{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"How many, newest first (max 200).","type":"integer","minimum":1,"maximum":200},"description":"How many, newest first (max 200)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/videos/{video_id}":{"get":{"operationId":"analyze_video","summary":"Analyze one of my videos","description":"Full detail for one video on your channel: stats, title score with reasons, the SEO checklist (description length, keyword placement, tags, chapters), and the current draft if you are editing it in Frankreel. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[\\w-]+$","description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."},"description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/videos/{video_id}/titles":{"post":{"operationId":"generate_titles","summary":"AI title ideas for a video","description":"Three new, honest title options for one of your videos, each with its title score, written for your channel profile (niche, tone, language, avoid list). Does not change anything on YouTube. Cost: 1 AI credit from your monthly allowance. If the call fails it is not charged.","tags":["AI (uses credits)"],"x-openai-isConsequential":false,"x-credit-cost":{"meter":"ai_credit","amount":1},"security":[{"bearer":[]},{"oauth2":["write"]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[\\w-]+$","description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."},"description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tone":{"description":"Defaults to the tone in your channel profile.","type":"string","enum":["neutral","energetic","calm"]},"length":{"type":"string","enum":["shorter","longer"]},"instruction":{"description":"Extra direction, e.g. \"mention the price\".","type":"string","maxLength":300}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/videos/{video_id}/descriptions":{"post":{"operationId":"generate_descriptions","summary":"AI descriptions for a video","description":"Three description drafts (300-900 characters) for one of your videos, with the keyword and payoff in the first two lines. Does not change anything on YouTube. Cost: 1 AI credit from your monthly allowance. If the call fails it is not charged.","tags":["AI (uses credits)"],"x-openai-isConsequential":false,"x-credit-cost":{"meter":"ai_credit","amount":1},"security":[{"bearer":[]},{"oauth2":["write"]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[\\w-]+$","description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."},"description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/videos/{video_id}/tags":{"post":{"operationId":"suggest_tags","summary":"AI tag ideas for a video","description":"Up to 10 tags viewers actually search for, that the video does not have yet. Cost: 1 AI credit from your monthly allowance. If the call fails it is not charged. (Tag ideas inside the Frankreel editor stay free.)","tags":["AI (uses credits)"],"x-openai-isConsequential":false,"x-credit-cost":{"meter":"ai_credit","amount":1},"security":[{"bearer":[]},{"oauth2":["write"]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[\\w-]+$","description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."},"description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/videos/{video_id}/draft":{"patch":{"operationId":"save_draft","summary":"Save a draft title, description or tags","description":"Saves changes to the Frankreel draft for a video (title, description and/or tags). Nothing changes on YouTube until publish_draft is called. Free: uses no credits.","tags":["Write"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["write"]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[\\w-]+$","description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."},"description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"description":{"type":"string","maxLength":5000},"tags":{"maxItems":60,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/videos/{video_id}/publish":{"post":{"operationId":"publish_draft","summary":"Publish a draft to YouTube","description":"Publishes the saved draft's title, description and tags to the live video on YouTube. This changes the public video, so only call it when the user has explicitly asked to publish. The change is recorded in History and can be undone in Frankreel. Needs publishing access to the channel (granted once in the web app). Free: uses no credits.","tags":["Write"],"x-openai-isConsequential":true,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["write"]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[\\w-]+$","description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."},"description":"The video: Frankreel video id (from list_videos) or the YouTube video id (the v= part of the URL)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","const":true,"description":"Must be true. Confirms the user asked to change the live video on YouTube."}},"required":["confirm"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/changes":{"get":{"operationId":"list_changes","summary":"Published changes and their results","description":"Every title, description and tag change published through Frankreel, with before and after, and how views per day moved afterwards (measured from 3 days after the change). Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/keywords":{"get":{"operationId":"keyword_research","summary":"Keyword score","description":"Scores a YouTube search term 0-100 from public YouTube data: demand (views going to the top results), competition (big channels and exact-match titles in the top results), and an overall score with the formula shown. Also returns related searches, longer matching searches and questions when Frankreel already knows them; if related is empty, call expand_keyword. Free plan shows the top 4 of each list. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100,"description":"The search term, e.g. \"home workout\"."},"description":"The search term, e.g. \"home workout\"."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/keywords/expand":{"post":{"operationId":"expand_keyword","summary":"Related keyword ideas (AI)","description":"Finds related searches, longer searches containing the term, and questions viewers ask about it. Each can then be scored with keyword_research. Cost: 1 AI credit from your monthly allowance when the AI runs; if Frankreel already has the related terms they are returned at no cost. If the call fails it is not charged.","tags":["AI (uses credits)"],"x-openai-isConsequential":false,"x-credit-cost":{"meter":"ai_credit","amount":1},"security":[{"bearer":[]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":2,"maxLength":100,"description":"The seed search term."}},"required":["q"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/titles/score":{"post":{"operationId":"score_title","summary":"Score a title","description":"Scores a YouTube title 0-100 with the reasons (length, numbers, curiosity words, keyword position, capitals, punctuation). Deterministic: the same title always gets the same score. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"keyword":{"description":"Main keyword; checks it appears early.","type":"string","maxLength":100}},"required":["title"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/thumbnails/score":{"post":{"operationId":"score_thumbnail","summary":"Score a thumbnail","description":"Scores a thumbnail 0-100 with checks for size, 16:9 shape, brightness, contrast, colour, clutter and the corner under the length badge. Rule-based and deterministic. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"video_id":{"description":"Score the current thumbnail of one of your videos.","type":"string","minLength":1,"maxLength":64,"pattern":"^[\\w-]+$"},"image_base64":{"description":"Or a JPG or PNG under 2 MB, base64 encoded.","type":"string","maxLength":3000000}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/outliers":{"get":{"operationId":"find_outliers","summary":"Find outlier videos","description":"Videos that got several times their channel's usual views, for a topic, ranked by outlier score. Good for spotting ideas that work. On the Free plan only type and period filters apply. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"default":"","description":"Topic to search, e.g. \"kettlebell\". Empty = videos Frankreel already tracks.","type":"string","maxLength":100},"description":"Topic to search, e.g. \"kettlebell\". Empty = videos Frankreel already tracks."},{"name":"type","in":"query","required":false,"schema":{"default":"long","type":"string","enum":["long","short"]}},{"name":"period","in":"query","required":false,"schema":{"default":"year","type":"string","enum":["week","month","3m","6m","year","all"]}},{"name":"min_score","in":"query","required":false,"schema":{"description":"Minimum outlier score (paid plans).","type":"number","minimum":0,"maximum":1000},"description":"Minimum outlier score (paid plans)."},{"name":"min_views","in":"query","required":false,"schema":{"description":"Paid plans.","type":"integer","minimum":0,"maximum":2000000000},"description":"Paid plans."},{"name":"max_subscribers","in":"query","required":false,"schema":{"description":"Only channels up to this size (paid plans).","type":"integer","minimum":0,"maximum":2000000000},"description":"Only channels up to this size (paid plans)."},{"name":"min_views_per_hour","in":"query","required":false,"schema":{"description":"Paid plans.","type":"number","minimum":0},"description":"Paid plans."},{"name":"max_length_minutes","in":"query","required":false,"schema":{"description":"Paid plans.","type":"integer","minimum":1,"maximum":1000},"description":"Paid plans."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/competitors":{"get":{"operationId":"list_competitors","summary":"Tracked competitors","description":"Channels you track as competitors, with their size and usual views per video. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"add_competitor","summary":"Track a competitor","description":"Starts tracking a channel as a competitor (Free plan: 3, Creator: 20, Studio: 50). Free: uses no credits.","tags":["Write"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$","description":"Frankreel channel id from search_channels."}},"required":["channel_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/competitors/videos":{"get":{"operationId":"competitor_videos","summary":"Competitor uploads","description":"Recent uploads from the channels you track, sorted by views, views per hour or date. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"parameters":[{"name":"sort","in":"query","required":false,"schema":{"default":"views","description":"vph = views per hour.","type":"string","enum":["views","vph","date"]},"description":"vph = views per hour."},{"name":"period","in":"query","required":false,"schema":{"default":"month","type":"string","enum":["48h","week","month","all"]}},{"name":"include_mine","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/channels/search":{"get":{"operationId":"search_channels","summary":"Find a YouTube channel","description":"Looks up YouTube channels by @handle, channel URL or name, to add as competitors. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"description":"@handle, channel URL or a name."},"description":"@handle, channel URL or a name."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/competitors/{channel_id}":{"delete":{"operationId":"remove_competitor","summary":"Stop tracking a competitor","description":"Stops tracking a competitor channel. Free: uses no credits.","tags":["Write"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["write"]}],"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/ideas":{"get":{"operationId":"list_ideas","summary":"My video ideas","description":"Video ideas Frankreel has made for your channel (daily ideas and topic searches), newest first, with the predicted views relative to your usual. Free: uses no credits.","tags":["Read"],"x-openai-isConsequential":false,"x-credit-cost":null,"security":[{"bearer":[]},{"oauth2":["read"]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"default":"all","type":"string","enum":["new","saved","dismissed","all"]}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"generate_ideas","summary":"AI video ideas for a topic","description":"Video ideas about a topic, fitted to your channel, its best videos and competitor breakouts (Free plan: 3 ideas, paid: 10). Cost: 1 AI credit from your monthly allowance, and counts as one of your monthly topic searches (Free: 3). If the call fails it is not charged.","tags":["AI (uses credits)"],"x-openai-isConsequential":false,"x-credit-cost":{"meter":"ai_credit","amount":1},"security":[{"bearer":[]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"type":"string","minLength":2,"maxLength":80,"description":"Topic or keyword to get ideas about."}},"required":["topic"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/ideas/{idea_id}/blueprint":{"post":{"operationId":"create_blueprint","summary":"Video blueprint for an idea","description":"Turns an idea into a plan you can film: three titles, a hook for the first 15 seconds, a beat-by-beat outline and thumbnail concepts. Made once per idea; asking again returns the same blueprint at no cost. Cost: 1 AI credit from your monthly allowance the first time. If the call fails it is not charged.","tags":["AI (uses credits)"],"x-openai-isConsequential":false,"x-credit-cost":{"meter":"ai_credit","amount":1},"security":[{"bearer":[]},{"oauth2":["write"]}],"parameters":[{"name":"idea_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$","description":"Idea id from list_ideas or generate_ideas."},"description":"Idea id from list_ideas or generate_ideas."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/coach":{"post":{"operationId":"ask_coach","summary":"Ask the AI coach","description":"Asks Frankreel's YouTube coach a question about your channel. Answers are grounded in your channel's numbers, competitors and saved keywords. The conversation is saved in the Coach page. Cost: 1 coach message from your monthly allowance (Free: 10, Creator: 100, Studio: 250); no AI credits are used. If the call fails it is not charged.","tags":["AI (uses credits)"],"x-openai-isConsequential":false,"x-credit-cost":{"meter":"coach_message","amount":1},"security":[{"bearer":[]},{"oauth2":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":2000},"thread_id":{"description":"Continue an earlier conversation.","type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"mode":{"default":"fast","description":"deep = slower, more thorough answer.","type":"string","enum":["fast","deep"]}},"required":["message"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A personal API key (fr_live_...) from Settings, AI & API, or an OAuth access token."},"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://frankreel.com/oauth/authorize","tokenUrl":"https://frankreel.com/api/oauth/token","refreshUrl":"https://frankreel.com/api/oauth/token","scopes":{"read":"Read your channel data, research and credit balance","write":"Run AI tools, save drafts, track competitors and publish drafts you ask for"}}}}},"schemas":{"Credits":{"type":"object","properties":{"charged":{"type":"object","properties":{"ai_credits":{"type":"integer"},"coach_messages":{"type":"integer"},"idea_searches":{"type":"integer"}}},"remaining":{"type":"object","additionalProperties":true}}},"Success":{"type":"object","required":["result","credits"],"properties":{"result":{"type":"object","additionalProperties":true},"credits":{"$ref":"#/components/schemas/Credits"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["invalid_input","unauthorized","plan_limit","rate_limited","not_found"]},"message":{"type":"string"}},"additionalProperties":true}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"x-scopes":["read","write"]}