Skip to main content
The Breadbox REST API gives you programmatic access to your household’s financial data — accounts, transactions, categories, rules, and more. All endpoints follow a consistent JSON request/response structure, use API key authentication, and return errors in a machine-readable envelope.

​
Base URL

All API endpoints are served relative to your Breadbox host under the /api/v1/ prefix: 
http://your-host:8080/api/v1/
For a local installation the full base URL is typically http://localhost:8080/api/v1/. Replace localhost:8080 with your actual host and port in all examples. The health check and version endpoints are exceptions — they sit outside the versioned prefix:
MethodEndpointAuthDescription
GET/healthNoBasic liveness check — returns 200 if the HTTP server is running
GET/health/liveNoAlias for /health
GET/health/readyNoDeep readiness check — verifies database connectivity and scheduler status
GET/api/v1/versionNoCurrent server version and update availability
curl http://localhost:8080/health

curl http://localhost:8080/health/ready

​
Authentication

Every /api/v1/ endpoint requires an API key passed in the X-API-Key request header. See the Authentication page for full details on key scopes and management. 
X-API-Key: bb_your_api_key_here

​
Response format

All successful responses return JSON with a Content-Type: application/json header. List endpoints wrap results in a data array and include a pagination object. Single-resource endpoints return the object directly. 
{
  "data": [ ... ],
  "next_cursor": "eyJ...",
  "has_more": false
}

​
Error format

Every error response — regardless of HTTP status code — uses the same JSON envelope: 
{
  "error": {
    "code": "UPPER_SNAKE_CASE",
    "message": "Human-readable description of what went wrong."
  }
}
The code field is stable and machine-readable; match against it in client code. The message field is for humans and may change without notice.

​
Error codes

HTTP StatusCodeDescription
400INVALID_PARAMETERA query parameter or request body field has an invalid value, wrong type, or is out of range.
400INVALID_CURSORThe pagination cursor is malformed or has expired.
401MISSING_API_KEYThe X-API-Key header was not provided.
401INVALID_API_KEYThe key is malformed or does not match any active key.
401REVOKED_API_KEYThe key exists but has been revoked.
403FORBIDDENThe key does not have sufficient scope for this operation (e.g., a read_only key calling a write endpoint).
404NOT_FOUNDThe requested resource does not exist.
409SYNC_IN_PROGRESSA sync is already running for the specified connection.
422VALIDATION_ERRORThe request body failed validation.
429RATE_LIMITEDToo many requests.
500INTERNAL_ERRORAn unexpected server-side error occurred. Check server logs.
503DATABASE_UNAVAILABLEThe database connection is not healthy.

​
Amount convention

Breadbox uses the Plaid sign convention for all monetary amounts:
  • Positive amount — money leaving the account (debits, purchases, fees, payments)
  • Negative amount — money entering the account (credits, deposits, refunds)
A grocery purchase of 42.50appearsas‘42.50‘.Adirectdepositof42.50 appears as `42.50`. A direct deposit of 2,500 appears as -2500.00. Every amount field is accompanied by an iso_currency_code field (e.g., "USD"). Never aggregate amounts across different currencies — always filter to a single iso_currency_code before summing.

​
HTTP status codes

CodeMeaning
200 OKRequest succeeded.
202 AcceptedRequest accepted for async processing (e.g., sync trigger).
400 Bad RequestInvalid parameter or cursor.
401 UnauthorizedMissing or invalid API key.
403 ForbiddenKey lacks required scope.
404 Not FoundResource does not exist.
409 ConflictState conflict (e.g., sync already in progress).
422 Unprocessable EntityRequest body validation failed.
500 Internal Server ErrorUnexpected server error.
502 Bad GatewayUpstream provider error (e.g., Plaid returned an error).
503 Service UnavailableDatabase is unreachable.