{"openapi":"3.1.0","info":{"title":"Watchmode (BYOK) API","version":"0.1.0","description":"Watchmode (BYOK) lets an AI assistant read your own Watchmode data through the Watchmode API with a key you supply (Watchmode API key). Read-only: 11 tools (search_titles, get_title_details, get_title_sources, list_titles, list_title_seasons, list_title_episodes, get_title_cast_crew, get_person, list_sources, list_releases, get_quota_status). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-watchmode.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-watchmode/docs"},"termsOfService":"https://connectorbay.com/byok-watchmode/terms"},"servers":[{"url":"https://byok-watchmode.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-watchmode/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/search_titles":{"post":{"operationId":"search_titles","summary":"Search titles (and people) by name or by IMDb or TMDB ID. Costs 1 credit of the plan's monthly quota. Use for \"Find Brea","description":"Search titles (and people) by name or by IMDb or TMDB ID. Costs 1 credit of the plan's monthly quota. Use for \"Find Breaking Bad on Watchmode\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_field":{"description":"What to search: name, imdb_id, tmdb_movie_id, tmdb_tv_id or tmdb_person_id.","enum":["name","imdb_id","tmdb_movie_id","tmdb_tv_id","tmdb_person_id"],"title":"Search Field","type":"string"},"search_value":{"description":"The name or ID to search for, for example 'Breaking Bad' or 'tt0903747'.","maxLength":200,"title":"Search Value","type":"string"},"types":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated result types to keep: movie, tv, person.","title":"Types"}},"required":["search_field","search_value"],"title":"search_titlesArguments","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_title_details":{"post":{"operationId":"get_title_details","summary":"Get a movie or TV show's details: plot, year, runtime, genres, ratings, critic score, US rating, networks, poster, trail","description":"Get a movie or TV show's details: plot, year, runtime, genres, ratings, critic score, US rating, networks, poster, trailer and similar title IDs. Costs 1 credit by Watchmode ID. Use for \"Give me the details of Breaking Bad on Watchmode\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title_id":{"description":"Watchmode title ID (1 credit). IMDb IDs such as tt0903747 or TMDB forms such as tv-1396 or movie-278 also work but cost 2 credits.","maxLength":20,"title":"Title Id","type":"string"},"language":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"ISO 639-1 language code for localized text (default en).","title":"Language"}},"required":["title_id"],"title":"get_title_detailsArguments","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_title_sources":{"post":{"operationId":"get_title_sources","summary":"List where a title can be streamed, rented or bought, with service, type (sub, rent, buy, free), region, price, quality ","description":"List where a title can be streamed, rented or bought, with service, type (sub, rent, buy, free), region, price, quality and web link. Costs 1 credit by Watchmode ID. Use for \"Where can I stream Breaking Bad in the US\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title_id":{"description":"Watchmode title ID (1 credit). IMDb IDs such as tt0903747 or TMDB forms such as tv-1396 or movie-278 also work but cost 2 credits.","maxLength":20,"title":"Title Id","type":"string"},"regions":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated two-letter country codes, for example 'US,GB'; must be enabled on your plan (default: your plan's regions).","title":"Regions"}},"required":["title_id"],"title":"get_title_sourcesArguments","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_titles":{"post":{"operationId":"list_titles","summary":"List titles with filters: type, genre IDs, streaming service IDs, source type, regions, release dates, ratings and sort ","description":"List titles with filters: type, genre IDs, streaming service IDs, source type, regions, release dates, ratings and sort order. Costs 1 credit per region per page. Use for \"Which highly rated horror movies stream for free in the US\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"types":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated: movie, tv_series, tv_movie, tv_special, tv_miniseries, short_film.","title":"Types"},"genres":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated genre IDs (see list_genres).","title":"Genres"},"source_ids":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated service IDs (see list_sources).","title":"Source Ids"},"source_types":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated: sub, rent, buy, free, tve.","title":"Source Types"},"regions":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated two-letter country codes, for example 'US,GB'; must be enabled on your plan (default: your plan's regions).","title":"Regions"},"release_date_start":{"anyOf":[{"maximum":21001231,"minimum":19000101,"type":"integer"},{"type":"null"}],"default":null,"description":"Earliest release date as YYYYMMDD.","title":"Release Date Start"},"release_date_end":{"anyOf":[{"maximum":21001231,"minimum":19000101,"type":"integer"},{"type":"null"}],"default":null,"description":"Latest release date as YYYYMMDD.","title":"Release Date End"},"user_rating_low":{"anyOf":[{"maximum":10,"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Minimum user rating (0 to 10).","title":"User Rating Low"},"critic_score_low":{"anyOf":[{"maximum":100,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum critic score (0 to 100).","title":"Critic Score Low"},"sort_by":{"anyOf":[{"enum":["relevance_desc","relevance_asc","popularity_desc","popularity_asc","release_date_desc","release_date_asc","title_desc","title_asc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order of results.","title":"Sort By"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number.","title":"Page"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (1 to 250).","title":"Limit"}},"title":"list_titlesArguments","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_title_seasons":{"post":{"operationId":"list_title_seasons","summary":"List the seasons of a TV series with name, number, air date and episode count. Costs 1 credit by Watchmode ID. Use for \"","description":"List the seasons of a TV series with name, number, air date and episode count. Costs 1 credit by Watchmode ID. Use for \"How many seasons does Breaking Bad have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title_id":{"description":"Watchmode title ID (1 credit). IMDb IDs such as tt0903747 or TMDB forms such as tv-1396 or movie-278 also work but cost 2 credits.","maxLength":20,"title":"Title Id","type":"string"}},"required":["title_id"],"title":"list_title_seasonsArguments","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_title_episodes":{"post":{"operationId":"list_title_episodes","summary":"List episodes of a TV series with number, release date, runtime and overview; streaming sources are left out unless requ","description":"List episodes of a TV series with number, release date, runtime and overview; streaming sources are left out unless requested. Costs 1 credit by Watchmode ID. Use for \"List the episodes of season 1 of Breaking Bad\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title_id":{"description":"Watchmode title ID (1 credit). IMDb IDs such as tt0903747 or TMDB forms such as tv-1396 or movie-278 also work but cost 2 credits.","maxLength":20,"title":"Title Id","type":"string"},"season":{"anyOf":[{"maximum":500,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only episodes of this season number.","title":"Season"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum number of episodes.","title":"Limit"},"include_sources":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to add streaming sources to each episode (larger answer).","title":"Include Sources"},"regions":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated two-letter country codes, for example 'US,GB'; must be enabled on your plan (default: your plan's regions).","title":"Regions"}},"required":["title_id"],"title":"list_title_episodesArguments","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_title_cast_crew":{"post":{"operationId":"get_title_cast_crew","summary":"List the cast and crew of a title with person IDs, role and billing order. Costs 1 credit by Watchmode ID. Use for \"Who ","description":"List the cast and crew of a title with person IDs, role and billing order. Costs 1 credit by Watchmode ID. Use for \"Who is in the cast of Breaking Bad\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title_id":{"description":"Watchmode title ID (1 credit). IMDb IDs such as tt0903747 or TMDB forms such as tv-1396 or movie-278 also work but cost 2 credits.","maxLength":20,"title":"Title Id","type":"string"},"language":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"ISO 639-1 language code for localized text (default en).","title":"Language"}},"required":["title_id"],"title":"get_title_cast_crewArguments","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_person":{"post":{"operationId":"get_person","summary":"Get a person's profile by Watchmode person ID: name, professions, birth data, biography and the title IDs they are known","description":"Get a person's profile by Watchmode person ID: name, professions, birth data, biography and the title IDs they are known for. Costs 1 credit. Use for \"Who is the person with Watchmode ID 7110004\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"person_id":{"description":"Watchmode person ID (starts with 7), for example 7110004.","maximum":9999999999,"minimum":1,"title":"Person Id","type":"integer"},"language":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"ISO 639-1 language code for localized text (default en).","title":"Language"}},"required":["person_id"],"title":"get_personArguments","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_sources":{"post":{"operationId":"list_sources","summary":"List the streaming, rental and free services Watchmode tracks, with service IDs, type and countries. Costs 1 credit. Use","description":"List the streaming, rental and free services Watchmode tracks, with service IDs, type and countries. Costs 1 credit. Use for \"Which streaming services does Watchmode cover in the US\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"regions":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated two-letter country codes, for example 'US,GB'; must be enabled on your plan (default: your plan's regions).","title":"Regions"},"types":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated: sub, purchase, free, tve.","title":"Types"}},"title":"list_sourcesArguments","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_releases":{"post":{"operationId":"list_releases","summary":"List recent and upcoming streaming releases by date window, with service and release date. Costs 1 credit per page. Use ","description":"List recent and upcoming streaming releases by date window, with service and release date. Costs 1 credit per page. Use for \"What new shows are arriving on streaming services this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maximum":21001231,"minimum":19000101,"type":"integer"},{"type":"null"}],"default":null,"description":"Releases after this date, YYYYMMDD (default 30 days ago).","title":"Start Date"},"end_date":{"anyOf":[{"maximum":21001231,"minimum":19000101,"type":"integer"},{"type":"null"}],"default":null,"description":"Releases before this date, YYYYMMDD (default 30 days ahead).","title":"End Date"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Number of results (1 to 250).","title":"Limit"}},"title":"list_releasesArguments","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_quota_status":{"post":{"operationId":"get_quota_status","summary":"Show how much of the key's monthly Watchmode quota has been used. Costs 0 credits. Use for \"How many Watchmode credits h","description":"Show how much of the key's monthly Watchmode quota has been used. Costs 0 credits. Use for \"How many Watchmode credits have I used this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_quota_statusArguments","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}}}}