---
title: "REST API Guide"
description: "Orientation for the BankSync REST API: base URL, authentication, resources, errors, and rate limits by plan."
section: "API"
canonical: "https://banksync.io/docs/api/rest-api"
---

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.

- **RESTful design** — Standard HTTP methods, JSON requests and responses
- **Scoped API keys** — Per-key permission scopes, enforced server-side
- **Full workspace access** — Read data, manage feeds, and trigger syncs

## Base URL

All requests use the same base URL:

```text
https://api.banksync.io/v1
```

## Quick start

**Make your first request**

1. **Create an API key** — In the BankSync app, open Settings > Developers and create a key. Copy the bsk\_ secret when it is shown; it appears only once. See the API keys guide for scopes and expiration.
2. **Authenticate with the X-API-Key header** — Send the key on every request. Keys are bound to one workspace, so no workspace ID header is needed.
3. **List your feeds** — Call GET /feeds to confirm the key works and see your configured feeds.

```bash
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.

> **Keep your API key secure:** 'Never expose your key in client-side code, public repositories, or logs. Store it in an environment variable or a secrets manager. If a key is compromised, revoke it immediately in Settings > Developers and create a new one.'

- [Authentication](/docs/api/authentication): header format, scopes, and request examples in curl, JavaScript, and Python.
- [API keys](/docs/api/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.

- **Financial data** — Transactions, balances, trades, holdings, and loans, fetched live from your connected banks
- **Banks & accounts** — List connected institutions and the accounts under each connection
- **Feeds & jobs** — Read and manage feed configurations, trigger syncs (POST /feeds/:fid/sync), and track job status
- **Enrichments** — Create and manage the Rule, Alert, and Memory enrichments that run during syncs

See [Resources & data types](/docs/api/resources) 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.

| Plan         | API access | Rate limit       |
| ------------ | ---------- | ---------------- |
| Free         | No         | n/a              |
| Starter      | No         | n/a              |
| Standard     | Yes        | 30 requests/min  |
| Professional | Yes        | 150 requests/min |
| Business     | Yes        | 750 requests/min |

When you exceed your limit the API returns `429 Too Many Requests`; back off and retry with exponential delay. 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.

| Code | Meaning                                       |
| ---- | --------------------------------------------- |
| 400  | Bad request: missing fields or invalid format |
| 401  | Missing, invalid, or revoked API key          |
| 403  | Key lacks the required scope                  |
| 404  | Resource not found                            |
| 422  | Feed configuration failed validation          |
| 429  | Rate limit exceeded                           |
| 503  | Bank consent required (reconnect in the app)  |

The [Error handling guide](/docs/api/errors) 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](/docs/mcp/overview).

> **SDKs coming soon:** We're working on official SDKs for Python, Node.js, and other languages. Until then, the API is plain HTTPS + JSON and works with any HTTP client.

[Browse the API reference](/docs/api/reference)

## Related guides

- [Authentication](/docs/api/authentication): how to authenticate every request with `X-API-Key`.
- [API keys](/docs/api/api-keys): create least-privilege keys and rotate them safely.
- [Resources & data types](/docs/api/resources): the data model behind every endpoint.
- [MCP server guide](/docs/mcp/overview): the same data exposed to AI agents over MCP.