{"openapi":"3.1.0","info":{"title":"Finnhub (BYOK) API","version":"0.1.0","description":"Finnhub (BYOK) lets an AI assistant read your own Finnhub data through the Finnhub API with a key you supply (Finnhub API key). Read-only: 12 tools (get_quote, get_company_profile, list_company_news, list_market_news, get_basic_financials, get_recommendation_trends, get_earnings_surprises, get_earnings_calendar, get_ipo_calendar, search_symbols, get_company_peers, get_market_status). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-finnhub.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-finnhub/docs"},"termsOfService":"https://connectorbay.com/byok-finnhub/terms"},"servers":[{"url":"https://byok-finnhub.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-finnhub/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_quote":{"post":{"operationId":"get_quote","summary":"Get the latest price of a US stock: current, open, high, low, previous close, change and percent change. Use for \"What i","description":"Get the latest price of a US stock: current, open, high, low, previous close, change and percent change. Use for \"What is Apple trading at right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"description":"Stock ticker symbol, for example 'AAPL'.","maxLength":30,"title":"Symbol","type":"string"}},"required":["symbol"],"title":"get_quoteArguments","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_company_profile":{"post":{"operationId":"get_company_profile","summary":"Get a company's name, exchange, country, currency, industry, IPO date, market capitalisation and website by ticker symbo","description":"Get a company's name, exchange, country, currency, industry, IPO date, market capitalisation and website by ticker symbol. Use for \"Give me the company profile for Microsoft\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"description":"Stock ticker symbol, for example 'AAPL'.","maxLength":30,"title":"Symbol","type":"string"}},"required":["symbol"],"title":"get_company_profileArguments","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_company_news":{"post":{"operationId":"list_company_news","summary":"List news stories about one company between two dates (North American companies only). Use for \"What news came out about","description":"List news stories about one company between two dates (North American companies only). Use for \"What news came out about Tesla this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"description":"Stock ticker symbol, for example 'AAPL'.","maxLength":30,"title":"Symbol","type":"string"},"from_date":{"description":"First day, formatted YYYY-MM-DD.","maxLength":10,"title":"From Date","type":"string"},"to_date":{"description":"Last day, formatted YYYY-MM-DD.","maxLength":10,"title":"To Date","type":"string"}},"required":["symbol","from_date","to_date"],"title":"list_company_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/list_market_news":{"post":{"operationId":"list_market_news","summary":"List the latest market news for a category: general, forex, crypto or merger. Pass min_id to get only stories newer than","description":"List the latest market news for a category: general, forex, crypto or merger. Pass min_id to get only stories newer than an id. Use for \"Show me the latest crypto market news\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"News category: general, forex, crypto or merger.","enum":["general","forex","crypto","merger"],"title":"Category","type":"string"},"min_id":{"anyOf":[{"maximum":2000000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Only return stories with an id greater than this (0 for the newest).","title":"Min Id"}},"required":["category"],"title":"list_market_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_basic_financials":{"post":{"operationId":"get_basic_financials","summary":"Get key ratios and statistics for a company, such as 52 week high and low, beta and average trading volume. Use for \"Wha","description":"Get key ratios and statistics for a company, such as 52 week high and low, beta and average trading volume. Use for \"What are the 52 week high and low and the beta of Nvidia\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"description":"Stock ticker symbol, for example 'AAPL'.","maxLength":30,"title":"Symbol","type":"string"},"metric":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"default":"all","description":"Set of metrics to return; only 'all' is documented.","title":"Metric"}},"required":["symbol"],"title":"get_basic_financialsArguments","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_recommendation_trends":{"post":{"operationId":"get_recommendation_trends","summary":"Get the monthly count of analyst ratings (strong buy, buy, hold, sell, strong sell) for a company. Use for \"How many ana","description":"Get the monthly count of analyst ratings (strong buy, buy, hold, sell, strong sell) for a company. Use for \"How many analysts rate Amazon a buy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"description":"Stock ticker symbol, for example 'AAPL'.","maxLength":30,"title":"Symbol","type":"string"}},"required":["symbol"],"title":"get_recommendation_trendsArguments","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_earnings_surprises":{"post":{"operationId":"get_earnings_surprises","summary":"Get a company's recent quarterly earnings per share results against analyst estimates, with the surprise amount and perc","description":"Get a company's recent quarterly earnings per share results against analyst estimates, with the surprise amount and percent. Use for \"Did Meta beat its earnings estimates recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"description":"Stock ticker symbol, for example 'AAPL'.","maxLength":30,"title":"Symbol","type":"string"},"limit":{"anyOf":[{"maximum":40,"minimum":1,"type":"integer"},{"type":"null"}],"default":4,"description":"How many most recent quarters to return.","title":"Limit"}},"required":["symbol"],"title":"get_earnings_surprisesArguments","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_earnings_calendar":{"post":{"operationId":"get_earnings_calendar","summary":"List scheduled company earnings releases between two dates, with EPS and revenue estimates and actuals. Use for \"Which c","description":"List scheduled company earnings releases between two dates, with EPS and revenue estimates and actuals. Use for \"Which companies report earnings next week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day, formatted YYYY-MM-DD.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last day, formatted YYYY-MM-DD.","title":"To Date"},"symbol":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Limit to one ticker symbol.","title":"Symbol"}},"title":"get_earnings_calendarArguments","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_ipo_calendar":{"post":{"operationId":"get_ipo_calendar","summary":"List past and upcoming IPOs between two dates with exchange, status, price range and share counts. Use for \"Which IPOs a","description":"List past and upcoming IPOs between two dates with exchange, status, price range and share counts. Use for \"Which IPOs are scheduled for the next two weeks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"description":"First day, formatted YYYY-MM-DD.","maxLength":10,"title":"From Date","type":"string"},"to_date":{"description":"Last day, formatted YYYY-MM-DD.","maxLength":10,"title":"To Date","type":"string"}},"required":["from_date","to_date"],"title":"get_ipo_calendarArguments","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_symbols":{"post":{"operationId":"search_symbols","summary":"Find ticker symbols by company name, symbol or ISIN text. Use for \"Find the ticker symbol for Shopify\".","description":"Find ticker symbols by company name, symbol or ISIN text. Use for \"Find the ticker symbol for Shopify\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Name, ticker or ISIN to look for, for example 'shopify'.","maxLength":100,"title":"Q","type":"string"},"exchange":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Limit to an exchange code, for example 'US'.","title":"Exchange"}},"required":["q"],"title":"search_symbolsArguments","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_company_peers":{"post":{"operationId":"get_company_peers","summary":"List ticker symbols of companies similar to the given one, grouped by sector, industry or sub-industry. Use for \"Which c","description":"List ticker symbols of companies similar to the given one, grouped by sector, industry or sub-industry. Use for \"Which companies are peers of Adobe\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"description":"Stock ticker symbol, for example 'AAPL'.","maxLength":30,"title":"Symbol","type":"string"},"grouping":{"anyOf":[{"enum":["sector","industry","subIndustry"],"type":"string"},{"type":"null"}],"default":"subIndustry","description":"How to group peers: sector, industry or subIndustry.","title":"Grouping"}},"required":["symbol"],"title":"get_company_peersArguments","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_market_status":{"post":{"operationId":"get_market_status","summary":"Show whether a stock exchange is open now, its time zone, session and any holiday. Use for \"Is the US stock market open ","description":"Show whether a stock exchange is open now, its time zone, session and any holiday. Use for \"Is the US stock market open right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"exchange":{"description":"Exchange code, for example 'US'.","maxLength":20,"title":"Exchange","type":"string"}},"required":["exchange"],"title":"get_market_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}}}}