{"openapi":"3.1.0","info":{"title":"World News API (BYOK) API","version":"0.1.0","description":"World News API (BYOK) lets an AI assistant read your own World News API data through the World News API API with a key you supply (World News API key). Read-only: 8 tools (search_news, search_news_by_entity, search_news_near_location, get_top_news, get_news_by_id, get_front_page, search_news_sources, get_geo_coordinates). The BYOK key travels with each request, is used for that one call only and...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-worldnewsapi.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-worldnewsapi/docs"},"termsOfService":"https://connectorbay.com/byok-worldnewsapi/terms"},"servers":[{"url":"https://byok-worldnewsapi.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-worldnewsapi/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_news":{"post":{"operationId":"search_news","summary":"Search news articles by words and filters (language, country, publish dates, sentiment range, publisher, category). Arti","description":"Search news articles by words and filters (language, country, publish dates, sentiment range, publisher, category). Articles carry a summary, publish date, authors and sentiment score. Costs 1 plan point plus 0.01 per article returned. Use for \"What positive English news about electric cars was published since the start of April 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Words to match, 3 to 100 characters; several words are all required, use OR or a minus sign for alternatives and exclusions, for example 'tesla -ford'.","title":"Text"},"language":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 639-1 language code of the articles, for example 'en'.","title":"Language"},"source_country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 3166 country code the articles originate from, for example 'us'.","title":"Source Country"},"earliest_publish_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published after this time, 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD'.","title":"Earliest Publish Date"},"latest_publish_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published before this time, 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD'.","title":"Latest Publish Date"},"min_sentiment":{"anyOf":[{"maximum":1,"minimum":-1,"type":"number"},{"type":"null"}],"default":null,"description":"Minimum sentiment of the article, -1 (negative) to 1 (positive); sentiment is available for English and German.","title":"Min Sentiment"},"max_sentiment":{"anyOf":[{"maximum":1,"minimum":-1,"type":"number"},{"type":"null"}],"default":null,"description":"Maximum sentiment of the article, -1 (negative) to 1 (positive).","title":"Max Sentiment"},"news_sources":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Up to 10 publishers, comma separated, for example 'bbc.com,cnbc.com'.","title":"News Sources"},"categories":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Categories, comma separated: politics, sports, business, technology, entertainment, health, science, lifestyle, travel, culture, education, environment or other.","title":"Categories"},"sort_direction":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"ASC or DESC (default DESC) when sorting by publish time.","title":"Sort Direction"},"number":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many articles to return, 1 to 100 (default 10). Each returned article costs 0.01 extra plan points.","title":"Number"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Articles to skip, 0 to 10000, for paging.","title":"Offset"}},"title":"search_newsArguments","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_news_by_entity":{"post":{"operationId":"search_news_by_entity","summary":"Find news mentioning a person, organization or location by semantic entity tags such as 'ORG:Tesla,PER:Elon Musk' or 'LO","description":"Find news mentioning a person, organization or location by semantic entity tags such as 'ORG:Tesla,PER:Elon Musk' or 'LOC:Italy', so spelling variants and synonyms are matched. Use for \"Which news mentions both Tesla and Elon Musk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"entities":{"description":"Entity filter 'TYPE:Name' pairs, comma separated; types are PER, ORG and LOC, for example 'ORG:Tesla,PER:Elon Musk'.","maxLength":1000,"title":"Entities","type":"string"},"language":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 639-1 language code of the articles, for example 'en'.","title":"Language"},"source_country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 3166 country code the articles originate from, for example 'us'.","title":"Source Country"},"earliest_publish_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published after this time, 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD'.","title":"Earliest Publish Date"},"latest_publish_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published before this time, 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD'.","title":"Latest Publish Date"},"number":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many articles to return, 1 to 100 (default 10). Each returned article costs 0.01 extra plan points.","title":"Number"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Articles to skip, 0 to 10000, for paging.","title":"Offset"}},"required":["entities"],"title":"search_news_by_entityArguments","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_news_near_location":{"post":{"operationId":"search_news_near_location","summary":"Find news that mentions places within a radius of 1 to 100 kilometres around a point; get the latitude and longitude of ","description":"Find news that mentions places within a radius of 1 to 100 kilometres around a point; get the latitude and longitude of a place with get_geo_coordinates. Use for \"What news was published about places within 20 km of Dresden\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_filter":{"description":"Latitude, longitude and radius in kilometres (1 to 100), for example '51.050407,13.737262,20'.","maxLength":100,"title":"Location Filter","type":"string"},"language":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 639-1 language code of the articles, for example 'en'.","title":"Language"},"earliest_publish_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published after this time, 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD'.","title":"Earliest Publish Date"},"latest_publish_date":{"anyOf":[{"maxLength":19,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published before this time, 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD'.","title":"Latest Publish Date"},"number":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many articles to return, 1 to 100 (default 10). Each returned article costs 0.01 extra plan points.","title":"Number"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Articles to skip, 0 to 10000, for paging.","title":"Offset"}},"required":["location_filter"],"title":"search_news_near_locationArguments","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_news":{"post":{"operationId":"get_top_news","summary":"Get the top story clusters of a country for a day, each with several articles from different publishers. Headlines only ","description":"Get the top story clusters of a country for a day, each with several articles from different publishers. Headlines only by default, which keeps the answer short. Use for \"What are the top news stories in Germany today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"source_country":{"description":"Two-letter ISO 3166 country code, for example 'us'.","maxLength":2,"title":"Source Country","type":"string"},"language":{"description":"Two-letter language code, one spoken in that country, for example 'en'.","maxLength":2,"title":"Language","type":"string"},"date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day to get top news for, YYYY-MM-DD (default today).","title":"Date"},"headlines_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Return only id, title and url of each article.","title":"Headlines Only"},"max_news_per_cluster":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Articles to return per story cluster, 1 to 100.","title":"Max News Per Cluster"}},"required":["source_country","language"],"title":"get_top_newsArguments","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_news_by_id":{"post":{"operationId":"get_news_by_id","summary":"Retrieve specific articles by their ids (from earlier search results) with summary, publish date, authors, category and ","description":"Retrieve specific articles by their ids (from earlier search results) with summary, publish date, authors, category and sentiment. Use for \"Show me the articles with ids 2352 and 2354\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ids":{"description":"Comma-separated article ids, for example '2352,2354'.","maxLength":1000,"title":"Ids","type":"string"}},"required":["ids"],"title":"get_news_by_idArguments","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_front_page":{"post":{"operationId":"get_front_page","summary":"Get the image URL of a newspaper's front page for a day, for example the Herald Sun in Australia; the archive starts on ","description":"Get the image URL of a newspaper's front page for a day, for example the Herald Sun in Australia; the archive starts on 2024-07-09. Use for \"Show me today's front page of the Herald Sun\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"source_country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 3166 country code of the newspaper, for example 'au'.","title":"Source Country"},"source_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Newspaper identifier, for example 'herald-sun'.","title":"Source Name"},"date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Day of the edition, YYYY-MM-DD (earliest 2024-07-09).","title":"Date"}},"title":"get_front_pageArguments","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_news_sources":{"post":{"operationId":"search_news_sources","summary":"Search the news sources indexed by World News API by (partial) name and get each publisher's website and language. Use f","description":"Search the news sources indexed by World News API by (partial) name and get each publisher's website and language. Use for \"Which BBC sources does World News API index\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Partial source name, 3 to 1000 characters, for example 'bbc'.","maxLength":1000,"title":"Name","type":"string"}},"required":["name"],"title":"search_news_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/get_geo_coordinates":{"post":{"operationId":"get_geo_coordinates","summary":"Convert a place name or address into latitude and longitude, for use with search_news_near_location. Use for \"What are t","description":"Convert a place name or address into latitude and longitude, for use with search_news_near_location. Use for \"What are the coordinates of Tokyo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Place name or address, for example 'Tokyo, Japan'.","maxLength":1000,"title":"Location","type":"string"}},"required":["location"],"title":"get_geo_coordinatesArguments","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}}}}