{"openapi":"3.1.0","info":{"title":"Twitch (BYOK) API","version":"0.1.0","description":"Twitch (BYOK) lets an AI assistant read your own Twitch data through the Twitch API with a key you supply (app or user access token). Read-only: 10 tools (get_users, get_streams, get_top_games, get_game, get_channel, search_channels, search_categories, list_broadcaster_clips, list_game_clips, list_videos). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-twitch.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-twitch/docs"},"termsOfService":"https://connectorbay.com/byok-twitch/terms"},"servers":[{"url":"https://byok-twitch.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-twitch/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_users":{"post":{"operationId":"get_users","summary":"Look up a Twitch user by login name or user id: display name, broadcaster type, description, profile image and account c","description":"Look up a Twitch user by login name or user id: display name, broadcaster type, description, profile image and account creation date. With neither parameter and a user access token, returns the token's own user. Use for \"Who is the Twitch user twitchdev\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"login":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Login name of one user, for example 'twitchdev'.","title":"Login"},"id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Numeric user id of one user, for example '141981764'.","title":"Id"}},"title":"get_usersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_streams":{"post":{"operationId":"get_streams","summary":"List live Twitch streams, most viewers first, optionally filtered by one user, one game id or one language: title, game,","description":"List live Twitch streams, most viewers first, optionally filtered by one user, one game id or one language: title, game, viewer count, start time. Use for \"Which Twitch streams are live right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_login":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only the stream of this login name (empty result when offline).","title":"User Login"},"user_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only the stream of this numeric user id.","title":"User Id"},"game_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only streams in this game or category id (see search_categories or get_top_games).","title":"Game Id"},"language":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Only streams in this ISO 639-1 language code, for example 'en' or 'de'; 'other' for unsupported languages.","title":"Language"},"first":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"First"},"after":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination.cursor value of the previous answer, to get the next page.","title":"After"}},"title":"get_streamsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_top_games":{"post":{"operationId":"get_top_games","summary":"List the games and categories with the most viewers on Twitch right now, with id, name and IGDB id. Use for \"What are th","description":"List the games and categories with the most viewers on Twitch right now, with id, name and IGDB id. Use for \"What are the top games on Twitch right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"first":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"First"},"after":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination.cursor value of the previous answer, to get the next page.","title":"After"}},"title":"get_top_gamesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_game":{"post":{"operationId":"get_game","summary":"Look up one game or category by exact name, Twitch id or IGDB id: returns id, name, IGDB id and box art URL template. Gi","description":"Look up one game or category by exact name, Twitch id or IGDB id: returns id, name, IGDB id and box art URL template. Give exactly one of name, id or igdb_id. Use for \"What is the Twitch id of the game Fortnite\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Exact name of the game or category, for example 'Fortnite'.","title":"Name"},"id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Twitch id of the game or category.","title":"Id"},"igdb_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"IGDB id of the game.","title":"Igdb Id"}},"title":"get_gameArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_channel":{"post":{"operationId":"get_channel","summary":"Get a channel's current settings by broadcaster id: stream title, game, language, tags, delay and branded-content flag. ","description":"Get a channel's current settings by broadcaster id: stream title, game, language, tags, delay and branded-content flag. Use for \"What is the stream title and game of Twitch channel 141981764\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"broadcaster_id":{"description":"Numeric id of the broadcaster (a user id from get_users).","maxLength":20,"title":"Broadcaster Id","type":"string"}},"required":["broadcaster_id"],"title":"get_channelArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_channels":{"post":{"operationId":"search_channels","summary":"Search Twitch channels by name (prefix match) that streamed in the past 6 months; set live_only to see only channels liv","description":"Search Twitch channels by name (prefix match) that streamed in the past 6 months; set live_only to see only channels live now. Use for \"Find Twitch channels named like 'speedrun'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Text to match at the start of the channel name or category, for example 'speedrun'.","maxLength":100,"title":"Query","type":"string"},"live_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return only channels that are live now.","title":"Live Only"},"first":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"First"},"after":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination.cursor value of the previous answer, to get the next page.","title":"After"}},"required":["query"],"title":"search_channelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_categories":{"post":{"operationId":"search_categories","summary":"Search Twitch games and categories by name; returns id and name. Use the id with get_streams or the clip tools. Use for ","description":"Search Twitch games and categories by name; returns id and name. Use the id with get_streams or the clip tools. Use for \"Find the Twitch category id for Minecraft\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Words contained in the category name, for example 'minecraft'.","maxLength":100,"title":"Query","type":"string"},"first":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"First"},"after":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination.cursor value of the previous answer, to get the next page.","title":"After"}},"required":["query"],"title":"search_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_broadcaster_clips":{"post":{"operationId":"list_broadcaster_clips","summary":"List clips captured from one broadcaster's streams, most viewed first, optionally within a start and end time (RFC 3339)","description":"List clips captured from one broadcaster's streams, most viewed first, optionally within a start and end time (RFC 3339). At most about 1000 clips can be paged. Use for \"What are the most viewed Twitch clips of broadcaster 141981764\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"broadcaster_id":{"description":"Numeric id of the broadcaster whose clips to list.","maxLength":20,"title":"Broadcaster Id","type":"string"},"started_at":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only clips created after this time, RFC 3339, for example 2026-10-01T00:00:00Z.","title":"Started At"},"ended_at":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only clips created before this time, RFC 3339 (default: one week after started_at).","title":"Ended At"},"is_featured":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for featured clips only, false for non-featured only; omit for all.","title":"Is Featured"},"first":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"First"},"after":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination.cursor value of the previous answer, to get the next page.","title":"After"}},"required":["broadcaster_id"],"title":"list_broadcaster_clipsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_game_clips":{"post":{"operationId":"list_game_clips","summary":"List clips captured while a game or category was being streamed, most viewed first, optionally within a start and end ti","description":"List clips captured while a game or category was being streamed, most viewed first, optionally within a start and end time (RFC 3339). Use for \"What are the top Twitch clips for game 509658 this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"game_id":{"description":"Twitch id of the game or category whose clips to list.","maxLength":20,"title":"Game Id","type":"string"},"started_at":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only clips created after this time, RFC 3339, for example 2026-10-01T00:00:00Z.","title":"Started At"},"ended_at":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only clips created before this time, RFC 3339 (default: one week after started_at).","title":"Ended At"},"first":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"First"},"after":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination.cursor value of the previous answer, to get the next page.","title":"After"}},"required":["game_id"],"title":"list_game_clipsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_videos":{"post":{"operationId":"list_videos","summary":"List a broadcaster's published videos (past broadcasts, highlights, uploads) with title, duration, view count and dates.","description":"List a broadcaster's published videos (past broadcasts, highlights, uploads) with title, duration, view count and dates. Use for \"What are the latest videos of Twitch user 141981764\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"description":"Numeric id of the broadcaster.","maxLength":20,"title":"User Id","type":"string"},"type":{"anyOf":[{"enum":["all","archive","highlight","upload"],"type":"string"},{"type":"null"}],"default":"all","description":"Kind of video: all, archive (past broadcasts), highlight or upload.","title":"Type"},"sort":{"anyOf":[{"enum":["time","trending","views"],"type":"string"},{"type":"null"}],"default":"time","description":"Order: time (newest first), trending or views.","title":"Sort"},"period":{"anyOf":[{"enum":["all","day","week","month"],"type":"string"},{"type":"null"}],"default":"all","description":"Published within: all, day, week or month.","title":"Period"},"first":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"First"},"after":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination.cursor value of the previous answer, to get the next page.","title":"After"}},"required":["user_id"],"title":"list_videosArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}