{"openapi":"3.0.3","info":{"title":"Twitter / X Scraping Backend Gateway API","version":"1.0.0","description":"Cloudflare Worker API Gateway providing complete Twitter/X scraping endpoints (profiles, tweets, media, replies, universal search, user search, advanced filters, and lists) powered by Apify Actors."},"servers":[{"url":"https://twitter-api.mikolabs.xyz","description":"Current Worker Host"}],"components":{"securitySchemes":{"XBaseAuthToken":{"type":"apiKey","in":"header","name":"X-Base-Auth-Token","description":"Twitter / X Base Auth Token cookie or gateway API token (also accepts X-Auth-Token or Authorization: Bearer <token>)"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Platform API Key"},"ApifyTokenAuth":{"type":"apiKey","in":"header","name":"X-Apify-Token","description":"Apify API token override"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Token","description":"Standard Bearer authorization header"}}},"paths":{"/scrape":{"post":{"summary":"Unified Multi-Target Scrape (JSON Body)","tags":["Unified Scraper"],"description":"Accepts handles, search terms, list URLs, date filters, engagement metrics, media flags, and returns canonical items.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"twitterHandles":{"type":"array","items":{"type":"string"},"example":["elonmusk","OpenAI"]},"searchTerms":{"type":"array","items":{"type":"string"},"example":["AI breakthrough","#python"]},"listUrls":{"type":"array","items":{"type":"string"},"example":["https://x.com/i/lists/78783491"]},"searchType":{"type":"string","enum":["tweets","users","profile_tweets"],"default":"tweets"},"maxItems":{"type":"integer","default":20},"includeReplies":{"type":"boolean","default":false},"includeRetweets":{"type":"boolean","default":true},"mediaOnly":{"type":"boolean","default":false},"scrapeProfileInfo":{"type":"boolean","default":true},"startDate":{"type":"string","example":"2024-01-01"},"endDate":{"type":"string","example":"2024-12-31"},"location":{"type":"string","example":"San Francisco"},"latestTweets":{"type":"boolean","default":false},"onlyImages":{"type":"boolean","default":false},"onlyVideos":{"type":"boolean","default":false},"onlyVerified":{"type":"boolean","default":false},"minLikes":{"type":"integer","default":0},"minRetweets":{"type":"integer","default":0},"minReplies":{"type":"integer","default":0},"tweetLanguage":{"type":"string","example":"en"}}}}}},"responses":{"200":{"description":"Unified multi-target scrape response"},"400":{"description":"Missing targets"}}},"get":{"summary":"Unified Multi-Target Scrape (Query String)","tags":["Unified Scraper"],"parameters":[{"name":"handles","in":"query","schema":{"type":"string"},"description":"Comma-separated handles"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Comma-separated search terms"},{"name":"lists","in":"query","schema":{"type":"string"},"description":"Comma-separated list URLs or IDs"},{"name":"maxItems","in":"query","schema":{"type":"integer","default":20}},{"name":"type","in":"query","schema":{"type":"string","enum":["tweets","users","profile_tweets"]}},{"name":"lang","in":"query","schema":{"type":"string"}},{"name":"minLikes","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Unified results"}}}},"/search":{"get":{"summary":"Quick Tweet or User Search","tags":["Unified Scraper"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["tweets","users"],"default":"tweets"}},{"name":"max","in":"query","schema":{"type":"integer","default":20}},{"name":"lang","in":"query","schema":{"type":"string"}},{"name":"minLikes","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Search items"}}}},"/profile/{username}/search":{"get":{"summary":"Search Within Profile","tags":["Unified Scraper"],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"max","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Tweets from user matching query"}}}},"/users":{"get":{"summary":"User Account Search","tags":["Unified Scraper"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"max","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Matched user accounts"}}}},"/list/{list_id}":{"get":{"summary":"Twitter List Extraction","tags":["Unified Scraper"],"parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"max","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List items"}}}},"/health":{"get":{"summary":"System Health Check","tags":["System"],"responses":{"200":{"description":"Health status"}}}},"/api/profile/{username}":{"get":{"summary":"Scrape Twitter/X Profile","tags":["Profile"],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"},"description":"Twitter username (without @)"},{"name":"token","in":"query","required":false,"schema":{"type":"string"},"description":"Optional Apify token override"}],"responses":{"200":{"description":"Profile details scraped successfully"},"500":{"description":"Apify or network error"}}}},"/api/profile/{username}/tweets":{"get":{"summary":"Get User Tweets","tags":["Tweets"],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"maxItems","in":"query","schema":{"type":"integer","default":50}},{"name":"includeReplies","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"User tweets list"}}}},"/api/search/tweets":{"get":{"summary":"Search Tweets Globally","tags":["Search"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"}},{"name":"queryType","in":"query","schema":{"type":"string","enum":["Latest","Top"],"default":"Latest"}},{"name":"maxItems","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Search results"}}}},"/api/search/advanced":{"post":{"summary":"Advanced Twitter Search","tags":["Advanced Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"numberOfTweets":{"type":"integer","default":50},"contentKeywords":{"type":"array","items":{"type":"string"}},"usersFromUsers":{"type":"array","items":{"type":"string"}},"mediaTypes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Advanced search results"}}}}}}