> ## Documentation Index > Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Setup readiness report > Returns a one-shot readiness/setup summary intended for the `breadbox doctor` CLI command. Any API key (read or write) works. Fields are best-effort — a per-row failure stays zero and the report still ships. The endpoint returns 503 only when the database is plainly unreachable. ## OpenAPI ````yaml https://raw.githubusercontent.com/canalesb93/breadbox/main/openapi.yaml get /api/v1/headless/bootstrap openapi: 3.1.0 info: title: Breadbox REST API version: 1.0.0 summary: Self-hosted financial-data REST API for households and AI agents. description: > Machine-readable contract for the Breadbox REST API. Every `/api/v1/*` endpoint declared on the production chi router is represented here. The companion prose document at `docs/api-reference.md` may lag this spec; when in doubt, this file is canonical. ## Authentication All `/api/v1/*` endpoints require an API key passed via the `X-API-Key` header. Keys carry one of two scopes: - `read_only` — may call any read endpoint (`GET`). - `full_access` — may call read endpoints **and** all write endpoints (`POST`, `PATCH`, `PUT`, `DELETE`, plus a handful of `GET`s like `/api-keys` and `/users/{user_id}/login` that return sensitive data). Endpoints requiring `full_access` are flagged with the phrase **Requires `full_access` scope.** in their description. OpenAPI does not natively distinguish scopes on a single API-key scheme, so the enforcement boundary is documented per-operation rather than encoded in the security block. ## Amount convention Transaction amounts use `NUMERIC(12,2)` and are paired with `iso_currency_code`. Positive = money out (debits, purchases, fees). Negative = money in (credits, deposits, refunds). Never sum across `iso_currency_code`. ## Identifiers Every entity has both a UUID `id` and an 8-character base62 `short_id`. REST responses include both. Path parameters that accept `{id}` accept either form; short IDs are usually preferable for humans. ## Pagination Cursor pagination is used on transaction-shaped lists. Pass the previous response's `next_cursor` as `?cursor=` to fetch the next page. Bounded resources (accounts, users, connections, categories) return bare arrays. ## Errors All error responses share the envelope `{ "error": { "code": "...", "message": "..." } }`. Codes are stable contracts in `UPPER_SNAKE_CASE`. contact: name: Breadbox url: https://breadbox.sh license: name: AGPL-3.0-only url: https://www.gnu.org/licenses/agpl-3.0.html servers: - url: https://breadbox.example.com description: Self-hosted Breadbox instance (replace host with your deployment). security: - apiKeyAuth: [] tags: - name: Health description: Liveness and readiness probes. No authentication. - name: Version description: Server version metadata. - name: Auth description: Device-code grant and the unauthenticated headless bootstrap probe. - name: Accounts description: Household bank accounts synced from providers. - name: Transactions description: Cursor-paginated transactions, counts, summaries, and merchant rollups. - name: Comments description: Conversation comments attached to a transaction. - name: Annotations description: >- Activity-timeline events for a transaction (category changes, comments, tags, system events). - name: Tags description: Free-form labels applied to transactions. - name: Categories description: Two-level category tree, import/export, and merges. - name: Connections description: >- Bank-side links (Plaid items, Teller enrollments, CSV-import buckets) and the hosted-link page that mints them. - name: Sync description: Manual sync triggers, sync history, and per-provider health. - name: Rules description: Categorization rule engine with retroactive apply and preview. - name: Account Links description: >- Dependent-to-primary reconciliation links and transaction match management. - name: Reports description: Agent-submitted reports and the household read/unread state. - name: Users description: Household members and the login accounts attached to them. - name: API Keys description: Scoped credentials for REST and MCP clients. - name: Settings description: Provider credentials and other app-config knobs. - name: Counterparties description: >- The canonical, cross-provider "other side" of a charge (merchants and non-merchants), with manual enrichment. - name: Workflows description: >- Scheduled Claude Agent SDK definitions, run history, transcripts, and prompt blocks. - name: Webhooks description: Stored webhook events and on-demand replay. paths: /api/v1/headless/bootstrap: get: tags: - Health summary: Setup readiness report description: | Returns a one-shot readiness/setup summary intended for the `breadbox doctor` CLI command. Any API key (read or write) works. Fields are best-effort — a per-row failure stays zero and the report still ships. The endpoint returns 503 only when the database is plainly unreachable. responses: '200': description: Bootstrap report. content: application/json: schema: $ref: '#/components/schemas/HeadlessBootstrapResponse' '401': $ref: '#/components/responses/Unauthorized' '503': description: Database is not reachable; partial report in body. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: HeadlessBootstrapResponse: type: object description: Readiness/setup summary consumed by `breadbox doctor`. required: - version - encryption_key_set - database - providers - users_count - login_accounts_count - api_keys_count - active_connections_count - scheduler_running - first_run properties: version: type: string description: Server build version. encryption_key_set: type: boolean description: True when ENCRYPTION_KEY is set. database: type: object required: - connected - migrations_current - migration_version properties: connected: type: boolean migrations_current: type: boolean description: >- True when the applied goose version meets or exceeds the highest embedded migration. migration_version: type: integer format: int64 description: Highest version_id applied in goose_db_version (0 if unread). providers: type: array description: Provider configuration status. Order is stable (plaid, teller). items: type: object required: - name - configured properties: name: type: string enum: - plaid - teller configured: type: boolean env: type: string description: >- Environment label (e.g. sandbox, production). Omitted when not configured. users_count: type: integer format: int64 description: Household user count. login_accounts_count: type: integer format: int64 description: Admin / dashboard login account count. api_keys_count: type: integer format: int64 description: Active (un-revoked) API key count. active_connections_count: type: integer format: int64 description: Bank connections in 'active' status. scheduler_running: type: boolean description: True when the sync scheduler has active cron entries. first_run: type: boolean description: >- True when `login_accounts_count == 0` — the same signal used by the admin first-run redirect. ErrorEnvelope: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable UPPER_SNAKE_CASE error code. message: type: string responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key description: | Breadbox API key with format `bb_`. Carries either `read_only` or `full_access` scope. Write endpoints (and a handful of sensitive reads — `/api-keys`, `/users/{user_id}/login`) require `full_access`; endpoints that require it are flagged in their description. ````