{"openapi":"3.1.0","info":{"title":"MDBList (BYOK) API","version":"0.1.0","description":"MDBList (BYOK) lets an AI assistant read your own MDBList data through the MDBList API with a key you supply (MDBList API key). Read-only: 11 tools (get_user, search_media, get_media_info, list_genres, list_top_lists, search_lists, list_my_lists, get_list, list_list_items, list_movie_updates, list_show_updates). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-mdblist.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-mdblist/docs"},"termsOfService":"https://connectorbay.com/byok-mdblist/terms"},"servers":[{"url":"https://byok-mdblist.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-mdblist/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_user":{"post":{"operationId":"get_user","summary":"Show the MDBList account behind the key: username, plan, daily request limit, requests used and list limits. Use for \"Ho","description":"Show the MDBList account behind the key: username, plan, daily request limit, requests used and list limits. Use for \"How many MDBList API requests do I have left today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_userArguments","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_media":{"post":{"operationId":"search_media","summary":"Search movies and shows by title, optionally by year, returning type, year, MDBList score and provider ids (IMDb, TMDb, ","description":"Search movies and shows by title, optionally by year, returning type, year, MDBList score and provider ids (IMDb, TMDb, Trakt). Use for \"Find the IMDb id of the movie Jaws\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"media_type":{"description":"Kind of title: movie, show or any.","enum":["movie","show","any"],"title":"Media Type","type":"string"},"query":{"description":"Title to search for.","maxLength":200,"title":"Query","type":"string"},"year":{"anyOf":[{"maximum":2100,"minimum":1870,"type":"integer"},{"type":"null"}],"default":null,"description":"Only titles within one year of this year.","title":"Year"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Maximum results.","title":"Limit"},"limit_by_score":{"anyOf":[{"maximum":100,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only results with at least this MDBList score (0 to 100).","title":"Limit By Score"},"sort_by_score":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to sort results by score.","title":"Sort By Score"}},"required":["media_type","query"],"title":"search_mediaArguments","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_media_info":{"post":{"operationId":"get_media_info","summary":"Get one movie or show by an external id: description, runtime, MDBList score, ratings from IMDb, Metacritic, Rotten Toma","description":"Get one movie or show by an external id: description, runtime, MDBList score, ratings from IMDb, Metacritic, Rotten Tomatoes, Letterboxd and others, streaming services, certification and trailer. Use for \"What are the ratings and streaming services for IMDb title tt0073195\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"media_provider":{"description":"Which id system media_id belongs to: imdb, tmdb, trakt, tvdb, mal or mdblist.","enum":["imdb","tmdb","trakt","tvdb","mal","mdblist"],"title":"Media Provider","type":"string"},"media_type":{"description":"Kind of title: movie, show or any.","enum":["movie","show","any"],"title":"Media Type","type":"string"},"media_id":{"description":"The title's id in that system, for example tt0073195 for IMDb.","maxLength":40,"title":"Media Id","type":"string"}},"required":["media_provider","media_type","media_id"],"title":"get_media_infoArguments","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_genres":{"post":{"operationId":"list_genres","summary":"List the genre names and slugs MDBList uses, for regular titles or for anime. Use for \"Which genres can I filter MDBList","description":"List the genre names and slugs MDBList uses, for regular titles or for anime. Use for \"Which genres can I filter MDBList lists by\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"anime":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"1 to list anime genres, 0 for regular genres.","title":"Anime"}},"title":"list_genresArguments","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_top_lists":{"post":{"operationId":"list_top_lists","summary":"List the most liked public MDBList lists with owner, media type, item count and likes. Use for \"What are the most popula","description":"List the most liked public MDBList lists with owner, media type, item count and likes. Use for \"What are the most popular lists on MDBList\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_top_listsArguments","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_lists":{"post":{"operationId":"search_lists","summary":"Search public MDBList lists by title. Use for \"Find MDBList lists about horror\".","description":"Search public MDBList lists by title. Use for \"Find MDBList lists about horror\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Words from the list title.","maxLength":200,"title":"Query","type":"string"}},"required":["query"],"title":"search_listsArguments","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_my_lists":{"post":{"operationId":"list_my_lists","summary":"List your own MDBList lists (including private ones) with type, item count and likes. Use for \"Which MDBList lists do I ","description":"List your own MDBList lists (including private ones) with type, item count and likes. Use for \"Which MDBList lists do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort":{"anyOf":[{"enum":["ranked","name","created"],"type":"string"},{"type":"null"}],"default":"ranked","description":"Order: ranked, name or created.","title":"Sort"},"unified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to merge movie and show twin lists into one entry.","title":"Unified"}},"title":"list_my_listsArguments","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_list":{"post":{"operationId":"get_list","summary":"Get the details of one MDBList list by id: owner, name, description, media type, item count and likes. Use for \"What is ","description":"Get the details of one MDBList list by id: owner, name, description, media type, item count and likes. Use for \"What is MDBList list 1176\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"list_id":{"description":"Numeric MDBList list id, for example 1176.","minimum":1,"title":"List Id","type":"integer"}},"required":["list_id"],"title":"get_listArguments","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_list_items":{"post":{"operationId":"list_list_items","summary":"List the movies and shows in a list, with rank, title, year and provider ids, filterable by genre and score. At most 1,0","description":"List the movies and shows in a list, with rank, title, year and provider ids, filterable by genre and score. At most 1,000 items per call; page with offset. Use for \"What titles are in MDBList list 1176\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"list_id":{"description":"Numeric MDBList list id, for example 1176.","minimum":1,"title":"List Id","type":"integer"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Items to return (default 20).","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Items to skip, for paging.","title":"Offset"},"filter_genre":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated genre slugs from list_genres to keep.","title":"Filter Genre"},"filter_title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Keep only titles containing this text.","title":"Filter Title"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field, for example rank, score, imdbrating, released or title.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc.","title":"Order"},"filter_score_min":{"anyOf":[{"maximum":100,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum MDBList score, 0 to 100.","title":"Filter Score Min"}},"required":["list_id"],"title":"list_list_itemsArguments","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_movie_updates":{"post":{"operationId":"list_movie_updates","summary":"List movies whose MDBList data (ratings, metadata, streaming) changed recently, with cursor paging. Use for \"Which movie","description":"List movies whose MDBList data (ratings, metadata, streaming) changed recently, with cursor paging. Use for \"Which movies changed on MDBList since 2026-01-01\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"since":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only titles updated after this ISO 8601 time or YYYY-MM-DD date (UTC); default is the last 24 hours, at most 30 days back.","title":"Since"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Items per page (default 20, maximum 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the next_cursor value of the previous answer.","title":"Cursor"}},"title":"list_movie_updatesArguments","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_show_updates":{"post":{"operationId":"list_show_updates","summary":"List shows whose MDBList data changed recently, with cursor paging. Use for \"Which TV shows changed on MDBList in the la","description":"List shows whose MDBList data changed recently, with cursor paging. Use for \"Which TV shows changed on MDBList in the last day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"since":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only titles updated after this ISO 8601 time or YYYY-MM-DD date (UTC); default is the last 24 hours, at most 30 days back.","title":"Since"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Items per page (default 20, maximum 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the next_cursor value of the previous answer.","title":"Cursor"}},"title":"list_show_updatesArguments","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}}}}