{"openapi":"3.1.0","info":{"title":"ShortsMonkey Developer API","version":"1.0.0","description":"Read-only YouTube opportunity data with shared REST API and MCP developer credits."},"servers":[{"url":"https://api.shortsmonkey.com/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sm_live_"}},"schemas":{"VideoItem":{"type":"object","required":["video_id","title","video_url","channel","views","duration_seconds","published_at"],"properties":{"video_id":{"type":"string"},"title":{"type":"string"},"video_url":{"type":"string","format":"uri"},"channel":{"type":"object","properties":{"id":{"type":["string","null"]},"title":{"type":"string"},"subscribers":{"type":["integer","null"]},"subscriber_count_hidden":{"type":"boolean"}}},"views":{"type":"integer"},"views_to_subscribers_ratio":{"type":["number","null"]},"duration_seconds":{"type":"integer"},"published_at":{"type":"string","format":"date-time"},"niche":{"type":["string","null"]}}},"DataPage":{"type":"object","required":["items","next_cursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VideoItem"}},"next_cursor":{"type":["string","null"],"description":"Use this value as the matching all_cursor or filter_cursor to fetch the next page."}}},"DualData":{"type":"object","required":["all_data","filter_data"],"properties":{"all_data":{"$ref":"#/components/schemas/DataPage","description":"Unfiltered items from the stable dataset snapshot."},"filter_data":{"$ref":"#/components/schemas/DataPage","description":"Items from the same snapshot after request filters and endpoint defaults are applied."}}},"DualDataResponse":{"type":"object","required":["data","meta","credits"],"properties":{"data":{"$ref":"#/components/schemas/DualData"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"},"snapshot_id":{"type":"string"},"snapshot_at":{"type":"string","format":"date-time"},"data_status":{"type":"string"},"methodology_version":{"type":"string"}}},"credits":{"type":"object","required":["cost","remaining","period_ends_at"],"properties":{"cost":{"type":"integer"},"remaining":{"type":"integer"},"period_ends_at":{"type":"string","format":"date-time"}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","details"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","INVALID_API_KEY","SUBSCRIPTION_REQUIRED","CREDITS_EXHAUSTED","INSUFFICIENT_SCOPE","ACCOUNT_DISABLED","RESOURCE_NOT_FOUND","IDEMPOTENCY_CONFLICT","CURSOR_EXPIRED","RATE_LIMITED","INTERNAL_ERROR","SERVICE_UNAVAILABLE","DATA_STALE","KEY_LIMIT_REACHED","KEY_NOT_FOUND","BUDGET_EXHAUSTED"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}},"paths":{"/auth/verify":{"get":{"operationId":"verifyApiKey","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Verified"}}}},"/credits":{"get":{"operationId":"getCreditBalance","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Balance"}}}},"/credits/costs":{"get":{"operationId":"getOperationCosts","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Costs"}}}},"/rankings/chinese-low-subscriber-long-videos":{"get":{"operationId":"getChineseLowSubscriberLongVideos","security":[{"bearerAuth":[]}],"description":"Filter by either period or the inclusive UTC start_date/end_date pair. Date filters apply to video published_at values in the current stable snapshot.","parameters":[{"name":"period","in":"query","description":"Preset publication window. Cannot be combined with start_date or end_date; defaults to today when no custom range is supplied.","schema":{"type":"string","enum":["today","7d","all_time"]}},{"name":"start_date","in":"query","description":"Inclusive UTC publication start date. Required together with end_date.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"end_date","in":"query","description":"Inclusive UTC publication end date. Required together with start_date.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"track","in":"query","schema":{"type":"string","default":"all"}},{"name":"quality","in":"query","schema":{"type":"string","enum":["strict","all"],"default":"strict"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"all_cursor","in":"query","description":"Cursor returned by data.all_data.next_cursor.","schema":{"type":"string"}},{"name":"filter_cursor","in":"query","description":"Cursor returned by data.filter_data.next_cursor.","schema":{"type":"string"}},{"name":"cursor","in":"query","deprecated":true,"description":"Legacy alias for filter_cursor. Do not send both.","schema":{"type":"string"}}],"responses":{"200":{"description":"Unfiltered and filtered results from one stable snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DualDataResponse"}}}},"304":{"description":"Not modified; zero credits"}}}},"/rankings/hot-today":{"get":{"operationId":"getHotToday","security":[{"bearerAuth":[]}],"parameters":[{"name":"region","in":"query","schema":{"type":"string"}},{"name":"tier","in":"query","schema":{"type":"string","enum":["S","A","B","C","all"],"default":"all"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"all_cursor","in":"query","description":"Cursor returned by data.all_data.next_cursor.","schema":{"type":"string"}},{"name":"filter_cursor","in":"query","description":"Cursor returned by data.filter_data.next_cursor.","schema":{"type":"string"}},{"name":"cursor","in":"query","deprecated":true,"description":"Legacy alias for filter_cursor. Do not send both.","schema":{"type":"string"}}],"responses":{"200":{"description":"Unfiltered and filtered results from one stable snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DualDataResponse"}}}}}}},"/videos/outliers/search":{"post":{"operationId":"searchOutlierVideos","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string"},"niche":{"type":"string"},"video_type":{"type":"string","enum":["shorts","long","all"],"default":"all"},"region":{"type":"string"},"max_channel_subscribers":{"type":"integer"},"min_views":{"type":"integer"},"min_vs_ratio":{"type":"number","default":10},"time_window":{"type":"string","enum":["24h","3d","7d","30d"],"default":"7d"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20},"all_cursor":{"type":"string"},"filter_cursor":{"type":"string"},"cursor":{"type":"string","deprecated":true,"description":"Legacy alias for filter_cursor. Do not send both."}}}}}},"responses":{"200":{"description":"Unfiltered and filtered results from one stable snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DualDataResponse"}}}}}}},"/videos/{video_id}":{"get":{"operationId":"getVideoDetail","security":[{"bearerAuth":[]}],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Unfiltered and filtered results from one stable snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DualDataResponse"}}}},"404":{"description":"Not found; zero credits"}}}}}}