@warmio/contracts 1.0.0

package/dist/openapi/base.yaml

@@ -0,0 +1,1679 @@
+openapi: 3.1.0
+info:
+  title: Warm API
+  description: |
+    Read your financial context or invoke supported Warm actions through a compact operation catalog.
+
+    ## Authentication
+    All requests use `Authorization: Bearer`. API keys are created for either read-only context
+    access or automation access in Settings on paid Warm plans.
+
+    Read/export routes accept `Authorization: Bearer YOUR_API_KEY_OR_ACCESS_TOKEN`.
+    Automation routes require an automation key (`warm_auto_...`) and do not accept access tokens.
+
+    Unauthenticated responses include `WWW-Authenticate` guidance and protected resource metadata.
+
+    ## Rate Limits
+    - Context keys: 200 requests per hour per key
+    - Automation keys: 500 requests per hour per key
+    - Rate limit headers included in authenticated responses
+    - `/api/export` supports dataset-scoped delta sync with `since` and publishes edge-cache metadata headers
+  version: '2.0.0'
+  contact:
+    name: Warm Support
+    url: https://warm.io/support
+  license:
+    name: Proprietary
+    url: https://warm.io/terms
+
+servers:
+  - url: https://app.warm.io
+    description: Production
+
+security:
+  - BearerAuth: []
+
+paths:
+  /api/verify:
+    get:
+      operationId: verifyApiAccess
+      summary: Verify API credentials
+      description: |
+        Validate a Warm API key or signed-in user access token against the public verification route.
+
+        This endpoint is the canonical readiness check for public API clients and discovery tools.
+      tags:
+        - Verification
+      responses:
+        '200':
+          description: Credentials are valid and the caller has API access
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - status
+                  - valid
+                  - auth
+                properties:
+                  status:
+                    type: string
+                    enum: [ok]
+                  valid:
+                    type: boolean
+                  auth:
+                    type: string
+                    description: Auth method used to satisfy verification
+                  audience:
+                    type: string
+                    enum: [context, automation, oauth]
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+
+  /api/export:
+    get:
+      operationId: getDatasetExport
+      summary: Get a typed dataset export
+      description: |
+        Fetch a canonical financial dataset export from the unified `/api/export` surface.
+
+        Use `dataset=transactions` for paginated transaction history. Other datasets return
+        a typed JSON object keyed by the dataset name or retained public alias.
+
+        Preferred dataset names are `accounts`, `transactions`, `snapshots`, `recurring`,
+        `budgets`, `goals`, `health`, `liabilities`, and `holdings`.
+      tags:
+        - Export
+      parameters:
+        - name: dataset
+          in: query
+          description: Dataset identifier or retained public alias
+          required: true
+          schema:
+            type: string
+            enum:
+              - accounts
+              - transactions
+              - snapshots
+              - recurring
+              - budgets
+              - goals
+              - health
+              - liabilities
+              - holdings
+        - name: since
+          in: query
+          description: ISO timestamp for incremental exports
+          required: false
+          schema:
+            type: string
+            format: date-time
+        - name: last_knowledge
+          in: query
+          description: Legacy alias for `since`
+          required: false
+          schema:
+            type: string
+            format: date-time
+        - name: limit
+          in: query
+          description: Maximum transactions per page when `dataset=transactions`
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+        - name: cursor
+          in: query
+          description: Pagination token from `pagination.next_cursor` when `dataset=transactions`
+          required: false
+          schema:
+            type: string
+        - name: accountId
+          in: query
+          description: Optional account filter when `dataset=transactions`
+          required: false
+          schema:
+            type: string
+        - name: search
+          in: query
+          description: Optional merchant or description search filter when `dataset=transactions`
+          required: false
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 120
+      responses:
+        '200':
+          description: Successful dataset export
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Dataset-shaped JSON response keyed by the requested dataset
+                properties:
+                  generated_at:
+                    type: string
+                    format: date-time
+                  next_knowledge:
+                    type: string
+                    format: date-time
+                    nullable: true
+                  pagination:
+                    $ref: '#/components/schemas/Pagination'
+                additionalProperties: true
+        '400':
+          description: Invalid query parameters
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+
+  /api/financial-context:
+    get:
+      operationId: getFinancialContext
+      summary: Get compact financial context
+      description: |
+        Fetch the current compact FinancialContext artifact for the authenticated user.
+
+        This response does not include transaction items. Use
+        `/api/financial-context/transactions` for month-addressed transaction pages or the
+        fixed 10-day latest transaction window.
+      tags:
+        - Export
+      responses:
+        '200':
+          description: Compact FinancialContext artifact
+          headers:
+            ETag:
+              $ref: '#/components/headers/ETag'
+            Cache-Control:
+              $ref: '#/components/headers/PrivateNoStore'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FinancialContext'
+        '304':
+          description: The caller's If-None-Match value matches the current content hash
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '413':
+          $ref: '#/components/responses/PayloadTooLarge'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+
+  /api/financial-context/transactions:
+    get:
+      operationId: getFinancialContextTransactions
+      summary: Get financial-context transactions
+      description: |
+        Fetch one transaction month or the fixed 10-day latest transaction window from the
+        current financial-context artifact.
+
+        The raw API requires exactly one selector: `month=YYYY-MM` or `latest=1`.
+        Bare calls are invalid on the raw API. The `@warmio/mcp` v7 `get_transactions` tool
+        maps bare calls to the fixed latest window and accepts only `month` (`YYYY-MM`) or
+        `latest: true`; it does not accept cursor, search, or `last_knowledge`.
+        Transaction amounts use the Warm/Plaid sign convention:
+        positive = expense/debit, negative = income/credit.
+
+        A well-formed month inside the covered range with no matching items returns `200` with
+        `count: 0` and `items: []`. Months before the earliest indexed month or after the latest
+        covered month return `404`.
+      tags:
+        - Export
+      parameters:
+        - name: month
+          in: query
+          description: Transaction month selector in YYYY-MM format. Mutually exclusive with `latest`.
+          required: false
+          schema:
+            type: string
+            pattern: '^\d{4}-(0[1-9]|1[0-2])$'
+            example: '2026-07'
+        - name: latest
+          in: query
+          description: Set to `1` for the fixed 10-day latest transaction window.
+          required: false
+          schema:
+            type: string
+            enum: ['1']
+      responses:
+        '200':
+          description: Transaction month page or latest transaction window
+          headers:
+            ETag:
+              $ref: '#/components/headers/ETag'
+            Cache-Control:
+              $ref: '#/components/headers/PrivateNoStore'
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/TransactionMonth'
+                  - $ref: '#/components/schemas/LatestTransactions'
+        '304':
+          description: The caller's If-None-Match value matches the current content hash
+        '400':
+          description: Missing selectors, mutually exclusive selectors, malformed `month`, or `latest` other than `1`
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '413':
+          $ref: '#/components/responses/PayloadTooLarge'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+
+  /api/financial-context/meta:
+    get:
+      operationId: getFinancialContextMeta
+      summary: Get financial-context metadata
+      description: |
+        Fetch operational metadata for the current financial-context artifact, including the
+        content hash used as the ETag, byte length, row counts, and freshness timestamps.
+        `content_hash` is the public artifact version token; this metadata does not expose a
+        public `data_version`.
+      tags:
+        - Export
+      responses:
+        '200':
+          description: Financial-context metadata
+          headers:
+            ETag:
+              $ref: '#/components/headers/ETag'
+            Cache-Control:
+              $ref: '#/components/headers/PrivateNoStore'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FinancialContextMeta'
+        '304':
+          description: The caller's If-None-Match value matches the current content hash
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '413':
+          $ref: '#/components/responses/PayloadTooLarge'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+
+  /api/automation/operations/search:
+    post:
+      operationId: searchOperations
+      summary: Search supported automation operations
+      tags: [Automation]
+      security:
+        - AutomationKeyAuth: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              properties:
+                query:
+                  type: string
+                  maxLength: 200
+      responses:
+        '200':
+          description: Matching operations
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required: [operations]
+                properties:
+                  operations:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/AutomationOperation'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/automation/operations/describe:
+    post:
+      operationId: describeOperation
+      summary: Describe one operation and request owner approval when required
+      tags: [Automation]
+      security:
+        - AutomationKeyAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OperationRequest'
+      responses:
+        '200':
+          description: Operation schema and optional pending owner approval
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required: [operation]
+                properties:
+                  operation:
+                    allOf:
+                      - $ref: '#/components/schemas/AutomationOperation'
+                      - type: object
+                        properties:
+                          input_schema:
+                            type: object
+                  approval:
+                    type: object
+                    additionalProperties: false
+                    required: [id, status, approval_url, expires_at]
+                    properties:
+                      id: { type: string, format: uuid }
+                      status: { type: string, enum: [pending] }
+                      approval_url: { type: string, format: uri }
+                      expires_at: { type: string, format: date-time }
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/automation/operations/invoke:
+    post:
+      operationId: invokeOperation
+      summary: Invoke one supported operation
+      tags: [Automation]
+      security:
+        - AutomationKeyAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OperationInvokeRequest'
+      responses:
+        '200':
+          description: Wrapped response from the invoked operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AutomationInvocationResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: Owner approval is required, invalid, expired, or already used
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      description: 'Read/export format: `Authorization: Bearer YOUR_API_KEY_OR_ACCESS_TOKEN`'
+    AutomationKeyAuth:
+      type: http
+      scheme: bearer
+      description: 'Automation format: `Authorization: Bearer warm_auto_...`'
+
+  headers:
+    ETag:
+      description: Quoted content hash for If-None-Match revalidation
+      schema:
+        type: string
+        example: '"7b6f9d4c..."'
+    PrivateNoStore:
+      description: Private financial responses are not stored by browsers or shared caches
+      schema:
+        type: string
+        example: private, no-store
+
+  responses:
+    BadRequest:
+      description: The request body or operation input is invalid
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Unauthorized:
+      description: Missing or invalid credentials
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Forbidden:
+      description: The caller is authenticated but does not have API access
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    NotFound:
+      description: The requested operation does not exist
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    InternalError:
+      description: The request could not be completed safely
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    PayloadTooLarge:
+      description: The response would exceed the public API response-size limit
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    RateLimited:
+      description: Hourly per-credential rate limit exceeded
+      headers:
+        Retry-After:
+          description: Seconds until the rate-limit window resets
+          schema:
+            type: integer
+            example: 3600
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+
+  schemas:
+    AutomationOperation:
+      type: object
+      additionalProperties: false
+      required: [operation_id, summary, description, method, path, risk, confirmation_required]
+      properties:
+        operation_id: { type: string }
+        summary: { type: string }
+        description: { type: string }
+        method: { type: string, enum: [GET, POST, PATCH, PUT, DELETE] }
+        path: { type: string }
+        risk:
+          type: array
+          items: { type: string, enum: [read, write, destructive, external_effect] }
+        confirmation_required: { type: boolean }
+    OperationRequest:
+      type: object
+      additionalProperties: false
+      required: [operation_id]
+      properties:
+        operation_id: { type: string }
+        input:
+          $ref: '#/components/schemas/OperationInput'
+    OperationInvokeRequest:
+      type: object
+      additionalProperties: false
+      required: [operation_id]
+      properties:
+        operation_id: { type: string }
+        input:
+          $ref: '#/components/schemas/OperationInput'
+        approval_id:
+          type: string
+          format: uuid
+          description: Matching owner approval required for every write operation
+    OperationInput:
+      type: object
+      additionalProperties: false
+      properties:
+        params: { type: object, additionalProperties: { type: string } }
+        body: { type: object, additionalProperties: true }
+    AutomationInvocationResponse:
+      type: object
+      additionalProperties: false
+      required: [body, headers, operation_id, status]
+      properties:
+        body: {}
+        headers:
+          type: object
+          additionalProperties: { type: string }
+        operation_id: { type: string }
+        status: { type: integer, minimum: 100, maximum: 599 }
+    ExportResponse:
+      type: object
+      required:
+        - schema_version
+        - generated_at
+        - user_id
+        - data_version
+        - next_knowledge
+        - accounts
+        - transactions
+        - snapshots
+        - pagination
+      properties:
+        schema_version:
+          type: string
+          description: API schema version
+          example: v1
+        generated_at:
+          type: string
+          format: date-time
+          description: Response generation timestamp
+          example: '2026-01-10T15:30:00Z'
+        user_id:
+          type: string
+          format: uuid
+          description: Your user ID
+          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+        data_version:
+          type: integer
+          description: Monotonic version number (increments on data changes)
+          example: 42
+        next_knowledge:
+          type: string
+          format: date-time
+          description: Use as `last_knowledge` in next request for delta sync
+          example: '2026-01-10T15:30:00Z'
+        accounts:
+          type: array
+          items:
+            $ref: '#/components/schemas/Account'
+        transactions:
+          type: array
+          items:
+            $ref: '#/components/schemas/Transaction'
+        snapshots:
+          type: array
+          items:
+            $ref: '#/components/schemas/Snapshot'
+        pagination:
+          $ref: '#/components/schemas/Pagination'
+
+    Account:
+      type: object
+      required:
+        - id
+        - name
+        - type
+        - current_balance
+        - iso_currency_code
+        - is_active
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique account identifier
+          example: acc_8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
+        account_id:
+          type: string
+          description: External account ID (from Plaid)
+          example: plaid_acc_ABC123xyz
+        name:
+          type: string
+          description: Display name with masked account number
+          example: 'Checking ****1234'
+        type:
+          type: string
+          enum: [depository, credit, loan, investment, brokerage, other]
+          description: Account type
+          example: depository
+        subtype:
+          type: string
+          description: Specific subtype
+          example: checking
+          enum:
+            - checking
+            - savings
+            - money market
+            - cd
+            - credit card
+            - mortgage
+            - student
+            - auto
+            - 401k
+            - ira
+            - brokerage
+            - other
+        current_balance:
+          type: number
+          description: Current balance (positive for assets)
+          example: 5420.50
+        available_balance:
+          type: number
+          nullable: true
+          description: Available balance (may differ from current)
+          example: 5320.50
+        iso_currency_code:
+          type: string
+          description: ISO 4217 currency code
+          example: USD
+        mask:
+          type: string
+          description: Last 4 digits of account number
+          example: '1234'
+        is_active:
+          type: boolean
+          description: Whether account is actively syncing
+          example: true
+        created_at:
+          type: string
+          format: date-time
+          example: '2025-06-15T10:00:00Z'
+        updated_at:
+          type: string
+          format: date-time
+          example: '2026-01-10T12:00:00Z'
+
+    Transaction:
+      type: object
+      required:
+        - id
+        - account_id
+        - date
+        - amount
+        - name
+        - primary_category
+        - detailed_category
+        - pending
+        - iso_currency_code
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique transaction identifier
+          example: txn_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
+        transaction_id:
+          type: string
+          description: External transaction ID (from Plaid)
+          example: plaid_txn_XYZ789abc
+        account_id:
+          type: string
+          format: uuid
+          description: Parent account ID
+          example: acc_8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
+        date:
+          type: string
+          format: date
+          description: Posted date
+          example: '2026-01-09'
+        authorized_date:
+          type: string
+          format: date
+          nullable: true
+          description: Authorization date (if different)
+          example: '2026-01-08'
+        amount:
+          type: number
+          description: Amount (positive = expense/debit, negative = income/credit)
+          example: 42.50
+        name:
+          type: string
+          description: Raw transaction description from bank
+          example: 'TRADER JOES #123 SAN FRANCISCO'
+        merchant_name:
+          type: string
+          nullable: true
+          description: Cleaned merchant name
+          example: "Trader Joe's"
+        merchant_entity_id:
+          type: string
+          nullable: true
+          description: Unique merchant identifier
+          example: eyg8o776k0QmNgVpAmaQj4WgzW9Qzo6O51gdd
+        logo:
+          type: string
+          format: uri
+          nullable: true
+          description: URL to merchant logo
+          example: https://plaid-merchant-logos.plaid.com/trader_joes.png
+        primary_category:
+          type: string
+          description: High-level category
+          example: FOOD_AND_DRINK
+          enum:
+            - INCOME
+            - TRANSFER_IN
+            - TRANSFER_OUT
+            - LOAN_PAYMENTS
+            - BANK_FEES
+            - ENTERTAINMENT
+            - FOOD_AND_DRINK
+            - GENERAL_MERCHANDISE
+            - HOME_IMPROVEMENT
+            - MEDICAL
+            - PERSONAL_CARE
+            - GENERAL_SERVICES
+            - GOVERNMENT_AND_NON_PROFIT
+            - TRANSPORTATION
+            - TRAVEL
+            - RENT_AND_UTILITIES
+        detailed_category:
+          type: string
+          description: Specific category
+          example: FOOD_AND_DRINK_GROCERIES
+        category_confidence:
+          type: string
+          enum: [VERY_HIGH, HIGH, MEDIUM, LOW, UNKNOWN]
+          description: Category confidence level
+          example: VERY_HIGH
+        payment_channel:
+          type: string
+          enum: [in_store, online, other]
+          description: How payment was made
+          example: in_store
+        pending:
+          type: boolean
+          description: Whether transaction is still pending
+          example: false
+        iso_currency_code:
+          type: string
+          description: ISO 4217 currency code
+          example: USD
+        location:
+          $ref: '#/components/schemas/Location'
+        created_at:
+          type: string
+          format: date-time
+          example: '2026-01-09T18:30:00Z'
+
+    Location:
+      type: object
+      nullable: true
+      properties:
+        city:
+          type: string
+          nullable: true
+          example: San Francisco
+        region:
+          type: string
+          nullable: true
+          example: CA
+        postal_code:
+          type: string
+          nullable: true
+          example: '94110'
+        country:
+          type: string
+          nullable: true
+          example: US
+
+    Snapshot:
+      type: object
+      required:
+        - id
+        - period_type
+        - period_start
+        - period_end
+        - snapshot_date
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique snapshot identifier
+          example: snap_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
+        period_type:
+          type: string
+          enum: [daily, weekly, monthly]
+          description: Period granularity
+          example: daily
+        period_start:
+          type: string
+          format: date
+          description: Period start date
+          example: '2026-01-01'
+        period_end:
+          type: string
+          format: date
+          description: Period end date
+          example: '2026-01-31'
+        snapshot_date:
+          type: string
+          format: date
+          description: When snapshot was taken
+          example: '2026-01-10'
+        income:
+          type: number
+          description: Total income for period
+          example: 6500.00
+        expenses:
+          type: number
+          description: Total expenses for period
+          example: 4200.00
+        net_cash_flow:
+          type: number
+          description: Income minus expenses
+          example: 2300.00
+        savings_rate:
+          type: number
+          description: Percentage saved (0.0 to 1.0)
+          example: 0.35
+        net_worth:
+          type: number
+          description: Total assets minus liabilities
+          example: 45000.00
+        total_cash:
+          type: number
+          description: Sum of depository balances
+          example: 12500.00
+        total_debt:
+          type: number
+          description: Sum of credit/loan balances
+          example: 8500.00
+        investment_value:
+          type: number
+          description: Investment account value
+          example: 28000.00
+        asset_value:
+          type: number
+          description: Other asset values
+          example: 15000.00
+        burn_rate:
+          type: number
+          description: Average daily spending
+          example: 140.00
+        runway_days:
+          type: integer
+          description: Days of expenses covered by cash
+          example: 89
+        safe_to_spend:
+          type: number
+          description: Estimated discretionary spending available
+          example: 1800.00
+        recurring_total:
+          type: number
+          description: Sum of recurring expenses
+          example: 1250.00
+        spending_by_category:
+          type: array
+          items:
+            $ref: '#/components/schemas/CategorySpending'
+        top_merchants:
+          type: array
+          items:
+            $ref: '#/components/schemas/MerchantSpending'
+        income_vs_last_period:
+          type: number
+          description: Percentage change from previous period
+          example: 0.05
+        spending_vs_last_period:
+          type: number
+          description: Percentage change from previous period
+          example: -0.08
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    CategorySpending:
+      type: object
+      properties:
+        category:
+          type: string
+          example: FOOD_AND_DRINK
+        amount:
+          type: number
+          example: 850.00
+        percentage:
+          type: number
+          example: 20.2
+
+    MerchantSpending:
+      type: object
+      properties:
+        merchant:
+          type: string
+          example: Whole Foods
+        amount:
+          type: number
+          example: 420.00
+        count:
+          type: integer
+          example: 8
+
+    Pagination:
+      type: object
+      properties:
+        limit:
+          type: integer
+          description: Transactions per page
+          example: 1000
+        next_cursor:
+          type: string
+          nullable: true
+          description: Token for next page (null if no more pages)
+          example: eyJkYXRlIjoiMjAyNi0wMS0wMSIsImlkIjoiYWJjMTIzIn0
+
+    RecurringStream:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique stream identifier
+          example: cb3daddd-1f82-43ed-ba9f-60ecf8c937e3
+        stream_id:
+          type: string
+          description: External stream ID (from Plaid)
+          example: LN053MyLw9H9MQ5ybwrJim1Kj495gbsJ98aeM
+        account_id:
+          type: string
+          description: Account ID this stream belongs to
+          example: Dpnjw06KAJHYVmr5jqejimy4nE0OQJczvD8KD
+        stream_type:
+          type: string
+          enum: [inflow, outflow]
+          description: Direction of recurring payment
+          example: outflow
+        merchant_name:
+          type: string
+          description: Merchant or payee name
+          example: Ting
+        description:
+          type: string
+          description: Transaction description pattern
+          example: 'TING* INV#MI-4636263'
+        category:
+          type: object
+          properties:
+            primary:
+              type: string
+              example: RENT_AND_UTILITIES
+            detailed:
+              type: string
+              example: RENT_AND_UTILITIES_TELEPHONE
+            confidence_level:
+              type: string
+              enum: [VERY_HIGH, HIGH, MEDIUM, LOW, UNKNOWN]
+        frequency:
+          type: string
+          enum: [WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, ANNUALLY, UNKNOWN]
+          description: Payment frequency
+          example: MONTHLY
+        average_amount:
+          type: number
+          description: Average transaction amount
+          example: 118.98
+        last_amount:
+          type: number
+          description: Most recent transaction amount
+          example: 146.58
+        is_active:
+          type: boolean
+          description: Whether stream is currently active
+          example: true
+        status:
+          type: string
+          enum: [MATURE, EARLY_DETECTION, TOMBSTONED]
+          description: Detection status
+          example: MATURE
+        first_date:
+          type: string
+          format: date
+          description: First detected transaction date
+          example: '2025-07-15'
+        last_date:
+          type: string
+          format: date
+          description: Most recent transaction date
+          example: '2025-09-15'
+        next_date:
+          type: string
+          format: date
+          description: Predicted next transaction date
+          example: '2025-10-15'
+        source:
+          type: string
+          enum: [plaid, user]
+          description: How stream was detected
+          example: plaid
+
+    Error:
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          type: string
+          description: Human-readable error message
+          example: Invalid API key.
+
+    FinancialContext:
+      type: object
+      required:
+        - version
+        - updated_at
+        - currency
+        - status
+        - transactions
+        - recurring
+        - budgets
+        - goals
+        - snapshots
+        - liabilities
+        - holdings
+        - health
+      properties:
+        version:
+          type: string
+          enum: [v1]
+        updated_at:
+          type: string
+          format: date-time
+          description: Latest represented source-data freshness timestamp
+        currency:
+          type: string
+          enum: [USD]
+        status:
+          $ref: '#/components/schemas/FinancialContextStatus'
+        transactions:
+          $ref: '#/components/schemas/TransactionIndex'
+        recurring:
+          type: array
+          items:
+            $ref: '#/components/schemas/FinancialContextRecurring'
+        budgets:
+          type: array
+          items:
+            $ref: '#/components/schemas/FinancialContextBudget'
+        goals:
+          type: array
+          items:
+            $ref: '#/components/schemas/FinancialContextGoal'
+        snapshots:
+          type: array
+          items:
+            $ref: '#/components/schemas/FinancialContextSnapshot'
+        liabilities:
+          type: array
+          items:
+            $ref: '#/components/schemas/FinancialContextLiability'
+        holdings:
+          type: array
+          items:
+            $ref: '#/components/schemas/FinancialContextHolding'
+        health:
+          oneOf:
+            - $ref: '#/components/schemas/FinancialContextHealth'
+            - type: 'null'
+
+    FinancialContextStatus:
+      type: object
+      required:
+        - position
+        - accounts
+      properties:
+        position:
+          oneOf:
+            - $ref: '#/components/schemas/FinancialContextPosition'
+            - type: 'null'
+        accounts:
+          type: array
+          items:
+            $ref: '#/components/schemas/FinancialContextAccount'
+
+    FinancialContextPosition:
+      type: object
+      required:
+        - date
+        - net_worth
+        - cash
+        - debt
+        - investments
+        - other_assets
+        - total_assets
+      properties:
+        date:
+          type: string
+          format: date
+          nullable: true
+        net_worth:
+          type: number
+          nullable: true
+        cash:
+          type: number
+          nullable: true
+        debt:
+          type: number
+          nullable: true
+        investments:
+          type: number
+          nullable: true
+        other_assets:
+          type: number
+          nullable: true
+        total_assets:
+          type: number
+          nullable: true
+
+    FinancialContextAccount:
+      type: object
+      required:
+        - id
+        - name
+        - type
+        - subtype
+        - group
+        - institution
+        - mask
+        - balance
+        - available
+        - currency
+        - updated_at
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        type:
+          type: string
+          enum: [depository, credit, loan, investment, brokerage, other]
+        subtype:
+          type: string
+          nullable: true
+        group:
+          type: string
+          enum: [cash, debt, investments]
+          nullable: true
+        institution:
+          type: string
+          nullable: true
+        mask:
+          type: string
+          nullable: true
+        balance:
+          type: number
+          nullable: true
+        available:
+          type: number
+          nullable: true
+        currency:
+          type: string
+          nullable: true
+        updated_at:
+          type: string
+          format: date-time
+          nullable: true
+
+    TransactionIndex:
+      type: object
+      required:
+        - total
+        - months
+      properties:
+        total:
+          type: integer
+          minimum: 0
+        months:
+          type: array
+          items:
+            type: object
+            required:
+              - month
+              - count
+            properties:
+              month:
+                type: string
+                pattern: '^\d{4}-\d{2}$'
+              count:
+                type: integer
+                minimum: 0
+
+    TransactionMonth:
+      type: object
+      required:
+        - month
+        - start_date
+        - end_date
+        - count
+        - items
+      properties:
+        month:
+          type: string
+          pattern: '^\d{4}-\d{2}$'
+        start_date:
+          type: string
+          format: date
+        end_date:
+          type: string
+          format: date
+        count:
+          type: integer
+          minimum: 0
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/FinancialContextTransaction'
+
+    LatestTransactions:
+      type: object
+      required:
+        - since
+        - window_days
+        - count
+        - items
+      properties:
+        since:
+          type: string
+          format: date
+          description: Inclusive lower bound for the latest transaction window
+        window_days:
+          type: integer
+          enum: [10]
+        count:
+          type: integer
+          minimum: 0
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/FinancialContextTransaction'
+
+    FinancialContextTransaction:
+      type: object
+      required:
+        - id
+        - account_id
+        - date
+        - amount
+        - merchant
+        - name
+        - category
+        - subcategory
+        - pending
+        - currency
+      properties:
+        id:
+          type: string
+        account_id:
+          type: string
+          nullable: true
+        date:
+          type: string
+          format: date
+          nullable: true
+        amount:
+          type: number
+          description: Amount (positive = expense/debit, negative = income/credit)
+        merchant:
+          type: string
+          nullable: true
+        name:
+          type: string
+          nullable: true
+        category:
+          type: string
+          nullable: true
+        subcategory:
+          type: string
+          nullable: true
+        pending:
+          type: boolean
+          nullable: true
+        currency:
+          type: string
+          nullable: true
+
+    FinancialContextRecurring:
+      type: object
+      required:
+        - id
+        - account_id
+        - direction
+        - frequency
+        - status
+        - merchant
+        - amount
+        - next_date
+      properties:
+        id:
+          type: string
+        account_id:
+          type: string
+          nullable: true
+        direction:
+          type: string
+          enum: [inflow, outflow]
+          nullable: true
+        frequency:
+          type: string
+          enum: [WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY]
+          nullable: true
+        status:
+          type: string
+          enum: [active, inactive, dismissed]
+          nullable: true
+        merchant:
+          type: string
+          nullable: true
+        amount:
+          type: number
+          nullable: true
+        next_date:
+          type: string
+          format: date
+          nullable: true
+
+    FinancialContextBudget:
+      type: object
+      required:
+        - id
+        - name
+        - type
+        - period
+        - status
+        - amount
+        - spent
+        - remaining
+        - used_percent
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        type:
+          type: string
+          enum: [category, merchant]
+        period:
+          type: string
+          enum: [weekly, biweekly, monthly]
+        status:
+          type: string
+          enum: [under, warning, over]
+        amount:
+          type: number
+        spent:
+          type: number
+        remaining:
+          type: number
+        used_percent:
+          type: number
+
+    FinancialContextGoal:
+      type: object
+      required:
+        - id
+        - name
+        - category
+        - status
+        - target
+        - current
+        - progress_percent
+        - target_date
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        category:
+          type: string
+        status:
+          type: string
+          enum: [not_started, in_progress, on_track, behind, completed]
+        target:
+          type: number
+        current:
+          type: number
+        progress_percent:
+          type: number
+        target_date:
+          type: string
+          format: date
+          nullable: true
+
+    FinancialContextSnapshot:
+      type: object
+      required:
+        - date
+        - net_worth
+        - cash
+        - debt
+        - income
+        - expenses
+        - cash_flow
+        - savings_rate
+        - investments
+        - assets
+        - health_score
+      properties:
+        date:
+          type: string
+          format: date
+        net_worth:
+          type: number
+          nullable: true
+        cash:
+          type: number
+          nullable: true
+        debt:
+          type: number
+          nullable: true
+        income:
+          type: number
+          nullable: true
+        expenses:
+          type: number
+          nullable: true
+        cash_flow:
+          type: number
+          nullable: true
+        savings_rate:
+          type: number
+          nullable: true
+        investments:
+          type: number
+          nullable: true
+        assets:
+          type: number
+          nullable: true
+        health_score:
+          type: number
+          nullable: true
+
+    FinancialContextLiability:
+      type: object
+      required:
+        - account_id
+        - type
+        - balance
+        - minimum_payment
+        - due_date
+        - interest_rate
+        - rate_type
+        - overdue
+      properties:
+        account_id:
+          type: string
+          nullable: true
+        type:
+          type: string
+          enum: [credit, student, mortgage, other]
+          nullable: true
+        balance:
+          type: number
+          nullable: true
+        minimum_payment:
+          type: number
+          nullable: true
+        due_date:
+          type: string
+          format: date
+          nullable: true
+        interest_rate:
+          type: number
+          nullable: true
+        rate_type:
+          type: string
+          enum: [fixed, variable]
+          nullable: true
+        overdue:
+          type: boolean
+          nullable: true
+
+    FinancialContextHolding:
+      type: object
+      required:
+        - account_id
+        - symbol
+        - name
+        - type
+        - quantity
+        - value
+        - cost_basis
+      properties:
+        account_id:
+          type: string
+          nullable: true
+        symbol:
+          type: string
+          nullable: true
+        name:
+          type: string
+          nullable: true
+        type:
+          type: string
+          enum: [cash, derivative, equity, etf, fixed_income, mutual_fund, other]
+          nullable: true
+        quantity:
+          type: number
+          nullable: true
+        value:
+          type: number
+          nullable: true
+        cost_basis:
+          type: number
+          nullable: true
+
+    FinancialContextHealth:
+      type: object
+      required:
+        - score
+        - label
+        - level
+        - summary
+        - data_completeness
+        - pillars
+      properties:
+        score:
+          type: number
+        label:
+          type: string
+          enum: [Needs Attention, Good, Strong]
+        level:
+          type: string
+          enum: [critical, poor, fair, good, strong]
+        summary:
+          type: string
+        data_completeness:
+          type: number
+        pillars:
+          oneOf:
+            - type: object
+              required:
+                - spend
+                - save
+                - borrow
+                - build
+              properties:
+                spend:
+                  type: number
+                  nullable: true
+                save:
+                  type: number
+                  nullable: true
+                borrow:
+                  type: number
+                  nullable: true
+                build:
+                  type: number
+                  nullable: true
+            - type: 'null'
+
+    FinancialContextMeta:
+      type: object
+      required:
+        - version
+        - user_id
+        - context_id
+        - generated_at
+        - updated_at
+        - content_hash
+        - byte_length
+        - counts
+      properties:
+        version:
+          type: string
+          enum: [v1]
+        user_id:
+          type: string
+        context_id:
+          type: string
+        generated_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+          description: Latest represented source-data freshness timestamp
+        content_hash:
+          type: string
+          description: Opaque artifact version token and ETag value. This is the only public artifact version token.
+        byte_length:
+          type: integer
+          minimum: 0
+        counts:
+          type: object
+          required:
+            - accounts
+            - transaction_months
+            - transactions
+            - snapshots
+          properties:
+            accounts:
+              type: integer
+              minimum: 0
+            transaction_months:
+              type: integer
+              minimum: 0
+            transactions:
+              type: integer
+              minimum: 0
+            snapshots:
+              type: integer
+              minimum: 0
+
+tags:
+  - name: Export
+    description: Export financial data as structured JSON