{"openapi":"3.1.0","info":{"title":"Belvo (BYOK) API","version":"0.1.0","description":"Belvo (BYOK) lets an AI assistant read your own Belvo data through the Belvo API with a key you supply (Belvo secret ID). Read-only: 9 tools (list_institutions, list_links, list_accounts, list_transactions, list_incomes, list_recurring_expenses, list_risk_insights, list_br_payment_intents, list_br_payment_charges). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-belvo.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-belvo/docs"},"termsOfService":"https://connectorbay.com/byok-belvo/terms"},"servers":[{"url":"https://byok-belvo.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-belvo/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_institutions":{"post":{"operationId":"list_institutions","summary":"List the banks, fiscal and employment institutions Belvo can connect to, with country, type and health status. Use for \"","description":"List the banks, fiscal and employment institutions Belvo can connect to, with country, type and health status. Use for \"Which Brazilian banks can Belvo connect to right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter country code such as BR, MX or CO.","title":"Country Code"},"type":{"anyOf":[{"enum":["bank","fiscal","employment"],"type":"string"},{"type":"null"}],"default":null,"description":"Institution type.","title":"Type"},"status":{"anyOf":[{"enum":["healthy","down"],"type":"string"},{"type":"null"}],"default":null,"description":"Health status: healthy or down.","title":"Status"},"display_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Partial match on the display name.","title":"Display Name"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the paginated results, starting at 1.","title":"Page"}},"title":"list_institutionsArguments","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_links":{"post":{"operationId":"list_links","summary":"List the links (end-user connections to an institution) with institution, access mode, status, refresh rate and last acc","description":"List the links (end-user connections to an institution) with institution, access mode, status, refresh rate and last access time. Use for \"Which of my Belvo links are invalid and need to be reconnected\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["valid","invalid","unconfirmed","token_required"],"type":"string"},{"type":"null"}],"default":null,"description":"Link status.","title":"Status"},"institution":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Belvo institution name such as ofmockbank_br_retail.","title":"Institution"},"access_mode":{"anyOf":[{"enum":["single","recurrent"],"type":"string"},{"type":"null"}],"default":null,"description":"Access mode.","title":"Access Mode"},"external_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own external ID for the link.","title":"External Id"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the paginated results, starting at 1.","title":"Page"}},"title":"list_linksArguments","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_accounts":{"post":{"operationId":"list_accounts","summary":"List bank accounts (checking, savings, credit card, loan) of a link with category, currency, balances and credit limits.","description":"List bank accounts (checking, savings, credit card, loan) of a link with category, currency, balances and credit limits. Use for \"What are the balances of the accounts on link 1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"link":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only results of this link ID (a connection of one end user to one institution). Recommended for speed.","title":"Link"},"category":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Account category such as CHECKING_ACCOUNT, SAVINGS_ACCOUNT or CREDIT_CARD_ACCOUNT.","title":"Category"},"currency":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Three-letter currency code.","title":"Currency"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the paginated results, starting at 1.","title":"Page"}},"title":"list_accountsArguments","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_transactions":{"post":{"operationId":"list_transactions","summary":"List transactions of a link, filterable by account, type, status and dates, with amount, currency, description and categ","description":"List transactions of a link, filterable by account, type, status and dates, with amount, currency, description and category. Use for \"What did this account spend in the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"link":{"description":"Link ID whose transactions to list (required by Belvo).","maxLength":100,"title":"Link","type":"string"},"account":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only results of this account ID.","title":"Account"},"type":{"anyOf":[{"enum":["INFLOW","OUTFLOW"],"type":"string"},{"type":"null"}],"default":null,"description":"INFLOW or OUTFLOW.","title":"Type"},"status":{"anyOf":[{"enum":["PENDING","PROCESSED","UNCATEGORIZED"],"type":"string"},{"type":"null"}],"default":null,"description":"PENDING, PROCESSED or UNCATEGORIZED.","title":"Status"},"value_date_gte":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions with value date on or after this date, YYYY-MM-DD.","title":"Value Date Gte"},"value_date_lte":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions with value date on or before this date, YYYY-MM-DD.","title":"Value Date Lte"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the paginated results, starting at 1.","title":"Page"}},"required":["link"],"title":"list_transactionsArguments","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_incomes":{"post":{"operationId":"list_incomes","summary":"List income analysis per link: income source type, monthly averages and totals by regularity and confidence. Use for \"Wh","description":"List income analysis per link: income source type, monthly averages and totals by regularity and confidence. Use for \"What is the average monthly income of the user on link 1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"link":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only results of this link ID (a connection of one end user to one institution). Recommended for speed.","title":"Link"},"account":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only results of this account ID.","title":"Account"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the paginated results, starting at 1.","title":"Page"}},"title":"list_incomesArguments","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_recurring_expenses":{"post":{"operationId":"list_recurring_expenses","summary":"List recurring expenses detected in a link's transactions with name, frequency, typical amount and category. Use for \"Wh","description":"List recurring expenses detected in a link's transactions with name, frequency, typical amount and category. Use for \"Which subscriptions and recurring payments does this user have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"link":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only results of this link ID (a connection of one end user to one institution). Recommended for speed.","title":"Link"},"account":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only results of this account ID.","title":"Account"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the paginated results, starting at 1.","title":"Page"}},"title":"list_recurring_expensesArguments","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_risk_insights":{"post":{"operationId":"list_risk_insights","summary":"List risk insight reports of a link: asset, credit card, loan, balance, cashflow and transaction metrics. Use for \"Show ","description":"List risk insight reports of a link: asset, credit card, loan, balance, cashflow and transaction metrics. Use for \"Show the risk insights computed for link 1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"link":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only results of this link ID (a connection of one end user to one institution). Recommended for speed.","title":"Link"},"account":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only results of this account ID.","title":"Account"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the paginated results, starting at 1.","title":"Page"}},"title":"list_risk_insightsArguments","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_br_payment_intents":{"post":{"operationId":"list_br_payment_intents","summary":"List Brazil payment intents (Pix and open finance payment requests) with status, amount, currency and failure details. R","description":"List Brazil payment intents (Pix and open finance payment requests) with status, amount, currency and failure details. Read only. Use for \"Which Belvo payment intents failed this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ordering":{"anyOf":[{"enum":["updated_at","-updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by update time: updated_at (oldest first) or -updated_at (newest first).","title":"Ordering"},"customer":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only intents of this customer ID.","title":"Customer"},"external_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only intents with this external ID.","title":"External Id"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the paginated results, starting at 1.","title":"Page"}},"title":"list_br_payment_intentsArguments","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_br_payment_charges":{"post":{"operationId":"list_br_payment_charges","summary":"List Brazil payment charges with status, amount, currency, payment method type and failure details. Read only. Use for \"","description":"List Brazil payment charges with status, amount, currency, payment method type and failure details. Read only. Use for \"Which Brazil charges are still pending\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Charge status, for example PENDING, FAILED, CANCELED or SCHEDULED.","title":"Status"},"payment_intent":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only charges of this payment intent ID.","title":"Payment Intent"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the paginated results, starting at 1.","title":"Page"}},"title":"list_br_payment_chargesArguments","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}}}}