API overview

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 curl snippets throughout this reference use http://localhost:8080 as a stand-in for your Breadbox host. Substitute your real host and port before running them — if you’re exposing Breadbox beyond your local machine, see Remote hosting for guidance on picking a URL.

The health check and version endpoints are exceptions — they sit outside the versioned prefix:

Method	Endpoint	Auth	Description
GET	`/health`	No	Basic liveness check — returns `200` if the HTTP server is running
GET	`/health/live`	No	Alias for `/health`
GET	`/health/ready`	No	Deep readiness check — verifies database connectivity and scheduler status
GET	`/api/v1/version`	No	Current server version and update availability

curl http://localhost:8080/health

{
  "status": "ok",
  "version": "0.5.0"
}

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

{
  "status": "ok",
  "db": "ok",
  "scheduler": "running",
  "version": "0.5.0"
}

{
  "status": "degraded",
  "db": "error",
  "db_error": "connection refused",
  "scheduler": "running",
  "version": "0.5.0"
}

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 use one of two shapes depending on whether the endpoint is cursor-paginated:

Small, finite lists (GET /accounts, GET /categories, GET /connections, GET /users, GET /reports) return a top-level JSON array. No pagination is applied — all matching records fit in a single response.
[ { "id": "...", "short_id": "...", "..." : "..." } ]
Cursor-paginated lists (GET /transactions, GET /rules) wrap results in a resource-named array alongside next_cursor and has_more. See Pagination for the full iteration contract.
{ "transactions": [ ... ], "next_cursor": "eyJ...", "has_more": false }

Single-resource endpoints return the object directly.

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 Status	Code	Description
`400`	`INVALID_PARAMETER`	A query parameter or request body field has an invalid value, wrong type, or is out of range.
`400`	`INVALID_CURSOR`	The pagination cursor is malformed or has expired.
`401`	`MISSING_API_KEY`	The `X-API-Key` header was not provided.
`401`	`INVALID_API_KEY`	The key is malformed or does not match any active key.
`401`	`REVOKED_API_KEY`	The key exists but has been revoked.
`403`	`FORBIDDEN`	The key does not have sufficient scope for this operation (e.g., a `read_only` key calling a write endpoint).
`404`	`NOT_FOUND`	The requested resource does not exist.
`409`	`SYNC_IN_PROGRESS`	A sync is already running for the specified connection.
`422`	`VALIDATION_ERROR`	The request body failed validation.
`429`	`RATE_LIMITED`	Too many requests.
`500`	`INTERNAL_ERROR`	An unexpected server-side error occurred. Check server logs.
`503`	`DATABASE_UNAVAILABLE`	The 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.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

Code	Meaning
`200 OK`	Request succeeded.
`202 Accepted`	Request accepted for async processing (e.g., sync trigger).
`400 Bad Request`	Invalid parameter or cursor.
`401 Unauthorized`	Missing or invalid API key.
`403 Forbidden`	Key lacks required scope.
`404 Not Found`	Resource does not exist.
`409 Conflict`	State conflict (e.g., sync already in progress).
`422 Unprocessable Entity`	Request body validation failed.
`500 Internal Server Error`	Unexpected server error.
`502 Bad Gateway`	Upstream provider error (e.g., Plaid returned an error).
`503 Service Unavailable`	Database is unreachable.

Overview

Endpoints

Base URL

Authentication

Response format

Error format

Error codes

Amount convention

HTTP status codes

​Base URL

​Authentication

​Response format

​Error format

​Error codes

​Amount convention

​HTTP status codes

Base URL

Authentication

Response format

Error format

Error codes

Amount convention

HTTP status codes