{"openapi":"3.1.0","info":{"title":"New York Times (BYOK) API","version":"0.1.0","description":"New York Times (BYOK) lets an AI assistant read your own New York Times data through the New York Times API with a key you supply (New York Times API key). Read-only: 6 tools (get_top_stories, search_articles, filter_articles, list_movie_reviews, search_movie_reviews, list_movie_critics). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached;...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-nytimes.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-nytimes/docs"},"termsOfService":"https://connectorbay.com/byok-nytimes/terms"},"servers":[{"url":"https://byok-nytimes.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-nytimes/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_top_stories":{"post":{"operationId":"get_top_stories","summary":"List the current top stories of a New York Times section with title, abstract, byline, dates and link. Use for \"What are","description":"List the current top stories of a New York Times section with title, abstract, byline, dates and link. Use for \"What are the top New York Times technology stories right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"section":{"description":"Section name, for example home, world, politics, technology, science, business, arts or sports.","enum":["home","opinion","world","national","politics","upshot","nyregion","business","technology","science","health","sports","arts","books","movies","theater","sundayreview","fashion","tmagazine","food","travel","magazine","realestate","automobiles","obituaries","insider"],"title":"Section","type":"string"}},"required":["section"],"title":"get_top_storiesArguments","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_articles":{"post":{"operationId":"search_articles","summary":"Search New York Times articles by keywords, returning headline, abstract, byline, section, date and link, ten per page, ","description":"Search New York Times articles by keywords, returning headline, abstract, byline, section, date and link, ten per page, optionally within a date range. Use for \"Search the New York Times for articles about semiconductor export controls\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Search terms, matched against body, headline and byline.","maxLength":300,"title":"Q","type":"string"},"begin_date":{"anyOf":[{"maxLength":8,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published on or after this date, YYYYMMDD.","title":"Begin Date"},"end_date":{"anyOf":[{"maxLength":8,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published on or before this date, YYYYMMDD.","title":"End Date"},"sort":{"anyOf":[{"enum":["newest","oldest"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by newest or oldest publication date; the default is relevance.","title":"Sort"},"page":{"anyOf":[{"maximum":10,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number starting at 0; each page holds 10 results and the highest page is 10.","title":"Page"},"fl":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":"headline,web_url,pub_date,abstract,snippet,lead_paragraph,section_name,news_desk,type_of_material,byline,word_count,_id","description":"Comma-separated article fields to return.","title":"Fl"}},"required":["q"],"title":"search_articlesArguments","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/filter_articles":{"post":{"operationId":"filter_articles","summary":"List New York Times articles that match a Lucene filter query such as section_name:\"Science\" or news_desk:(\"Sports\"), ne","description":"List New York Times articles that match a Lucene filter query such as section_name:\"Science\" or news_desk:(\"Sports\"), newest first by default. Use for \"Which Science section articles did the New York Times publish most recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fq":{"description":"Lucene filter, for example 'section_name:(\"Science\") AND type_of_material:(\"News\")'. Fields include section_name, news_desk, type_of_material, byline, headline, subject, glocations.","maxLength":300,"title":"Fq","type":"string"},"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Optional extra search terms.","title":"Q"},"begin_date":{"anyOf":[{"maxLength":8,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles on or after this date, YYYYMMDD.","title":"Begin Date"},"end_date":{"anyOf":[{"maxLength":8,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles on or before this date, YYYYMMDD.","title":"End Date"},"sort":{"anyOf":[{"enum":["newest","oldest"],"type":"string"},{"type":"null"}],"default":"newest","description":"Order by newest or oldest publication date.","title":"Sort"},"page":{"anyOf":[{"maximum":10,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number starting at 0; each page holds 10 results and the highest page is 10.","title":"Page"},"fl":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":"headline,web_url,pub_date,abstract,snippet,lead_paragraph,section_name,news_desk,type_of_material,byline,word_count,_id","description":"Comma-separated article fields to return.","title":"Fl"}},"required":["fq"],"title":"filter_articlesArguments","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_reviews":{"post":{"operationId":"list_movie_reviews","summary":"List New York Times movie reviews, either all of them or only the Critics' Picks, twenty per page. Use for \"Which movies","description":"List New York Times movie reviews, either all of them or only the Critics' Picks, twenty per page. Use for \"Which movies are the current New York Times Critics' Picks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"description":"all for every review, or picks for Critics' Picks currently in theaters.","enum":["all","picks"],"title":"Type","type":"string"},"order":{"anyOf":[{"enum":["by-title","by-publication-date","by-opening-date"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order: by-title, by-publication-date or by-opening-date.","title":"Order"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Skip this many results; must be a multiple of 20 (the page size).","title":"Offset"}},"required":["type"],"title":"list_movie_reviewsArguments","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_movie_reviews":{"post":{"operationId":"search_movie_reviews","summary":"Search New York Times movie reviews by title keywords, with optional filters for Critics' Picks, reviewer and publicatio","description":"Search New York Times movie reviews by title keywords, with optional filters for Critics' Picks, reviewer and publication or opening dates. Use for \"Find the New York Times review of the movie Parasite\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keywords matched against the movie title and indexed terms; wrap in single quotes for an exact match.","maxLength":200,"title":"Query","type":"string"},"critics_pick":{"anyOf":[{"enum":["Y","N"],"type":"string"},{"type":"null"}],"default":null,"description":"Y for Critics' Picks only, N for the rest.","title":"Critics Pick"},"reviewer":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Critic name in the form 'Manohla Dargis'.","title":"Reviewer"},"publication_date":{"anyOf":[{"maxLength":21,"type":"string"},{"type":"null"}],"default":null,"description":"Review publication date, YYYY-MM-DD, or a range 'YYYY-MM-DD;YYYY-MM-DD'.","title":"Publication Date"},"opening_date":{"anyOf":[{"maxLength":21,"type":"string"},{"type":"null"}],"default":null,"description":"Movie opening date, YYYY-MM-DD, or a range 'YYYY-MM-DD;YYYY-MM-DD'.","title":"Opening Date"},"order":{"anyOf":[{"enum":["by-title","by-publication-date","by-opening-date"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order: by-title, by-publication-date or by-opening-date.","title":"Order"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Skip this many results; must be a multiple of 20 (the page size).","title":"Offset"}},"required":["query"],"title":"search_movie_reviewsArguments","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_critics":{"post":{"operationId":"list_movie_critics","summary":"List the New York Times movie critics: all, full-time or part-time, or look one up by name, with bio. Use for \"Who are t","description":"List the New York Times movie critics: all, full-time or part-time, or look one up by name, with bio. Use for \"Who are the full-time New York Times movie critics\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"description":"all, full-time, part-time, or a reviewer name such as 'Manohla Dargis'.","maxLength":100,"title":"Type","type":"string"}},"required":["type"],"title":"list_movie_criticsArguments","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}}}}