Connections represent the links between Breadbox and your financial institutions. Each connection corresponds to one institution login and may contain multiple accounts. The connections API lets you inspect connection health, check recent sync activity, and trigger manual syncs on demand.
List connections Returns all bank connections in the order they were created.
Auth: ReadQuery parameters Filter to connections belonging to a specific family member. If omitted, all connections are returned.
Response { "data" : [ { "id" : "c9d8e7f6-a5b4-3210-fedc-ba0987654321" , "institution_id" : "ins_3" , "institution_name" : "Chase" , "provider" : "plaid" , "status" : "active" , "error_code" : null , "error_message" : null , "last_synced_at" : "2026-02-28T14:30:00Z" , "last_attempted_sync_at" : "2026-02-28T14:30:00Z" , "accounts_count" : 2 , "user_id" : "u1a2b3c4-d5e6-f789-0abc-def123456789" , "user_name" : "Alex Canales" , "created_at" : "2025-11-01T09:00:00Z" , "updated_at" : "2026-02-28T14:30:00Z" }, { "id" : "d8e9f0a1-b2c3-4567-efab-cd9012345678" , "institution_id" : "ins_11" , "institution_name" : "Bank of America" , "provider" : "plaid" , "status" : "error" , "error_code" : "ITEM_LOGIN_REQUIRED" , "error_message" : "The login details of this item have changed." , "last_synced_at" : "2026-01-15T08:00:00Z" , "last_attempted_sync_at" : "2026-02-28T14:31:00Z" , "accounts_count" : 1 , "user_id" : "u2b3c4d5-e6f7-890a-bcde-f12345678901" , "user_name" : "Jordan Canales" , "created_at" : "2025-12-01T11:00:00Z" , "updated_at" : "2026-02-28T14:31:00Z" } ] }
Connection status values Value Description activeConnection is healthy and syncing normally. Transactions are being imported on schedule. errorThe most recent sync encountered an error. Check error_code and error_message for details. Breadbox will retry on the next scheduled sync. pending_reauthThe institution requires the user to re-authenticate. This is typically triggered by a provider error such as ITEM_LOGIN_REQUIRED. The user must complete re-authentication from the admin dashboard before syncing can resume. disconnectedThe connection has been manually disconnected and is no longer active. Accounts and historical transactions are preserved.
curl -H "X-API-Key: bb_your_key" \ "http://localhost:8080/api/v1/connections"
Get connection status GET /api/v1/connections/{id}/status
Returns detailed health and sync information for a single connection, including the most recent sync log entry.
Auth: ReadPath parameters The connection’s Breadbox UUID or short ID.
Response { "id" : "c9d8e7f6-a5b4-3210-fedc-ba0987654321" , "institution_name" : "Chase" , "provider" : "plaid" , "status" : "active" , "error_code" : null , "error_message" : null , "last_synced_at" : "2026-02-28T14:30:00Z" , "last_attempted_sync_at" : "2026-02-28T14:30:00Z" , "recent_sync" : { "id" : "s1a2b3c4-d5e6-f789-0abc-def123456789" , "trigger" : "cron" , "status" : "success" , "added_count" : 12 , "modified_count" : 2 , "removed_count" : 0 , "error" : null , "started_at" : "2026-02-28T14:29:45Z" , "completed_at" : "2026-02-28T14:30:00Z" } }
The recent_sync object is null if no sync has ever been run for this connection.
curl -H "X-API-Key: bb_your_key" \ "http://localhost:8080/api/v1/connections/c9d8e7f6-a5b4-3210-fedc-ba0987654321/status"
Trigger a manual sync Triggers a manual data sync. The sync runs asynchronously in the background — this endpoint returns immediately with 202 Accepted and does not wait for completion. Use GET /api/v1/connections/{id}/status to poll for results.
Auth: WriteRequest body The request body is optional. If provided, it must be valid JSON.
{ "connection_id" : "c9d8e7f6-a5b4-3210-fedc-ba0987654321" }
The specific connection to sync. If omitted, all active connections are synced sequentially.
Response — 202 Accepted { "message" : "Sync started." , "connection_id" : "c9d8e7f6-a5b4-3210-fedc-ba0987654321" }
When syncing all connections, connection_id is null:
{ "message" : "Sync started for all active connections." , "connection_id" : null }
Sync a specific connection
Sync all connections
curl -X POST \ -H "X-API-Key: bb_your_key" \ -H "Content-Type: application/json" \ -d '{"connection_id": "c9d8e7f6-a5b4-3210-fedc-ba0987654321"}' \ "http://localhost:8080/api/v1/sync"
Connection response fields Breadbox-assigned UUID for the connection.
Provider-assigned institution identifier (e.g., Plaid’s ins_3 for Chase).
Human-readable institution name (e.g., "Chase").
Data provider for this connection. One of: plaid, teller, csv.
Connection health status. One of: active, error, pending_reauth, disconnected.
Machine-readable error code from the last failed sync (e.g., "ITEM_LOGIN_REQUIRED"). null when the connection is healthy.
Human-readable description of the error. null when the connection is healthy.
Timestamp of the most recently completed successful sync. null if the connection has never synced successfully.
Timestamp of the most recently attempted sync, regardless of outcome. null if never attempted.
Number of accounts associated with this connection.
UUID of the family member who owns this connection.
Display name of the owning family member.
The most recent sync log entry. null if no sync has ever run. What triggered the sync: cron, webhook, manual, or initial.
Sync status: in_progress, success, or error.
Number of new transactions imported.
Number of existing transactions updated.
Number of transactions soft-deleted.
Error message when status is error. null on success.
started_at
string (ISO 8601)
required
When the sync began.
When the sync completed. null if still in progress.
Error codes Condition Status Code Missing or invalid API key 401MISSING_API_KEY / INVALID_API_KEYuser_id is not a valid UUID400INVALID_PARAMETERconnection_id is not a valid UUID400INVALID_PARAMETERConnection not found 404NOT_FOUNDSync already in progress for this connection 409SYNC_IN_PROGRESS
