Wallet API Reference

Base URL: https://rest.budgetbakers.com/wallet

Full Specification: OpenAPI (Swagger UI) — all endpoints, schemas, and interactive testing

All endpoints require an API token, obtained in the Web app (Premium plan required):

Authorization: Bearer <your_api_token>

All User Data endpoints support pagination:

Response includes nextOffset when more results are available.

API uses the Token Bucket Rate limiting algorithm, which allows short bursts of requests while enforcing an average rate over time.

• Capacity: 400 requests/hour per client
• Exceeding limit returns 429 Too Many Requests

Text Filters

Use prefix operators to filter text fields (e.g. note, payee fields).

Text filters can be specified up to 2 times for AND logic. E.g. note=contains-i.grocery&note=contains-i.market

Range Filters

Used for numeric properties (e.g. amount) and datetime fields (recordDate, createdAt).

Date-only values

When date-only values (no time component) are provided, whole-day (in UTC) semantics apply.:

Range filters support up to 2 conditions (AND logic) using repeated parameters:

• amount=gte.100&amount=lte.500
• recordDate=gte.2024-01-01&recordDate=lt.2024-02-01

Comma-separated syntax is also accepted: amount=gte.100,lte.500

User data is synchronized from Wallet app. Changes made in the app may not appear immediately via API.

Initial Sync

Synchronization begins when you generate your first API key. Until the initial sync completes, requests return 409 Conflict:

{
  "error": "init_sync_in_progress",
  "message": "Data synchronization in progress. Please retry later.",
  "retry_after_minutes": 5
}

Ongoing Sync

After initial sync, data is always returned, but recent changes in user data may not appear immediately. These response headers indicate sync status:

Advisory information for AI agents. Hints can provide context about results, pagination, and rate limits.

Enable: Add agentHints=true to any request.

Batch Semantics & Partial Success

Most write endpoints accept arrays of items in a single request. Batch sizes are intentionally small to keep operations predictable.

Due to technical limitations, batch operations are not atomic. Each item is processed independently — a single request can partially succeed. When a batch contains mixed results, the response uses HTTP 207:

If all items succeed, the response is HTTP 200. Use validation=strict in PATCH requests to reject unknown fields instead of silently ignoring them.

Creating Records

POST /records — up to 20 records per request. Maximum 20,000 records per user (includes records created in mobile/web apps).

Transfer records cannot be created via the API. Transfer pairs created in the mobile app are partially patchable (metadata only) and must be deleted as a pair.

Patching Records

PATCH /records — up to 10 records per request. At least one field must be provided.

* Fields marked with * are locked on bank-synced accounts and transfer records. Attempting to patch them returns a client_error. Metadata fields (note, labels, category, paymentType, counterParty) can always be patched.

Creating Accounts

POST /accounts — single account per request. Maximum 50 accounts per user (includes accounts created in mobile/web apps).

Patching Accounts

PATCH /accounts — up to 10 per request.

Bank-synced accounts cannot be patched via the API. Use the mobile app to manage them.

Account deletion is not currently supported via the API.

Custom Categories

Custom categories are always derived from a base (system) category via parentId. Create them for highly specific purposes that don't fit into existing base categories (e.g. "Subscriptions" under "Entertainment").

POST /categories/custom — single category per request. Maximum 50 custom categories per user (includes categories created in mobile/web apps).

Restricted System Categories

The following internal system categories cannot be assigned to records and cannot be used as parentId for custom categories:

Patching Categories

PATCH /categories — up to 10 per request. Works on both base and custom categories.

Deleting categories: Only custom categories can be deleted. The category must have no references from records, budgets, standing orders, or record rules. Use GET /{type}/references?id=... to check before deleting.

Creating Budgets

POST /budgets — single budget per request. Maximum 50 budgets per user (includes budgets created in mobile/web apps).

Patching budgets is currently disabled.

Deleting budgets is supported. Budgets have no child references, so they can always be deleted.

DELETE /v1/api/{type} — up to 10 IDs per request.

Pre-check references before deleting categories and records: GET /v1/api/{type}/references?id=uuid1,uuid2 (max 10 IDs). The response shows which entities reference the given IDs. If references exist, the delete will fail with a client_error for that item.