{"openapi":"3.1.0","info":{"title":"API Ninjas (BYOK) API","version":"0.1.0","description":"API Ninjas (BYOK) lets an AI assistant read your own API Ninjas data through the API Ninjas API with a key you supply (API Ninjas API key). Read-only: 10 tools (get_exchange_rate, get_commodity_price, list_commodity_prices, search_cities, search_countries, get_timezone, list_public_holidays, check_public_holiday, search_historical_events, get_nutrition_from_text). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-apininjas.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-apininjas/docs"},"termsOfService":"https://connectorbay.com/byok-apininjas/terms"},"servers":[{"url":"https://byok-apininjas.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-apininjas/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_exchange_rate":{"post":{"operationId":"get_exchange_rate","summary":"Get the current exchange rate for a currency pair. Free keys get a rate that updates once a day; paid plans get real-tim","description":"Get the current exchange rate for a currency pair. Free keys get a rate that updates once a day; paid plans get real-time rates. Use for \"What is the USD to EUR exchange rate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pair":{"description":"Currency pair as two ISO 4217 codes joined by an underscore, for example 'USD_EUR'.","maxLength":10,"title":"Pair","type":"string"}},"required":["pair"],"title":"get_exchange_rateArguments","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_commodity_price":{"post":{"operationId":"get_commodity_price","summary":"Get the latest futures price of one commodity such as gold, silver, crude_oil or corn, with daily change and 52-week ran","description":"Get the latest futures price of one commodity such as gold, silver, crude_oil or corn, with daily change and 52-week range. Use for \"What is the price of gold today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Commodity name as the provider spells it, for example 'gold', 'silver', 'platinum' or 'crude_oil'.","maxLength":40,"title":"Name","type":"string"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":null,"description":"ISO 4217 currency code to convert the price into, for example 'EUR'.","title":"Currency"}},"required":["name"],"title":"get_commodity_priceArguments","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_commodity_prices":{"post":{"operationId":"list_commodity_prices","summary":"List current prices of many commodities, optionally limited to one category or exchange. Use for \"Show me the current en","description":"List current prices of many commodities, optionally limited to one category or exchange. Use for \"Show me the current energy commodity prices\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"enum":["precious_metals","base_metals","energy","grains","softs","livestock"],"type":"string"},{"type":"null"}],"default":null,"description":"Category to list.","title":"Category"},"exchange":{"anyOf":[{"enum":["CME","NYMEX","COMEX","ICE"],"type":"string"},{"type":"null"}],"default":null,"description":"Exchange to list.","title":"Exchange"}},"title":"list_commodity_pricesArguments","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_cities":{"post":{"operationId":"search_cities","summary":"Search cities by name, country and population; returns coordinates, country code, population and whether it is a capital","description":"Search cities by name, country and population; returns coordinates, country code, population and whether it is a capital. Give at least one filter. Free keys receive one match. Use for \"What is the population of Lisbon in Portugal\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"City name, for example 'London'.","title":"Name"},"country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"ISO 3166 alpha-2 country code, for example 'PT'.","title":"Country"},"min_population":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only cities with at least this many people.","title":"Min Population"},"max_population":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only cities with at most this many people.","title":"Max Population"}},"title":"search_citiesArguments","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_countries":{"post":{"operationId":"search_countries","summary":"Look up country statistics (capital, region, currency, GDP, population, area, unemployment, life expectancy and more) by","description":"Look up country statistics (capital, region, currency, GDP, population, area, unemployment, life expectancy and more) by name or filters. Use for \"What is the population and GDP of Japan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Country name or ISO 3166 alpha-2 or alpha-3 code, for example 'Japan' or 'JP'.","title":"Name"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":null,"description":"Three-letter currency code, for example 'EUR'.","title":"Currency"},"min_population":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Minimum population, in thousands.","title":"Min Population"},"max_population":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Maximum population, in thousands.","title":"Max Population"},"limit":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":5,"description":"How many countries to return (1 to 30).","title":"Limit"}},"title":"search_countriesArguments","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_timezone":{"post":{"operationId":"get_timezone","summary":"Get the current local time and UTC offset (in seconds) for an IANA time zone name. Use for \"What time is it now in Asia/","description":"Get the current local time and UTC offset (in seconds) for an IANA time zone name. Use for \"What time is it now in Asia/Kolkata\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"timezone":{"description":"IANA time zone name, for example 'Asia/Kolkata' or 'America/New_York'.","maxLength":60,"title":"Timezone","type":"string"}},"required":["timezone"],"title":"get_timezoneArguments","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_public_holidays":{"post":{"operationId":"list_public_holidays","summary":"List a country's public holidays for the current year with local names, dates and whether each is nationwide. Free keys ","description":"List a country's public holidays for the current year with local names, dates and whether each is nationwide. Free keys can only ask for the current year. Use for \"What are the public holidays in Germany this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"description":"Country as an ISO 3166 alpha-2 code (for example 'DE'), alpha-3 code or English name.","maxLength":60,"title":"Country","type":"string"}},"required":["country"],"title":"list_public_holidaysArguments","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/check_public_holiday":{"post":{"operationId":"check_public_holiday","summary":"Check whether one date is a public holiday in a country, optionally for a state or region. Free keys can check dates in ","description":"Check whether one date is a public holiday in a country, optionally for a state or region. Free keys can check dates in the current or past years. Use for \"Is 2026-01-01 a public holiday in France\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"description":"Country as an ISO 3166 alpha-2 code (for example 'FR'), alpha-3 code or English name.","maxLength":60,"title":"Country","type":"string"},"date":{"description":"Date to check, YYYY-MM-DD, between 1980-01-01 and 2050-12-31.","maxLength":10,"title":"Date","type":"string"},"subdivision":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"ISO 3166-2 code of a state or region, for example 'DE-BY'.","title":"Subdivision"}},"required":["country","date"],"title":"check_public_holidayArguments","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_historical_events":{"post":{"operationId":"search_historical_events","summary":"Search notable historical events by keyword and/or date; returns up to 10 events with year, month, day and a description","description":"Search notable historical events by keyword and/or date; returns up to 10 events with year, month, day and a description. Use for \"What happened on 20 July in history\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Keywords or a short phrase, for example 'moon landing'.","title":"Text"},"year":{"anyOf":[{"maximum":3000,"minimum":-5000,"type":"integer"},{"type":"null"}],"default":null,"description":"Four-digit year; use a negative number for BC years.","title":"Year"},"month":{"anyOf":[{"maximum":12,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Month number, 1 to 12.","title":"Month"},"day":{"anyOf":[{"maximum":31,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Day of the month, 1 to 31.","title":"Day"}},"title":"search_historical_eventsArguments","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_nutrition_from_text":{"post":{"operationId":"get_nutrition_from_text","summary":"Estimate nutrition for foods written in plain text, such as '1lb brisket and fries'; returns one entry per food. Calorie","description":"Estimate nutrition for foods written in plain text, such as '1lb brisket and fries'; returns one entry per food. Calories and protein are returned only on paid plans. Use for \"How much fat and carbohydrate are in a bowl of rice with chicken\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Foods in plain text, optionally with quantities, for example '1lb brisket and fries'.","maxLength":500,"title":"Query","type":"string"}},"required":["query"],"title":"get_nutrition_from_textArguments","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}}}}