> ## 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. # Edit a recurring series > **Requires `full_access` scope.** Partial update of a thin series' `name` and/or `type` — any subset may be present, omitted fields are unchanged. Renaming onto an existing live series name is rejected (the name is the series' unique mint key). An empty body is rejected. ## OpenAPI ````yaml https://raw.githubusercontent.com/canalesb93/breadbox/main/openapi.yaml patch /api/v1/series/{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/series/{id}: parameters: - name: id in: path required: true schema: type: string patch: tags: - Series summary: Edit a recurring series description: >- **Requires `full_access` scope.** Partial update of a thin series' `name` and/or `type` — any subset may be present, omitted fields are unchanged. Renaming onto an existing live series name is rejected (the name is the series' unique mint key). An empty body is rejected. requestBody: required: true content: application/json: schema: type: object properties: name: type: string type: type: string enum: - subscription - bill - loan - other responses: '200': description: Updated series. content: application/json: schema: $ref: '#/components/schemas/RecurringSeries' '404': $ref: '#/components/responses/NotFound' components: schemas: RecurringSeries: type: object description: >- A thin, rule-maintained recurring series (subscription/bill/loan). Surrogate identity + name + type; membership comes from `assign_series` rules, not a shipped detector. properties: id: type: string short_id: type: string name: type: string type: type: string description: 'Recurring-charge type: `subscription`|`bill`|`loan`|`other`.' 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: 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. ````