> ## 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. # List transactions > Filterable, cursor-paginated transaction query. ## OpenAPI ````yaml https://raw.githubusercontent.com/canalesb93/breadbox/main/openapi.yaml get /api/v1/transactions 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/transactions: get: tags: - Transactions summary: List transactions description: Filterable, cursor-paginated transaction query. parameters: - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Fields' - name: account_id in: query schema: type: string description: Filter by account UUID or short_id (repeatable). - name: connection_id in: query schema: type: string description: Filter by connection. - name: user_id in: query schema: type: string description: >- Filter by attributed user (uses `COALESCE(attributed_user_id, connection.user_id)`). - name: category_id in: query schema: type: string description: Filter by category. - name: tag in: query schema: type: string description: Filter by tag slug. - name: search in: query schema: type: string description: >- Substring/word/fuzzy search on name + merchant_name. Comma-separated values are OR'd. - name: search_mode in: query schema: type: string enum: - contains - words - fuzzy description: Search algorithm. - name: exclude_search in: query schema: type: string description: Negative search filter (NOT ILIKE). Min 2 chars. - name: date_from in: query schema: type: string format: date - name: date_to in: query schema: type: string format: date - name: amount_min in: query schema: type: number - name: amount_max in: query schema: type: number - name: pending in: query schema: type: boolean - name: flagged in: query schema: type: boolean description: Filter to flagged (true) or unflagged (false) transactions. - name: deleted in: query schema: type: string enum: - include - only description: Whether to include or restrict to soft-deleted transactions. responses: '200': description: Paginated transaction list. content: application/json: schema: $ref: '#/components/schemas/TransactionListResponse' '400': $ref: '#/components/responses/BadRequest' components: parameters: Cursor: name: cursor in: query required: false description: Opaque pagination cursor returned by a previous list response. schema: type: string Limit: name: limit in: query required: false description: Page size (default 50, capped per-endpoint). schema: type: integer minimum: 1 maximum: 200 Fields: name: fields in: query required: false description: | Comma-separated field selector. Accepts column names and aliases (`minimal`, `core`, `category`, `timestamps`, `triage`, `review_core`, `transaction_core`). `id` and `short_id` are always included. schema: type: string schemas: TransactionListResponse: type: object properties: transactions: type: array items: $ref: '#/components/schemas/Transaction' next_cursor: type: string nullable: true has_more: type: boolean limit: type: integer Transaction: type: object properties: id: type: string format: uuid short_id: type: string account_id: type: string connection_id: type: string nullable: true attributed_user_id: type: string nullable: true date: type: string format: date authorized_date: type: string format: date nullable: true amount: type: string description: Decimal as string. Positive = money out, negative = money in. iso_currency_code: type: string name: type: string merchant_name: type: string nullable: true counterparty_short_id: type: string nullable: true description: >- short_id of the assigned counterparty (the other side of the transaction), null when unassigned. counterparty_name: type: string nullable: true description: >- Preferred display name when a counterparty is assigned; falls back to merchant_name then name. counterparty_logo_url: type: string nullable: true description: Counterparty logo URL; null until enrichment populates it. category_id: type: string nullable: true pending: type: boolean deleted_at: type: string format: date-time nullable: true tags: type: array items: type: string description: Tag slug. metadata: type: object additionalProperties: true description: >- Free-form JSONB enrichment store. Always an object (empty `{}` when unset). flagged_at: type: string format: date-time nullable: true description: >- When the transaction was flagged for human attention; null when not flagged. The reason lives in a comment annotation. created_at: type: string format: date-time updated_at: type: string format: date-time additionalProperties: true 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: BadRequest: description: Invalid input. 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. ````