{"openapi":"3.1.0","info":{"title":"GoonAPI","version":"1.0.0","description":"Video search, listings, playable streams and thumbnails for tube sites, aggregated across sources. Authenticate every request with your website's API key."},"servers":[{"url":"https://api.xxxgoon.com"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Videos","description":"Browse, search, inspect and play videos."},{"name":"Discovery","description":"Suggestions, categories, tags and sources."},{"name":"Account","description":"Your API key."}],"paths":{"/v1/videos":{"get":{"operationId":"listVideos","tags":["Videos"],"summary":"List or search videos","description":"Videos merged from every available source, interleaved so no single source dominates. Without `q` this is a browse feed; with `q` it is a search. A curated category name (see /v1/categories) as `q` returns each source's own category feed.","parameters":[{"name":"q","in":"query","required":false,"description":"Search words, a tag, a performer or a category. Up to 100 characters.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number, starting at 1.","schema":{"type":"integer","minimum":1,"maximum":100,"default":1}},{"name":"sort","in":"query","required":false,"description":"Ordering, applied within each source before sources are interleaved. `trending` is most viewed this week, `month` most viewed this month. With `new`, add `quality_filter=0`: brand-new videos have few views and are otherwise filtered out.","schema":{"type":"string","enum":["popular","trending","month","rated","new","longest"],"default":"popular"}},{"name":"duration","in":"query","required":false,"description":"Length bucket: `short` under 10 minutes, `medium` 10 to 30, `long` over 30.","schema":{"type":"string","enum":["short","medium","long"]}},{"name":"sources","in":"query","required":false,"description":"Comma-separated source names to restrict to, e.g. `xvideos,eporner`. Default: all.","schema":{"type":"string"}},{"name":"min_height","in":"query","required":false,"description":"Only videos whose listing advertises at least this resolution. Few sources report resolution in listings (mainly xvideos), so this narrows results to those sources; the streams endpoint gives every video's real qualities.","schema":{"type":"integer","enum":[720,1080,2160]}},{"name":"quality_filter","in":"query","required":false,"description":"Set to `0` to keep low-rated and very short clips, which are dropped by default.","schema":{"type":"string","enum":["0","1"],"default":"1"}},{"name":"limit","in":"query","required":false,"description":"Trim the page to this many videos. A page is a merge across sources, so its natural size varies (typically 300 to 500).","schema":{"type":"integer","minimum":1,"maximum":250}},{"name":"include","in":"query","required":false,"description":"Set to `frames` to add hover frames where the source supplies them (few do).","schema":{"type":"string","enum":["frames"]}}],"x-sample-query":"?q=amateur&sort=popular&page=1","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"page":{"type":"integer","description":"The page returned."},"count":{"type":"integer","description":"Number of videos in data."},"next_page":{"type":["integer","null"],"description":"Page to request next, or null when there are no more results."}}},"example":{"data":[{"id":"eHZpZGVvczprZmJhbzEyMzQ","source":"xvideos","title":"Example video title","duration":754,"thumbnail":"https://cdn.example-source.com/thumbs/12/34/poster.jpg","thumbnail_proxy":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fthumbs%2F12%2F34%2Fposter.jpg","preview":"https://cdn.example-source.com/previews/12/34/preview.mp4","preview_proxy":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fpreviews%2F12%2F34%2Fpreview.mp4","views":1280455,"rating":4.6,"height":1080,"channel":"Example Channel","published_at":"2026-09-14T00:00:00.000Z","tags":["example","hd"],"source_url":"https://www.example-source.com/video.kfbao1234/example_video_title"}],"page":1,"count":1,"next_page":2}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}}}}},"/v1/videos/trending":{"get":{"operationId":"trendingVideos","tags":["Videos"],"summary":"Trending videos","description":"The past week's most watched videos across sources. Good for a homepage.","parameters":[{"name":"limit","in":"query","required":false,"description":"How many videos.","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}},{"name":"include","in":"query","required":false,"description":"Set to `frames` to add hover frames where the source supplies them (few do).","schema":{"type":"string","enum":["frames"]}}],"x-sample-query":"?limit=24","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"count":{"type":"integer","description":"Number of videos in data."}}},"example":{"data":[{"id":"eHZpZGVvczprZmJhbzEyMzQ","source":"xvideos","title":"Example video title","duration":754,"thumbnail":"https://cdn.example-source.com/thumbs/12/34/poster.jpg","thumbnail_proxy":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fthumbs%2F12%2F34%2Fposter.jpg","preview":"https://cdn.example-source.com/previews/12/34/preview.mp4","preview_proxy":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fpreviews%2F12%2F34%2Fpreview.mp4","views":1280455,"rating":4.6,"height":1080,"channel":"Example Channel","published_at":"2026-09-14T00:00:00.000Z","tags":["example","hd"],"source_url":"https://www.example-source.com/video.kfbao1234/example_video_title"}],"count":1}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}}}}},"/v1/videos/{id}":{"get":{"operationId":"getVideo","tags":["Videos"],"summary":"Video detail","description":"Everything known about one video. Tags, description, hover frames and the seek-preview storyboard are included when the source provides them.","parameters":[{"name":"id","in":"path","required":true,"description":"A video id from any listing.","schema":{"type":"string"}}],"x-sample-query":"","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VideoDetail"}}},"example":{"data":{"id":"eHZpZGVvczprZmJhbzEyMzQ","source":"xvideos","title":"Example video title","duration":754,"thumbnail":"https://cdn.example-source.com/thumbs/12/34/poster.jpg","thumbnail_proxy":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fthumbs%2F12%2F34%2Fposter.jpg","preview":"https://cdn.example-source.com/previews/12/34/preview.mp4","preview_proxy":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fpreviews%2F12%2F34%2Fpreview.mp4","views":1280455,"rating":4.6,"height":1080,"channel":"Example Channel","published_at":"2026-09-14T00:00:00.000Z","tags":["example","hd"],"source_url":"https://www.example-source.com/video.kfbao1234/example_video_title","frames":[],"description":"Uploader's description of the video.","storyboard":null}}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"404":{"description":"No video has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"video_not_found","message":"No video with this id."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}}}}},"/v1/videos/{id}/streams":{"get":{"operationId":"getStreams","tags":["Videos"],"summary":"Playable streams","description":"The video's playable quality variants, best first. URLs are signed by the source and expire, so call this when the viewer presses play rather than when you render the page, and do not store the result.","parameters":[{"name":"id","in":"path","required":true,"description":"A video id from any listing.","schema":{"type":"string"}}],"x-sample-query":"","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Stream"}},"expires_in":{"type":"integer","description":"Seconds the URLs can be relied on."}}},"example":{"data":[{"label":"1080p","format":"mp4","height":1080,"url":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fv%2F1080.mp4%3Ftoken%3D..."},{"label":"720p","format":"mp4","height":720,"url":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fv%2F720.mp4%3Ftoken%3D..."},{"label":"Auto","format":"hls","height":1080,"url":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fv%2Fmaster.m3u8%3Ftoken%3D..."}],"expires_in":300}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"404":{"description":"No video has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"video_not_found","message":"No video with this id."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}},"502":{"description":"The source returned no playable streams right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"streams_unavailable","message":"The source returned no playable streams. Try again shortly."}}}}}}}},"/v1/videos/{id}/related":{"get":{"operationId":"relatedVideos","tags":["Videos"],"summary":"Related videos","description":"Videos sharing this one's performer or strongest tag, topped up with highly rated videos.","parameters":[{"name":"id","in":"path","required":true,"description":"A video id from any listing.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many videos.","schema":{"type":"integer","minimum":1,"maximum":48,"default":12}}],"x-sample-query":"?limit=12","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"count":{"type":"integer","description":"Number of videos in data."}}},"example":{"data":[{"id":"eHZpZGVvczprZmJhbzEyMzQ","source":"xvideos","title":"Example video title","duration":754,"thumbnail":"https://cdn.example-source.com/thumbs/12/34/poster.jpg","thumbnail_proxy":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fthumbs%2F12%2F34%2Fposter.jpg","preview":"https://cdn.example-source.com/previews/12/34/preview.mp4","preview_proxy":"https://stream.example.com/?src=https%3A%2F%2Fcdn.example-source.com%2Fpreviews%2F12%2F34%2Fpreview.mp4","views":1280455,"rating":4.6,"height":1080,"channel":"Example Channel","published_at":"2026-09-14T00:00:00.000Z","tags":["example","hd"],"source_url":"https://www.example-source.com/video.kfbao1234/example_video_title"}],"count":1}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"404":{"description":"No video has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"video_not_found","message":"No video with this id."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}}}}},"/v1/suggest":{"get":{"operationId":"suggest","tags":["Discovery"],"summary":"Search suggestions","description":"Up to six completions for a partial search, for an autocomplete box. Empty for input under two characters.","parameters":[{"name":"q","in":"query","required":true,"description":"What the visitor has typed so far.","schema":{"type":"string","minLength":2,"maxLength":40}}],"x-sample-query":"?q=ama","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"string"}}}},"example":{"data":["example search","example search hd"]}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}}}}},"/v1/categories":{"get":{"operationId":"listCategories","tags":["Discovery"],"summary":"Categories","description":"Curated category names. Pass one as `q` to /v1/videos.","parameters":[],"x-sample-query":"","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"string"}}}},"example":{"data":["amateur","pov","threesome"]}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}}}}},"/v1/tags/trending":{"get":{"operationId":"trendingTags","tags":["Discovery"],"summary":"Trending tags","description":"The tags most common among this week's trending videos.","parameters":[{"name":"limit","in":"query","required":false,"description":"How many tags.","schema":{"type":"integer","minimum":1,"maximum":30,"default":10}}],"x-sample-query":"?limit=10","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"string"}}}},"example":{"data":["example","hd"]}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}}}}},"/v1/sources":{"get":{"operationId":"listSources","tags":["Discovery"],"summary":"Sources","description":"Every source the API aggregates and whether it is currently playable. Unavailable sources are left out of listings until they recover.","parameters":[],"x-sample-query":"","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"available":{"type":"boolean"}}}}}},"example":{"data":[{"name":"xvideos","available":true},{"name":"eporner","available":true}]}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}}}}},"/v1/me":{"get":{"operationId":"whoAmI","tags":["Account"],"summary":"Your key","description":"The website this key belongs to and its rate limit. A quick way to check a key works.","parameters":[],"x-sample-query":"","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":["string","null"]},"rate_limit_per_minute":{"type":"integer"}}}}},"example":{"data":{"name":"Example Tube","domain":"example.com","rate_limit_per_minute":120}}}}},"401":{"description":"The key is missing or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"This API key is not recognised."}}}}},"403":{"description":"The key has been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"key_revoked","message":"This API key has been revoked."}}}}},"429":{"description":"Your per-minute rate limit is used up. See the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit of 120 requests per minute exceeded."}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer <your key>"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Video":{"type":"object","required":["id","source","title","duration","tags"],"properties":{"id":{"type":"string","description":"Stable, URL-safe video id. Use it in the other video endpoints."},"source":{"type":"string","description":"Which source the video comes from (see /v1/sources)."},"title":{"type":"string"},"duration":{"type":"integer","description":"Length in seconds. 0 when the source did not say."},"thumbnail":{"type":["string","null"],"description":"Thumbnail on the source's CDN. Costs nothing to serve; if a CDN refuses the hotlink, fall back to thumbnail_proxy."},"thumbnail_proxy":{"type":["string","null"],"description":"The same thumbnail through GoonAPI's edge relay, cached at the edge. Always embeddable."},"preview":{"type":["string","null"],"description":"Short muted preview clip on the source's CDN, when the source has one."},"preview_proxy":{"type":["string","null"],"description":"The preview clip through GoonAPI's edge relay."},"views":{"type":["integer","null"],"description":"View count at the source."},"rating":{"type":["number","null"],"description":"Source rating, 0 to 5."},"height":{"type":["integer","null"],"description":"Best resolution the listing advertises, e.g. 1080."},"channel":{"type":["string","null"],"description":"Uploader or channel name."},"published_at":{"type":["string","null"],"description":"When the source published it.","format":"date-time"},"tags":{"type":"array","items":{"type":"string"}},"source_url":{"type":["string","null"],"description":"The video's page on the source site."},"frames":{"type":"array","items":{"type":"string"},"description":"Still frames to cycle through on hover. Returned with include=frames and on the detail endpoint; only a few sources supply them, so expect an empty list for most videos and prefer preview_proxy."}}},"VideoDetail":{"allOf":[{"$ref":"#/components/schemas/Video"},{"type":"object","properties":{"description":{"type":["string","null"],"description":"Uploader's description."},"storyboard":{"type":["string","null"],"description":"WebVTT thumbnail-sprite track for seek previews, when available."}}}]},"Stream":{"type":"object","required":["label","format","url"],"properties":{"label":{"type":"string","description":"Human label for a quality menu: \"1080p\", \"720p\", \"Auto\"."},"format":{"type":"string","enum":["mp4","hls"],"description":"mp4 plays in a <video> tag directly; hls needs hls.js outside Safari."},"height":{"type":["integer","null"],"description":"Vertical resolution, when known."},"url":{"type":"string","description":"Playable URL with CORS and Range support. Short-lived: request streams when playback starts."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. invalid_api_key."},"message":{"type":"string","description":"Human-readable explanation."}}}}}}}}