> ## 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. # Poll a hosted-link session > Returns the current state of a hosted-link session. Accepts either the canonical UUID or the 8-char short_id as `{id}`. The plaintext bearer `token` and the constructed `url` are returned **only** at creation time — this poll endpoint omits them. Use `result_connection_ids` (always present, possibly empty) to find the connections the user added during the session once `status` reaches `completed`. Status values: `pending`, `active`, `completed`, `failed`, `expired`. ## OpenAPI ````yaml https://raw.githubusercontent.com/canalesb93/breadbox/main/openapi.yaml get /api/v1/connections/link/{id} 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/connections/link/{id}: parameters: - $ref: '#/components/parameters/IDPath' get: tags: - Connections summary: Poll a hosted-link session description: | Returns the current state of a hosted-link session. Accepts either the canonical UUID or the 8-char short_id as `{id}`. The plaintext bearer `token` and the constructed `url` are returned **only** at creation time — this poll endpoint omits them. Use `result_connection_ids` (always present, possibly empty) to find the connections the user added during the session once `status` reaches `completed`. Status values: `pending`, `active`, `completed`, `failed`, `expired`. responses: '200': description: Hosted-link session. content: application/json: schema: $ref: '#/components/schemas/HostedLinkSession' '404': $ref: '#/components/responses/NotFound' components: parameters: IDPath: name: id in: path required: true description: UUID or 8-char short_id. schema: type: string schemas: HostedLinkSession: type: object description: | A hosted-link session is the agent-facing record of a "share this URL with the user so they can connect a bank in their browser" flow. Returned by `GET /connections/link/{id}` and (extended with `token` and `url`) by `POST /connections/link`. properties: id: type: string short_id: type: string user_id: type: string provider: type: string description: | `"plaid"`, `"teller"`, or empty string. Empty means the hosted page shows a picker so the user chooses a provider. enum: - '' - plaid - teller action: type: string enum: - link - relink connection_id: type: string description: >- Present only for `action: "relink"` — the connection being re-authenticated. single_use: type: boolean redirect_url: type: string description: Optional URL the hosted page redirects to after completion. label: type: string description: Optional human-readable label shown in the agent's audit timeline. status: type: string enum: - pending - active - completed - failed - expired - consumed error_code: type: string description: 'Present only on `status: "failed"`.' error_message: type: string description: 'Present only on `status: "failed"`.' result_connection_ids: type: array items: type: string description: | UUIDs of the bank connections the user added during the session. Always present; empty array until at least one connection has been recorded. expires_at: type: string format: date-time started_at: type: string format: date-time nullable: true description: >- Stamped when the hosted page first transitions the session to `active`. completed_at: type: string format: date-time nullable: true description: Stamped when the session reaches `completed` or `failed`. created_at: type: string format: date-time 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: NotFound: description: Resource not found. 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. ````