{"openapi":"3.1.0","info":{"title":"SimFin (BYOK) API","version":"0.1.0","description":"SimFin (BYOK) lets an AI assistant read your own SimFin data through the SimFin API with a key you supply (SimFin API key). Read-only: 9 tools (list_companies, get_company_info, get_financial_statements, get_share_prices, get_common_shares_outstanding, get_weighted_shares_outstanding, list_company_filings, list_filings, list_changed_companies). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-simfin.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-simfin/docs"},"termsOfService":"https://connectorbay.com/byok-simfin/terms"},"servers":[{"url":"https://byok-simfin.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-simfin/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/list_companies":{"post":{"operationId":"list_companies","summary":"List the companies in the SimFin database (SimFin ID and ticker). The list is long; only the first entries are returned.","description":"List the companies in the SimFin database (SimFin ID and ticker). The list is long; only the first entries are returned. Use for \"Which companies does SimFin cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_companiesArguments","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_info":{"post":{"operationId":"get_company_info","summary":"Get general company information for companies chosen by ticker or SimFin ID. The response shape is not documented by the","description":"Get general company information for companies chosen by ticker or SimFin ID. The response shape is not documented by the provider and is returned as sent (first entries only). Use for \"Give me general company information for AAPL\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated SimFin company IDs, for example '111052'. Use this or ticker.","title":"Id"},"ticker":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ticker symbols, for example 'AAPL,MSFT'. Use this or id.","title":"Ticker"}},"title":"get_company_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/get_financial_statements":{"post":{"operationId":"get_financial_statements","summary":"Get income statement, balance sheet, cash flow or derived ratios for companies by period and fiscal year, as a list of r","description":"Get income statement, balance sheet, cash flow or derived ratios for companies by period and fiscal year, as a list of records. Use for \"Show Apple's annual income statement and balance sheet\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"statements":{"description":"Comma-separated statement types: PL (income), BS (balance sheet), CF (cash flow), DERIVED (ratios).","maxLength":40,"title":"Statements","type":"string"},"id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated SimFin company IDs, for example '111052'. Use this or ticker.","title":"Id"},"ticker":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ticker symbols, for example 'AAPL,MSFT'. Use this or id.","title":"Ticker"},"period":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated periods: Q1, Q2, Q3, Q4, FY, H1, H2, NINE_MONTH. Omit for all.","title":"Period"},"fyear":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated fiscal years such as '2021,2023' (the company's fiscal year).","title":"Fyear"},"start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest date to include, YYYY-MM-DD (period end).","title":"Start"},"end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Latest date to include, YYYY-MM-DD (period end).","title":"End"},"ttm":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return trailing twelve month periods.","title":"Ttm"},"asreported":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return figures as originally reported instead of restated.","title":"Asreported"}},"required":["statements"],"title":"get_financial_statementsArguments","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_share_prices":{"post":{"operationId":"get_share_prices","summary":"Get daily share price history for companies, optionally with valuation ratios and derived metrics. Use for \"Show Apple's","description":"Get daily share price history for companies, optionally with valuation ratios and derived metrics. Use for \"Show Apple's share price in January 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated SimFin company IDs, for example '111052'. Use this or ticker.","title":"Id"},"ticker":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ticker symbols, for example 'AAPL,MSFT'. Use this or id.","title":"Ticker"},"ratios":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include ratios and derived metrics.","title":"Ratios"},"asreported":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to use as-reported figures for derived metrics.","title":"Asreported"},"start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest date to include, YYYY-MM-DD (price date).","title":"Start"},"end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Latest date to include, YYYY-MM-DD (price date).","title":"End"}},"title":"get_share_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/get_common_shares_outstanding":{"post":{"operationId":"get_common_shares_outstanding","summary":"Get point-in-time common shares outstanding for companies, optionally within a date range. Use for \"How many shares of A","description":"Get point-in-time common shares outstanding for companies, optionally within a date range. Use for \"How many shares of Apple are outstanding\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated SimFin company IDs, for example '111052'. Use this or ticker.","title":"Id"},"ticker":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ticker symbols, for example 'AAPL,MSFT'. Use this or id.","title":"Ticker"},"start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest date to include, YYYY-MM-DD (date).","title":"Start"},"end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Latest date to include, YYYY-MM-DD (date).","title":"End"}},"title":"get_common_shares_outstandingArguments","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_weighted_shares_outstanding":{"post":{"operationId":"get_weighted_shares_outstanding","summary":"Get weighted average shares outstanding per reporting period (quarter, half year, year or trailing twelve months). Use f","description":"Get weighted average shares outstanding per reporting period (quarter, half year, year or trailing twelve months). Use for \"What were Apple's weighted shares outstanding by fiscal year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated SimFin company IDs, for example '111052'. Use this or ticker.","title":"Id"},"ticker":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ticker symbols, for example 'AAPL,MSFT'. Use this or id.","title":"Ticker"},"period":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated periods: Q1, Q2, Q3, Q4, FY, H1, H2, NINE_MONTH.","title":"Period"},"fyear":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated fiscal years such as '2021,2023'.","title":"Fyear"},"start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest date to include, YYYY-MM-DD (period end).","title":"Start"},"end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Latest date to include, YYYY-MM-DD (period end).","title":"End"},"ttm":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return trailing twelve month figures.","title":"Ttm"}},"title":"get_weighted_shares_outstandingArguments","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_filings":{"post":{"operationId":"list_company_filings","summary":"List the SEC filings SimFin holds for one company, by ticker or SimFin ID (filing documents are not downloaded). Free ac","description":"List the SEC filings SimFin holds for one company, by ticker or SimFin ID (filing documents are not downloaded). Free accounts have a small daily filings quota. Use for \"Which filings does SimFin have for AAPL\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"SimFin company ID. Use this or ticker.","title":"Id"},"ticker":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Company ticker, for example 'AAPL'. Use this or id.","title":"Ticker"}},"title":"list_company_filingsArguments","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_filings":{"post":{"operationId":"list_filings","summary":"List recent filings across all companies in the SimFin database, with paging and an optional filing-date window. Use for","description":"List recent filings across all companies in the SimFin database, with paging and an optional filing-date window. Use for \"What filings were added between 2026-10-01 and 2026-10-15\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number starting at 0.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Filings per page (1 to 100).","title":"Per Page"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest filing date, YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Latest filing date, YYYY-MM-DD.","title":"End Date"}},"title":"list_filingsArguments","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_changed_companies":{"post":{"operationId":"list_changed_companies","summary":"List companies whose data changed since a start date, useful for knowing what to refresh. Use for \"Which companies chang","description":"List companies whose data changed since a start date, useful for knowing what to refresh. Use for \"Which companies changed in SimFin since 2026-10-01\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest date to include, YYYY-MM-DD (change date).","title":"Start"}},"title":"list_changed_companiesArguments","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}}}}