{"openapi":"3.1.0","info":{"title":"Bangerfeed API","version":"1.0.0","summary":"Outlier intelligence for Punjabi and Indian short-form creators.","description":"Bangerfeed watches creators' channels across Instagram, TikTok and YouTube, scores every video as views divided by the channel's median (the **outlier score**), analyses outliers with Gemini and surfaces the hooks, formats and topics that are breaking out.\n\n**Auth**: every endpoint except this document needs an API key (Settings > API) sent as `Authorization: Bearer lh_live_...` or `x-api-key`. API access is a Pro-plan feature; the same key also unlocks the MCP server at `/api/mcp` on Creator and above.\n\n**Credits**: analysing a video costs 1 credit, a narrated channel recap costs 2. Credit shortfalls answer `402`."},"servers":[{"url":"https://bangerfeed.com/api/v1"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Workspace"},{"name":"Videos","description":"The outlier feed and single-video detail."},{"name":"Channels","description":"Watchlist, channel search and recaps."},{"name":"Insights","description":"Hooks, formats, topics and suggestions aggregated from analysed videos."},{"name":"Collections"},{"name":"Automations","description":"Rules that auto-analyse outliers every day."},{"name":"Meta"}],"paths":{"/me":{"get":{"tags":["Workspace"],"operationId":"getMe","summary":"Workspace, plan limits and credit usage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos":{"get":{"tags":["Videos"],"operationId":"listVideos","summary":"The outlier feed","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["watchlist","global","library","mine"],"default":"watchlist"},"description":"`watchlist` = channels you watch, `global` = everything Bangerfeed tracks, `library` = videos you have analysed or saved, `mine` = channels flagged as yours."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","tiktok","youtube","all"],"default":"all"},"description":"Restrict to one platform."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Detected language of the post (`pa`, `hi`, `en`, `hinglish`...)."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":3650,"default":30},"description":"Posted within the last N days. `0` = all time."},{"name":"min","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Minimum outlier score."},{"name":"views","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum views."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text search over caption, title, transcript and hook."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["outlier","views","recent","engagement"],"default":"outlier"},"description":"Sort order."},{"name":"analysed","in":"query","required":false,"schema":{"type":"string","enum":["1","0"]},"description":"`1` = only videos with a finished analysis."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":24},"description":"Rows per page."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"total":{"type":"integer"},"page":{"type":"integer"},"page_size":{"type":"integer"}},"required":["items","total","page","page_size"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/{id}":{"get":{"tags":["Videos"],"operationId":"getVideo","summary":"One video with channel, analysis and hook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Video id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoDetail"}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/analyze":{"post":{"tags":["Videos"],"operationId":"analyzeVideo","summary":"Queue analysis for a URL or a known post (1 credit)","description":"Pass a public Instagram reel, TikTok or YouTube URL (Bangerfeed scrapes it if it has never seen it) or the `post_id` of a video already in the feed. Adds it to your library and queues Gemini analysis. Analysis usually finishes in 1-3 minutes; poll `GET /videos/{id}` and watch `analysis.status`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public video URL"},"post_id":{"type":"string","format":"uuid","description":"Existing post id"}},"description":"Exactly one of `url` or `post_id`."}}}},"responses":{"200":{"description":"Queued, already queued, or already analysed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeResult"}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeResult"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels":{"get":{"tags":["Channels"],"operationId":"listWatchlist","summary":"Your watchlist with 7-day activity","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WatchedChannel"}},"total":{"type":"integer"}},"required":["items","total"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Channels"],"operationId":"addChannel","summary":"Watch a channel","description":"Adds the channel to your watchlist (subject to your plan's channel limit) and starts the first history pull so the median and outliers appear within minutes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Profile URL, e.g. https://www.instagram.com/handle"},"handle":{"type":"string","description":"Bare handle, with `platform`"},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]}},"description":"A profile `url`, or a `handle` plus `platform`."}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelMutation"}}}},"400":{"description":"Could not add (bad handle, channel limit reached).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelMutation"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels/search":{"get":{"tags":["Channels"],"operationId":"searchChannels","summary":"Search the shared channel graph","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Matches handle, display name or bio."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","tiktok","youtube","all"],"default":"all"},"description":"Restrict to one platform."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Primary language of the channel."},{"name":"min_followers","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum followers."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["followers","outlier","recent"],"default":"followers"},"description":"`outlier` sorts by views per follower."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":40},"description":"Max rows."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"total":{"type":"integer"}},"required":["items","total"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels/{id}":{"get":{"tags":["Channels"],"operationId":"getChannel","summary":"One channel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Channel id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelWithWatch"}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Channels"],"operationId":"removeChannel","summary":"Stop watching a channel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Channel id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string"}},"required":["ok","id"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/channels/{id}/recap":{"get":{"tags":["Channels"],"operationId":"getChannelStats","summary":"Window stats for a channel (free, no narrative)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Channel id"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":365,"default":30},"description":"Look-back window."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"stats":{"$ref":"#/components/schemas/ChannelWindowStats"}},"required":["days","stats"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Channels"],"operationId":"createChannelRecap","summary":"Narrated recap (2 credits)","description":"Runs the window stats and asks Gemini for a 180-260 word brief on what is working, what the outliers share and what to copy this week. Stored as a report; credits are refunded if generation fails.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Channel id"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"maximum":365,"default":30}}}}}},"responses":{"201":{"description":"Report created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits (`balance`, `cost`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/hooks":{"get":{"tags":["Insights"],"operationId":"topHooks","summary":"Strongest spoken hooks","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["watchlist","global"],"default":"watchlist"},"description":"`watchlist` = only channels you watch; `global` = the whole Bangerfeed graph."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","tiktok","youtube","all"],"default":"all"},"description":"Restrict to one platform."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Language code of the analysis (`pa`, `hi`, `en`, `hinglish`...)."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":3650,"default":30},"description":"Look-back window in days. `0` = all time."},{"name":"min","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Minimum outlier score (views / channel median)."},{"name":"views","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum views."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Max rows (each endpoint has its own default)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Hook"}},"total":{"type":"integer"}},"required":["items","total"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/formats":{"get":{"tags":["Insights"],"operationId":"topFormats","summary":"Format buckets ranked by outlier strength","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["watchlist","global"],"default":"watchlist"},"description":"`watchlist` = only channels you watch; `global` = the whole Bangerfeed graph."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","tiktok","youtube","all"],"default":"all"},"description":"Restrict to one platform."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Language code of the analysis (`pa`, `hi`, `en`, `hinglish`...)."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":3650,"default":30},"description":"Look-back window in days. `0` = all time."},{"name":"min","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Minimum outlier score (views / channel median)."},{"name":"views","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum views."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Max rows (each endpoint has its own default)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"byCategory":{"type":"array","items":{"$ref":"#/components/schemas/Bucket"}},"byType":{"type":"array","items":{"$ref":"#/components/schemas/Bucket"}},"analysed":{"type":"integer","description":"Analysed videos in the window"}},"required":["byCategory","byType","analysed"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/topics":{"get":{"tags":["Insights"],"operationId":"topTopics","summary":"Topic, hook-category and register buckets","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["watchlist","global"],"default":"watchlist"},"description":"`watchlist` = only channels you watch; `global` = the whole Bangerfeed graph."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","tiktok","youtube","all"],"default":"all"},"description":"Restrict to one platform."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Language code of the analysis (`pa`, `hi`, `en`, `hinglish`...)."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":3650,"default":30},"description":"Look-back window in days. `0` = all time."},{"name":"min","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Minimum outlier score (views / channel median)."},{"name":"views","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum views."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Max rows (each endpoint has its own default)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"topics":{"type":"array","items":{"$ref":"#/components/schemas/Bucket"}},"hookCategories":{"type":"array","items":{"$ref":"#/components/schemas/Bucket"}},"registers":{"type":"array","items":{"$ref":"#/components/schemas/Bucket"}},"analysed":{"type":"integer"}},"required":["topics","hookCategories","registers","analysed"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suggest":{"get":{"tags":["Insights"],"operationId":"suggestVideos","summary":"What to make next","description":"Topics with momentum (defaults: last 30 days, 10K+ views, outlier >= 1) with an example angle, hook and remake ideas each.","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["watchlist","global"],"default":"watchlist"},"description":"`watchlist` = only channels you watch; `global` = the whole Bangerfeed graph."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["instagram","tiktok","youtube","all"],"default":"all"},"description":"Restrict to one platform."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Language code of the analysis (`pa`, `hi`, `en`, `hinglish`...)."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":3650,"default":30},"description":"Look-back window in days. `0` = all time."},{"name":"min","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Minimum outlier score (views / channel median)."},{"name":"views","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Minimum views."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Max rows (each endpoint has its own default)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Suggestion"}},"total":{"type":"integer"}},"required":["items","total"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/collections":{"get":{"tags":["Collections"],"operationId":"listCollections","summary":"Collections with item counts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"total":{"type":"integer"}},"required":["items","total"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/collections/{id}/items":{"post":{"tags":["Collections"],"operationId":"addToCollection","summary":"Save a video into a collection","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Collection id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"string","format":"uuid"},"note":{"type":"string","description":"Optional note, max 500 chars"}},"required":["post_id"]}}}},"responses":{"201":{"description":"Saved (idempotent)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"collection_id":{"type":"string"},"post_id":{"type":"string"}},"required":["ok","collection_id","post_id"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection or video not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rules":{"get":{"tags":["Automations"],"operationId":"listRules","summary":"Automation rules","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Rule"}},"total":{"type":"integer"}},"required":["items","total"]}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Automations"],"operationId":"createRule","summary":"Create an automation rule","description":"Every day the rule scans the chosen channels (or your whole watchlist) for videos above the thresholds and queues analysis for up to `daily_limit` new ones, 1 credit each.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuleInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rule"}}}},"400":{"description":"Validation failed. `error` holds the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace plan does not include API access. `plan_required` names the upgrade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"tags":["Meta"],"operationId":"getOpenApi","summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"lh_live_...","description":"API key from Settings > API."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"plan":{"type":"string"},"plan_required":{"type":"string"},"balance":{"type":"integer"},"cost":{"type":"integer"}},"required":["error"]},"Workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string","enum":["free","creator","pro"]},"limits":{"type":"object","properties":{"channels":{"type":"integer","description":"Competitors tracked per workspace"},"verified_channels":{"type":"integer","description":"Your own channels with the fast refresh"},"monthly_credits":{"type":"integer"},"refresh_hours":{"type":"integer","description":"Refresh interval for verified channels; competitors refresh daily"}},"required":["channels","verified_channels","monthly_credits","refresh_hours"]},"credits":{"type":"object","properties":{"used":{"type":"integer","description":"Spent since the last monthly grant"},"granted":{"type":"integer","description":"Size of the last grant"},"balance":{"type":"integer","description":"Credits left"}},"required":["used","granted","balance"]},"api_access":{"type":"boolean"},"mcp_access":{"type":"boolean"},"default_language":{"type":"string"}},"required":["id","name","plan","limits","credits"]},"ChannelRef":{"type":"object","properties":{"id":{"type":"string"},"handle":{"type":"string"},"display_name":{"type":["string","null"]}},"required":["id","handle"]},"Video":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"channel":{"$ref":"#/components/schemas/ChannelRef"},"posted_at":{"type":["string","null"],"format":"date-time"},"views":{"type":["integer","null"]},"likes":{"type":["integer","null"]},"comments":{"type":["integer","null"]},"outlier_score":{"type":["number","null"],"description":"views / channel median"},"engagement_rate":{"type":["number","null"],"description":"(likes + comments + shares + saves) / views"},"language":{"type":["string","null"]},"caption":{"type":["string","null"]},"title":{"type":["string","null"]},"thumbnail_url":{"type":["string","null"]},"analysis_status":{"type":["string","null"],"enum":["queued","running","done","failed","skipped",null]},"in_library":{"type":"boolean"}},"required":["id","url","platform","channel","analysis_status","in_library"]},"VideoAnalysis":{"type":"object","properties":{"format_category":{"type":"string"},"format_type":{"type":"string"},"format_flavor":{"type":"string"},"format_reasoning":{"type":"string"},"spoken_hook":{"type":"string","description":"Hook as spoken, original language"},"spoken_hook_en":{"type":"string","description":"Hook in English"},"spoken_hook_madlib":{"type":"string","description":"Reusable hook template"},"spoken_hook_category":{"type":"string"},"hook_alignment":{"type":"string"},"on_screen_hook":{"type":["string","null"]},"visual_layout_category":{"type":"string"},"visual_layout_type":{"type":"string"},"narrative_structure":{"type":"array","items":{"type":"object","properties":{"section":{"type":"string"},"start_s":{"type":"number"},"end_s":{"type":"number"},"purpose":{"type":"string"}}}},"seed":{"type":"string"},"topic":{"type":"string"},"angle":{"type":"string"},"summary":{"type":"string"},"supporting_evidence":{"type":"array","items":{"type":"string"}},"common_belief":{"type":"string"},"contrarian_reality":{"type":"string"},"language":{"type":"string"},"script":{"type":"string"},"code_switch_ratio":{"type":"number"},"register":{"type":"string"},"on_screen_text_language":{"type":"string"},"cultural_references":{"type":"array","items":{"type":"string"}},"cta":{"type":["string","null"]},"why_it_worked":{"type":"array","items":{"type":"string"}},"remake_ideas":{"type":"array","items":{"type":"string"}}},"description":"Gemini analysis of one video."},"Analysis":{"type":"object","properties":{"status":{"type":["string","null"],"enum":["queued","running","done","failed","skipped",null]},"language":{"type":["string","null"]},"script":{"type":["string","null"]},"register":{"type":["string","null"]},"code_switch_ratio":{"type":["number","null"]},"on_screen_text_language":{"type":["string","null"]},"transcript":{"type":["string","null"]},"transcript_romanised":{"type":["string","null"]},"transcript_en":{"type":["string","null"]},"result":{"oneOf":[{"$ref":"#/components/schemas/VideoAnalysis"},{"type":"null"}]},"error":{"type":["string","null"]},"model":{"type":["string","null"]},"finished_at":{"type":["string","null"],"format":"date-time"}}},"Hook":{"type":"object","properties":{"id":{"type":"string"},"post_id":{"type":"string"},"hook_text":{"type":"string"},"hook_text_en":{"type":["string","null"]},"hook_category":{"type":["string","null"]},"hook_madlib":{"type":["string","null"]},"hook_alignment":{"type":["string","null"]},"language":{"type":["string","null"]},"views":{"type":["integer","null"]},"outlier":{"type":["number","null"]},"posted_at":{"type":["string","null"]},"url":{"type":"string"},"thumbnail_url":{"type":["string","null"]},"handle":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]}}},"Channel":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"handle":{"type":"string"},"display_name":{"type":["string","null"]},"url":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"bio":{"type":["string","null"]},"followers":{"type":["integer","null"]},"posts_count":{"type":["integer","null"]},"median_views":{"type":["number","null"]},"median_views_90d":{"type":["number","null"]},"views_per_follower":{"type":["number","null"]},"avg_engagement_rate":{"type":["number","null"]},"primary_language":{"type":["string","null"]},"primary_script":{"type":["string","null"]},"niche":{"type":"array","items":{"type":"string"}},"region":{"type":["string","null"]},"verified":{"type":"boolean"},"stats_sample":{"type":"integer","description":"Videos behind the median"},"stats_updated_at":{"type":["string","null"]},"last_refreshed_at":{"type":["string","null"]},"backfilled_at":{"type":["string","null"]}},"required":["id","platform","handle"]},"ChannelWithWatch":{"allOf":[{"$ref":"#/components/schemas/Channel"},{"type":"object","properties":{"in_watchlist":{"type":"boolean"},"is_mine":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"added_at":{"type":["string","null"]}}}]},"WatchedChannel":{"allOf":[{"$ref":"#/components/schemas/Channel"},{"type":"object","properties":{"is_mine":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"added_at":{"type":"string"},"posts_7d":{"type":"integer"},"best_outlier_7d":{"type":["number","null"]}}}]},"ChannelMutation":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string"},"message":{"type":"string"}},"required":["ok"]},"VideoDetail":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"external_id":{"type":"string"},"shortcode":{"type":["string","null"]},"media_type":{"type":"string","enum":["reel","video","short","carousel","image","story","other"]},"channel_id":{"type":"string"},"posted_at":{"type":["string","null"]},"first_seen_at":{"type":"string"},"views":{"type":["integer","null"]},"likes":{"type":["integer","null"]},"comments":{"type":["integer","null"]},"shares":{"type":["integer","null"]},"saves":{"type":["integer","null"]},"outlier_score":{"type":["number","null"]},"engagement_rate":{"type":["number","null"]},"views_per_follower":{"type":["number","null"]},"language":{"type":["string","null"]},"script":{"type":["string","null"]},"is_romanised":{"type":["boolean","null"]},"caption":{"type":["string","null"]},"title":{"type":["string","null"]},"hashtags":{"type":"array","items":{"type":"string"}},"duration_s":{"type":["number","null"]},"thumbnail_url":{"type":["string","null"]},"is_pinned":{"type":"boolean"},"metrics_updated_at":{"type":["string","null"]},"channel":{"oneOf":[{"$ref":"#/components/schemas/Channel"},{"type":"null"}]},"analysis":{"oneOf":[{"$ref":"#/components/schemas/Analysis"},{"type":"null"}]},"hook":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"hook_text":{"type":"string"},"hook_text_en":{"type":["string","null"]},"hook_category":{"type":["string","null"]},"hook_madlib":{"type":["string","null"]},"hook_alignment":{"type":["string","null"]},"language":{"type":["string","null"]}}},{"type":"null"}]},"in_watchlist":{"type":"boolean"},"library":{"oneOf":[{"type":"object","properties":{"status":{"type":"string"},"source":{"type":"string"},"created_at":{"type":"string"}}},{"type":"null"}]},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"metrics":{"type":"array","items":{"type":"object","properties":{"captured_at":{"type":"string"},"views":{"type":["integer","null"]},"likes":{"type":["integer","null"]},"comments":{"type":["integer","null"]}}},"description":"Metric snapshots, oldest first"}},"required":["id","url","platform","channel_id"]},"AnalyzeResult":{"type":"object","properties":{"ok":{"type":"boolean"},"message":{"type":"string"},"post_id":{"type":["string","null"]},"queued":{"type":"boolean","description":"True when a Gemini run was queued (vs already done)"}},"required":["ok","message","post_id","queued"]},"ChannelWindowStats":{"type":"object","properties":{"channel_id":{"type":"string"},"handle":{"type":"string"},"platform":{"type":"string"},"display_name":{"type":["string","null"]},"followers":{"type":["integer","null"]},"posts":{"type":"integer"},"videos":{"type":"integer"},"median_views":{"type":["number","null"]},"total_views":{"type":"integer"},"avg_er":{"type":["number","null"]},"best_outlier":{"type":["number","null"]},"views_per_follower":{"type":["number","null"]},"posts_per_week":{"type":"number"},"analysed":{"type":"integer"},"language_mix":{"type":"object","additionalProperties":{"type":"integer"}},"top_posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"caption":{"type":["string","null"]},"title":{"type":["string","null"]},"views":{"type":["integer","null"]},"outlier":{"type":["number","null"]},"posted_at":{"type":["string","null"]},"thumbnail_url":{"type":["string","null"]},"hook":{"type":["string","null"]},"topic":{"type":["string","null"]},"format":{"type":["string","null"]}}}},"hook_categories":{"type":"object","additionalProperties":{"type":"integer"}},"formats":{"type":"object","additionalProperties":{"type":"integer"}},"topics":{"type":"array","items":{"type":"string"}}}},"Report":{"type":"object","properties":{"id":{"type":"string"},"workspace_id":{"type":"string"},"type":{"type":"string","enum":["recap","head_to_head"]},"title":{"type":"string"},"status":{"type":["string","null"],"enum":["queued","running","done","failed","skipped",null]},"params":{"type":"object"},"result":{"oneOf":[{"type":"object","properties":{"stats":{"$ref":"#/components/schemas/ChannelWindowStats"},"narrative":{"type":"string"}}},{"type":"null"}]},"credits_charged":{"type":"integer"},"error":{"type":["string","null"]},"created_at":{"type":"string"},"finished_at":{"type":["string","null"]}},"required":["id","type","title","status"]},"Bucket":{"type":"object","properties":{"key":{"type":"string"},"count":{"type":"integer"},"median_outlier":{"type":["number","null"]},"avg_outlier":{"type":["number","null"]},"total_views":{"type":"integer"},"sample":{"type":"array","items":{"type":"object","properties":{"post_id":{"type":"string"},"url":{"type":"string"},"views":{"type":["integer","null"]},"outlier":{"type":["number","null"]},"thumbnail_url":{"type":["string","null"]},"handle":{"type":"string"}}}}}},"Suggestion":{"allOf":[{"$ref":"#/components/schemas/Bucket"},{"type":"object","properties":{"angle":{"type":["string","null"]},"hook":{"type":["string","null"]},"remake_ideas":{"type":"array","items":{"type":"string"}}}}]},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"item_count":{"type":"integer"}},"required":["id","name","item_count"]},"RuleInput":{"type":"object","properties":{"name":{"type":"string","maxLength":80,"default":"Top daily performers"},"channel_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"Null or empty = the whole watchlist."},"platforms":{"type":["array","null"],"items":{"type":"string","enum":["instagram","tiktok","youtube"]}},"outlier_min":{"type":"number","minimum":0,"default":2},"views_min":{"type":"integer","minimum":0,"default":10000},"er_min":{"type":"number","minimum":0,"maximum":100,"default":0,"description":"Minimum engagement rate, percent."},"days_back":{"type":"integer","minimum":1,"maximum":90,"default":7},"daily_limit":{"type":"integer","minimum":1,"maximum":50,"default":5,"description":"Max analyses queued per run (1 credit each)."},"active":{"type":"boolean","default":true}}},"Rule":{"allOf":[{"$ref":"#/components/schemas/RuleInput"},{"type":"object","properties":{"id":{"type":"string"},"workspace_id":{"type":"string"},"created_at":{"type":"string"},"last_run_at":{"type":["string","null"]}},"required":["id","workspace_id"]}]}}}}