Fincanva Open API and MCP reference

How do you call a Fincanva operation?

• Over REST, send POST to https://app.fincanva.com/api/v1/research/<operation_id> with the parameters as a JSON body and an Authorization: Bearer header carrying an API key or an OAuth access token.
• Over MCP, add https://app.fincanva.com/mcp to an MCP client; each operation is a tool named by its id, and the client signs in with your Fincanva account.
• The OpenAPI 3.1 document of every REST operation is at https://app.fincanva.com/api/v1/research/openapi.json.

What does every Fincanva operation return?

A successful REST call returns status: true and a data object holding result (the operation's own output), summary (a few lines of text), assumed (every value the operation filled in because the request left it out, with the reason), dataVersion (the nightly data build the figures come from, or null when nothing was computed from market data) and, when the result is a series, chart. A recorded result also carries recipeId (what reproduces it: the same operation, input and data version) and permalink (the result's permanent address on Fincanva). Over MCP the same object is the tool's structured content and the summary is its text.

What each unit and each sign means is stated once, in the conventions.

Which Fincanva operations can you call?

Strategy authoring

• List allocation methods — list_allocation_methods. Lists the allocation methods Fincanva offers — how a strategy, or a Combined strategy across its strategies, sets the weight of each holding — with each method's own parameters, their defaults and bounds, the levels it works at, and whether your plan includes it.
• List risk condition presets — list_risk_rule_presets. Lists the ready-made risk conditions a strategy can switch on — the VIX, the VIX ratio, TIPS, the yield-curve rules, the S&P 500 against its 200-day average and its 12-month momentum — each with the rule it applies: the indicator, the risk-off and risk-on thresholds, the weeks of delay and which values you may change.
• Describe the strategy model — describe_portfolio_model. Describes the Fincanva strategy model one section at a time — the Combined level (the API's portfolio), risk conditions, allocation, the strategies inside a Combined (the API's models), position exits, selection and simulation settings — listing every field with its type, unit, default, bounds and allowed values, and your plan's limit where one applies.

Screening

• List screener filters — list_screen_filters. Searches the screener's filter catalogue by words in a filter's name or description, by investing concept (value, momentum, quality and more), by level (asset, sector, market), by category or by asset type, and returns each match with the inputs it takes and the kinds of comparison it supports.
• Describe a screener filter — describe_screen_filter. Returns one screener filter in full: what it measures, the inputs it takes (such as how many months or reports ago its value is read), every relation it supports (greater than, between, highest N, against the market or sector aggregate, against its own past), each relation's comparison targets with their allowed values and defaults, and the unit of every value.

Which error codes can a Fincanva operation return?

• invalid_input — HTTP 422. The parameters do not match the operation's schema; details lists every problem with its field.
• payload_too_large — HTTP 413. The request body is larger than an operation accepts; details.maxBytes gives the limit. Nothing was run or charged.
• result_too_large — HTTP 422. The request was valid, but its result is larger than Fincanva keeps (details.maxBytes; details.what names the value). The run is refunded. Narrow it (fewer instruments, a shorter period, fewer steps) and run it again.
• ambiguous — HTTP 422. A name you gave matches several instruments; details lists the candidates, so choose one and call again.
• not_resolved — HTTP 422. A name you gave matches no instrument Fincanva has.
• insufficient_history — HTTP 422. The instruments do not have enough history for the period or lookback asked for.
• unauthorized — HTTP 401. The API key or access token is missing, expired or revoked.
• plan_limit — HTTP 403. Your plan does not include this operation or this setting; unlockedBy names the lowest plan that does.
• toolset_disabled — HTTP 403. The operation's family is switched off for this MCP connection; switch it on in the connection's settings in Fincanva.
• licence — HTTP 403. The data this operation needs may not be served through the API or MCP under its provider's terms.
• quota_exhausted — HTTP 429. This month's allowance of calls, heavy runs or research reports is used up; resetsAt gives the date it resets.
• not_found — HTTP 404. The operation, or an item you named such as a filter, does not exist.
• busy — HTTP 503. Fincanva is at capacity for this kind of run; nothing was charged against your allowance, so try again shortly.
• engine_failed — HTTP 502. The computation failed on Fincanva's side; nothing was charged against your allowance.
• internal — HTTP 500. An unexpected error on Fincanva's side; nothing was charged against your allowance.