REST API Guide

The BankSync REST API gives you programmatic access to everything in your workspace: banks, accounts, transactions, balances, investments, loans, feeds, sync jobs, and enrichments. Use it to build custom integrations, automate reporting, or wire BankSync into your own application.

This page is the orientation map. Each topic links to a focused guide, and every endpoint is documented in the generated API reference.

Base URL#

All requests use the same base URL:

https://api.banksync.io/v1

Quick start#

curl -X GET "https://api.banksync.io/v1/feeds" \  -H "X-API-Key: bsk_your_api_key_here"

A 200 OK with a JSON body means you are authenticated and correctly scoped.

Authentication#

Every request requires your API key in the X-API-Key header. Keys carry resource:action scopes (for example feeds:read, jobs:write) that you choose at creation, so each integration gets exactly the access it needs.

• Authentication: header format, scopes, and request examples in curl, JavaScript, and Python.
• API keys: creating, scoping, rotating, and revoking keys.

Resources#

Everything hangs off your workspace. Banks contain accounts; accounts expose transactions, balances, trades, holdings, and loans; feeds move that data to your connected apps and produce jobs each time they run.

See Resources & data types for the full hierarchy, key fields per resource, pagination, and sync modes, or browse every endpoint in the API reference.

Rate limits#

API throughput is set by your workspace plan. Free and Starter do not include REST API access with an API key.

How requests are counted:

• Per workspace. The limit is one budget shared by every API key and installed app in the workspace. It is not per key or per endpoint.
• Every /v1 request counts. Listing banks or accounts, reading transactions, GET /v1/whoami, and requests that later fail (a 404, say) count the same as any other. Only requests rejected for a missing or invalid credential aren't counted.
• Refused requests count too. A client that keeps retrying immediately after a 429 keeps its own budget used up. Wait for Retry-After before sending again.
• Over a rolling 60-second period. Limits are enforced at the edge and are approximate across locations, so you may sometimes get a little more than the table shows. Design for the number in the table, not above it.
• Scheduled syncs don't count. Feeds that sync on a schedule run inside BankSync and never use your API budget.
• Installed apps. An app's requests count toward the same workspace budget. An app installed on a Free or Starter workspace can still use the API there at the Standard rate.

When you exceed your limit the API returns 429 Too Many Requests with these headers:

There is no remaining-count header.

Polling many accounts#

Transactions are read one account at a time, so a full polling pass costs one request per bank to list its accounts plus one request per account. A workspace with 4 banks and 13 accounts needs 17 requests per pass. Sent back to back, that is more than Standard's 10 per minute, so part of the pass is refused.

Either of these patterns fixes it:

• Pace the pass. Space requests at least 60 / limit seconds apart, plus a little margin: about 7 seconds on Standard, 3.5 on Professional, 2.5 on Business. The 17-request pass above then finishes in about two minutes with no refusals.
• Resume after a 429. When a request is refused, wait the Retry-After seconds, then retry that same request and carry on with the rest of the pass. Don't abandon the pass, and don't start it again from the beginning.

To keep each pass small, list banks and accounts once and cache the IDs instead of re-listing them every poll. Use from/to to fetch only the recent date range you need, and page with cursor. If you consistently need more headroom, upgrade your plan or contact support.

Error handling#

The API uses conventional HTTP status codes and returns structured JSON errors with a success: false flag and a human-readable error message.

The Error handling guide covers the response format, validation errors, and a troubleshooting walkthrough for each code.

AI agents instead of code?#

If you want an AI assistant (Claude, Cursor, ChatGPT, and others) to work with your BankSync data rather than writing HTTP calls yourself, use the hosted MCP server at https://mcp.banksync.io. It authenticates with the same API keys. See the MCP server guide.

Related guides#

• Authentication: how to authenticate every request with X-API-Key.
• API keys: create least-privilege keys and rotate them safely.
• Resources & data types: the data model behind every endpoint.
• MCP server guide: the same data exposed to AI agents over MCP.