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`. Warm API keys grant full access to the public API and local MCP tools. Read endpoints accept a Warm API key or signed-in JWT. Automation endpoints require a Warm API key. API keys begin with `warm_`. ## Rate Limits - API keys: 500 requests per hour per key - Rate limit headers are included only on routes that document a `429` response. - `/api/export` supports dataset-scoped delta sync with `since` and publishes edge-cache metadata headers. version: 3.0.2 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 for installer and Settings flows. Authentication: Read endpoints accept a Warm API key or signed-in JWT. tags: - Verification responses: "200": content: application/json: schema: $ref: "#/components/schemas/VerifyApiResponse" description: Credentials are valid and the caller has API access "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" security: - BearerAuth: [] /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 documented dataset name. Preferred dataset names are `accounts`, `transactions`, `snapshots`, `recurring`, `budgets`, `goals`, `health`, `liabilities`, and `holdings`. Authentication: Read endpoints accept a Warm API key or signed-in JWT. tags: - Export parameters: - name: dataset in: query description: Dataset identifier 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: 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": content: application/json: schema: oneOf: - $ref: "#/components/schemas/ExportAccountsResponse" - $ref: "#/components/schemas/ExportTransactionsResponse" - $ref: "#/components/schemas/ExportSnapshotsResponse" - $ref: "#/components/schemas/ExportRecurringResponse" - $ref: "#/components/schemas/ExportBudgetsResponse" - $ref: "#/components/schemas/ExportGoalsResponse" - $ref: "#/components/schemas/ExportHealthResponse" - $ref: "#/components/schemas/ExportLiabilitiesResponse" - $ref: "#/components/schemas/ExportHoldingsResponse" description: Successful dataset export "400": description: Invalid query parameters content: application/json: schema: $ref: "#/components/schemas/Error" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": $ref: "#/components/responses/RateLimited" security: - BearerAuth: [] /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. Authentication: Read endpoints accept a Warm API key or signed-in JWT. 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" security: - BearerAuth: [] /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 current `@warmio/mcp` `get_transactions` tool accepts one required `period` string: `latest` for the fixed latest window or `YYYY-MM` for a month. It does not accept export pagination or filtering controls. 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`. Authentication: Read endpoints accept a Warm API key or signed-in JWT. 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" security: - BearerAuth: [] /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`. Authentication: Read endpoints accept a Warm API key or signed-in JWT. 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" security: - BearerAuth: [] /api/automation/operations/search: post: operationId: searchOperations summary: Search supported automation operations tags: - Automation security: - BearerAuth: [] 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" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": $ref: "#/components/responses/RateLimited" "500": $ref: "#/components/responses/InternalError" description: "Authentication: Automation endpoints require a Warm API key." /api/automation/operations/describe: post: operationId: describeOperation summary: Describe one supported operation tags: - Automation security: - BearerAuth: [] 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" description: "Authentication: Automation endpoints require a Warm API key." /api/automation/operations/invoke: post: operationId: invokeOperation summary: Invoke one supported operation tags: - Automation security: - BearerAuth: [] 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" description: "Authentication: Automation endpoints require a Warm API key." components: securitySchemes: BearerAuth: description: "API key format: Authorization: Bearer warm_...; read endpoints accept a warm api key or signed-in jwt." scheme: bearer type: http 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 properties: confirmation_required: type: boolean description: type: string method: type: string enum: - DELETE - GET - PATCH - POST - PUT operation_id: type: string path: type: string risk: type: array items: type: string enum: - read - write - destructive - external_effect summary: type: string required: - confirmation_required - description - method - operation_id - path - risk - summary additionalProperties: false $schema: https://json-schema.org/draft-07/schema# OperationRequest: type: object properties: input: type: object properties: body: type: object additionalProperties: {} params: type: object additionalProperties: type: string additionalProperties: false operation_id: type: string minLength: 1 required: - operation_id additionalProperties: false $schema: https://json-schema.org/draft-07/schema# OperationInvokeRequest: type: object properties: input: type: object properties: body: type: object additionalProperties: {} params: type: object additionalProperties: type: string additionalProperties: false operation_id: type: string minLength: 1 approval_id: type: string format: uuid required: - operation_id additionalProperties: false $schema: https://json-schema.org/draft-07/schema# OperationInput: type: object properties: body: type: object additionalProperties: {} params: type: object additionalProperties: type: string additionalProperties: false $schema: https://json-schema.org/draft-07/schema# AutomationInvocationResponse: type: object properties: body: {} headers: type: object additionalProperties: type: string operation_id: type: string status: type: integer minimum: 100 maximum: 599 required: - headers - operation_id - status additionalProperties: false $schema: https://json-schema.org/draft-07/schema# 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 `since` in the 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.5 available_balance: type: number nullable: true description: Available balance (may differ from current) example: 5320.5 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.5 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 expenses: type: number description: Total expenses for period example: 4200 net_cash_flow: type: number description: Income minus expenses example: 2300 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 total_cash: type: number description: Sum of depository balances example: 12500 total_debt: type: number description: Sum of credit/loan balances example: 8500 investment_value: type: number description: Investment account value example: 28000 asset_value: type: number description: Other asset values example: 15000 burn_rate: type: number description: Average daily spending example: 140 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 recurring_total: type: number description: Sum of recurring expenses example: 1250 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 percentage: type: number example: 20.2 MerchantSpending: type: object properties: merchant: type: string example: Whole Foods amount: type: number example: 420 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 properties: error: type: string required: - error additionalProperties: false $schema: https://json-schema.org/draft-07/schema# VerifyApiResponse: type: object properties: valid: type: boolean const: true description: True when the credential is valid and has API access example: true required: - valid additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContext: type: object properties: version: type: string enum: - v1 updated_at: type: string format: date-time currency: type: string enum: - USD status: type: object properties: position: anyOf: - type: object properties: date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" net_worth: anyOf: - type: number - type: "null" cash: anyOf: - type: number - type: "null" debt: anyOf: - type: number - type: "null" investments: anyOf: - type: number - type: "null" other_assets: anyOf: - type: number - type: "null" total_assets: anyOf: - type: number - type: "null" required: - date - net_worth - cash - debt - investments - other_assets - total_assets additionalProperties: false description: The status.position field is a point-in-time (as-of-date) balance snapshot, separate from transaction and behavior windows. A null position means no position snapshot is available. - type: "null" description: The status.position field is a point-in-time (as-of-date) balance snapshot, separate from transaction and behavior windows. A null position means no position snapshot is available. accounts: type: array items: type: object properties: id: type: string name: type: string source: anyOf: - type: string enum: - plaid - manual - csv_import - type: "null" type: type: string enum: - depository - credit - loan - investment - brokerage - other subtype: type: - string - "null" group: anyOf: - type: string enum: - cash - debt - investments - other - type: "null" institution: type: - string - "null" mask: type: - string - "null" balance: anyOf: - type: number - type: "null" available: anyOf: - type: number - type: "null" currency: type: - string - "null" updated_at: anyOf: - type: string format: date-time - type: "null" required: - id - name - source - type - subtype - group - institution - mask - balance - available - currency - updated_at additionalProperties: false required: - position - accounts additionalProperties: false transactions: type: object properties: total: type: integer minimum: 0 months: type: array items: type: object properties: month: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ count: type: integer minimum: 0 required: - month - count additionalProperties: false required: - total - months additionalProperties: false recurring: type: array items: type: object properties: id: type: string account_id: type: - string - "null" direction: anyOf: - type: string enum: - inflow - outflow - type: "null" frequency: anyOf: - type: string enum: - WEEKLY - BIWEEKLY - MONTHLY - QUARTERLY - SEMI_ANNUALLY - ANNUALLY - type: "null" status: anyOf: - type: string enum: - active - inactive - dismissed - type: "null" merchant: type: - string - "null" amount: anyOf: - type: number - type: "null" next_date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" excluded_from_subscriptions: type: boolean required: - id - account_id - direction - frequency - status - merchant - amount - next_date additionalProperties: false budgets: type: array items: type: object 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 required: - id - name - type - period - status - amount - spent - remaining - used_percent additionalProperties: false goals: type: array items: type: object 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: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" required: - id - name - category - status - target - current - progress_percent - target_date additionalProperties: false snapshots: type: array items: type: object properties: date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ net_worth: anyOf: - type: number - type: "null" cash: anyOf: - type: number - type: "null" debt: anyOf: - type: number - type: "null" income: anyOf: - type: number - type: "null" expenses: anyOf: - type: number - type: "null" cash_flow: anyOf: - type: number - type: "null" savings_rate: anyOf: - type: number - type: "null" investments: anyOf: - type: number - type: "null" assets: anyOf: - type: number - type: "null" health_score: anyOf: - type: number - type: "null" health_score_model_version: anyOf: - type: number const: 3 - type: "null" required: - date - net_worth - cash - debt - income - expenses - cash_flow - savings_rate - investments - assets - health_score - health_score_model_version additionalProperties: false liabilities: type: array items: type: object properties: account_id: type: - string - "null" type: anyOf: - type: string enum: - credit - student - mortgage - other - type: "null" balance: anyOf: - type: number - type: "null" minimum_payment: anyOf: - type: number - type: "null" due_date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" interest_rate: anyOf: - type: number - type: "null" rate_type: anyOf: - type: string enum: - fixed - variable - type: "null" overdue: type: - boolean - "null" required: - account_id - type - balance - minimum_payment - due_date - interest_rate - rate_type - overdue additionalProperties: false holdings: type: array items: type: object properties: account_id: type: - string - "null" symbol: type: - string - "null" name: type: - string - "null" type: anyOf: - type: string enum: - cash - derivative - equity - etf - fixed_income - mutual_fund - other - type: "null" quantity: anyOf: - type: number - type: "null" value: anyOf: - type: number - type: "null" cost_basis: anyOf: - type: number - type: "null" required: - account_id - symbol - name - type - quantity - value - cost_basis additionalProperties: false health: anyOf: - type: object properties: score: type: number model_version: type: number const: 3 record_count: type: integer minimum: 0 label: type: string enum: - Needs Attention - Good - Strong level: type: string enum: - strong - good - fair - poor - critical summary: type: string data_completeness: type: number pillars: anyOf: - type: object properties: spend: anyOf: - type: number - type: "null" save: anyOf: - type: number - type: "null" borrow: anyOf: - type: number - type: "null" build: anyOf: - type: number - type: "null" required: - spend - save - borrow - build additionalProperties: false - type: "null" required: - score - model_version - record_count - label - level - summary - data_completeness - pillars additionalProperties: false - type: "null" required: - version - updated_at - currency - status - transactions - recurring - budgets - goals - snapshots - liabilities - holdings - health additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextStatus: type: object properties: position: anyOf: - type: object properties: date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" net_worth: anyOf: - type: number - type: "null" cash: anyOf: - type: number - type: "null" debt: anyOf: - type: number - type: "null" investments: anyOf: - type: number - type: "null" other_assets: anyOf: - type: number - type: "null" total_assets: anyOf: - type: number - type: "null" required: - date - net_worth - cash - debt - investments - other_assets - total_assets additionalProperties: false description: The status.position field is a point-in-time (as-of-date) balance snapshot, separate from transaction and behavior windows. A null position means no position snapshot is available. - type: "null" description: The status.position field is a point-in-time (as-of-date) balance snapshot, separate from transaction and behavior windows. A null position means no position snapshot is available. accounts: type: array items: type: object properties: id: type: string name: type: string source: anyOf: - type: string enum: - plaid - manual - csv_import - type: "null" type: type: string enum: - depository - credit - loan - investment - brokerage - other subtype: type: - string - "null" group: anyOf: - type: string enum: - cash - debt - investments - other - type: "null" institution: type: - string - "null" mask: type: - string - "null" balance: anyOf: - type: number - type: "null" available: anyOf: - type: number - type: "null" currency: type: - string - "null" updated_at: anyOf: - type: string format: date-time - type: "null" required: - id - name - source - type - subtype - group - institution - mask - balance - available - currency - updated_at additionalProperties: false required: - position - accounts additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextPosition: type: object properties: date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" net_worth: anyOf: - type: number - type: "null" cash: anyOf: - type: number - type: "null" debt: anyOf: - type: number - type: "null" investments: anyOf: - type: number - type: "null" other_assets: anyOf: - type: number - type: "null" total_assets: anyOf: - type: number - type: "null" required: - date - net_worth - cash - debt - investments - other_assets - total_assets additionalProperties: false description: The status.position field is a point-in-time (as-of-date) balance snapshot, separate from transaction and behavior windows. A null position means no position snapshot is available. $schema: https://json-schema.org/draft-07/schema# FinancialContextAccount: type: object properties: id: type: string name: type: string source: anyOf: - type: string enum: - plaid - manual - csv_import - type: "null" type: type: string enum: - depository - credit - loan - investment - brokerage - other subtype: type: - string - "null" group: anyOf: - type: string enum: - cash - debt - investments - other - type: "null" institution: type: - string - "null" mask: type: - string - "null" balance: anyOf: - type: number - type: "null" available: anyOf: - type: number - type: "null" currency: type: - string - "null" updated_at: anyOf: - type: string format: date-time - type: "null" required: - id - name - source - type - subtype - group - institution - mask - balance - available - currency - updated_at additionalProperties: false $schema: https://json-schema.org/draft-07/schema# TransactionIndex: type: object properties: total: type: integer minimum: 0 months: type: array items: type: object properties: month: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ count: type: integer minimum: 0 required: - month - count additionalProperties: false required: - total - months additionalProperties: false $schema: https://json-schema.org/draft-07/schema# TransactionMonth: type: object properties: month: type: string pattern: ^\d{4}-(0[1-9]|1[0-2])$ start_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ end_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ count: type: integer minimum: 0 items: type: array items: type: object properties: id: type: string account_id: type: - string - "null" date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" amount: type: number merchant: type: - string - "null" name: type: - string - "null" category: type: - string - "null" subcategory: type: - string - "null" pending: type: - boolean - "null" currency: type: - string - "null" is_internal_transfer: type: - boolean - "null" transfer_pair_id: anyOf: - type: string format: uuid - type: "null" transfers_interpretation_version: type: number enum: - 0 - 1 merchants_interpretation_version: type: number const: 0 required: - id - account_id - date - amount - merchant - name - category - subcategory - pending - currency additionalProperties: false required: - month - start_date - end_date - count - items additionalProperties: false $schema: https://json-schema.org/draft-07/schema# LatestTransactions: type: object properties: since: type: string pattern: ^\d{4}-\d{2}-\d{2}$ window_days: type: number const: 10 count: type: integer minimum: 0 items: type: array items: type: object properties: id: type: string account_id: type: - string - "null" date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" amount: type: number merchant: type: - string - "null" name: type: - string - "null" category: type: - string - "null" subcategory: type: - string - "null" pending: type: - boolean - "null" currency: type: - string - "null" is_internal_transfer: type: - boolean - "null" transfer_pair_id: anyOf: - type: string format: uuid - type: "null" transfers_interpretation_version: type: number enum: - 0 - 1 merchants_interpretation_version: type: number const: 0 required: - id - account_id - date - amount - merchant - name - category - subcategory - pending - currency additionalProperties: false required: - since - window_days - count - items additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextTransaction: type: object properties: id: type: string account_id: type: - string - "null" date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" amount: type: number merchant: type: - string - "null" name: type: - string - "null" category: type: - string - "null" subcategory: type: - string - "null" pending: type: - boolean - "null" currency: type: - string - "null" is_internal_transfer: type: - boolean - "null" transfer_pair_id: anyOf: - type: string format: uuid - type: "null" transfers_interpretation_version: type: number enum: - 0 - 1 merchants_interpretation_version: type: number const: 0 required: - id - account_id - date - amount - merchant - name - category - subcategory - pending - currency additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextRecurring: type: object properties: id: type: string account_id: type: - string - "null" direction: anyOf: - type: string enum: - inflow - outflow - type: "null" frequency: anyOf: - type: string enum: - WEEKLY - BIWEEKLY - MONTHLY - QUARTERLY - SEMI_ANNUALLY - ANNUALLY - type: "null" status: anyOf: - type: string enum: - active - inactive - dismissed - type: "null" merchant: type: - string - "null" amount: anyOf: - type: number - type: "null" next_date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" excluded_from_subscriptions: type: boolean required: - id - account_id - direction - frequency - status - merchant - amount - next_date additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextBudget: type: object 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 required: - id - name - type - period - status - amount - spent - remaining - used_percent additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextGoal: type: object 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: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" required: - id - name - category - status - target - current - progress_percent - target_date additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextSnapshot: type: object properties: date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ net_worth: anyOf: - type: number - type: "null" cash: anyOf: - type: number - type: "null" debt: anyOf: - type: number - type: "null" income: anyOf: - type: number - type: "null" expenses: anyOf: - type: number - type: "null" cash_flow: anyOf: - type: number - type: "null" savings_rate: anyOf: - type: number - type: "null" investments: anyOf: - type: number - type: "null" assets: anyOf: - type: number - type: "null" health_score: anyOf: - type: number - type: "null" health_score_model_version: anyOf: - type: number const: 3 - type: "null" required: - date - net_worth - cash - debt - income - expenses - cash_flow - savings_rate - investments - assets - health_score - health_score_model_version additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextLiability: type: object properties: account_id: type: - string - "null" type: anyOf: - type: string enum: - credit - student - mortgage - other - type: "null" balance: anyOf: - type: number - type: "null" minimum_payment: anyOf: - type: number - type: "null" due_date: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: "null" interest_rate: anyOf: - type: number - type: "null" rate_type: anyOf: - type: string enum: - fixed - variable - type: "null" overdue: type: - boolean - "null" required: - account_id - type - balance - minimum_payment - due_date - interest_rate - rate_type - overdue additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextHolding: type: object properties: account_id: type: - string - "null" symbol: type: - string - "null" name: type: - string - "null" type: anyOf: - type: string enum: - cash - derivative - equity - etf - fixed_income - mutual_fund - other - type: "null" quantity: anyOf: - type: number - type: "null" value: anyOf: - type: number - type: "null" cost_basis: anyOf: - type: number - type: "null" required: - account_id - symbol - name - type - quantity - value - cost_basis additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextHealth: type: object properties: score: type: number model_version: type: number const: 3 record_count: type: integer minimum: 0 label: type: string enum: - Needs Attention - Good - Strong level: type: string enum: - strong - good - fair - poor - critical summary: type: string data_completeness: type: number pillars: anyOf: - type: object properties: spend: anyOf: - type: number - type: "null" save: anyOf: - type: number - type: "null" borrow: anyOf: - type: number - type: "null" build: anyOf: - type: number - type: "null" required: - spend - save - borrow - build additionalProperties: false - type: "null" required: - score - model_version - record_count - label - level - summary - data_completeness - pillars additionalProperties: false $schema: https://json-schema.org/draft-07/schema# FinancialContextMeta: type: object 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 content_hash: type: string byte_length: type: integer minimum: 0 counts: type: object properties: accounts: type: integer minimum: 0 transaction_months: type: integer minimum: 0 transactions: type: integer minimum: 0 snapshots: type: integer minimum: 0 required: - accounts - transaction_months - transactions - snapshots additionalProperties: false required: - version - user_id - context_id - generated_at - updated_at - content_hash - byte_length - counts additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportAccount: type: object properties: balance: anyOf: - type: number - type: "null" id: type: string mask: type: - string - "null" name: type: - string - "null" subtype: type: - string - "null" type: type: - string - "null" required: - balance - id - mask - name - subtype - type additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportAccountsResponse: type: object properties: accounts: type: array items: type: object properties: balance: anyOf: - type: number - type: "null" id: type: string mask: type: - string - "null" name: type: - string - "null" subtype: type: - string - "null" type: type: - string - "null" required: - balance - id - mask - name - subtype - type additionalProperties: false generated_at: type: string format: date-time required: - accounts - generated_at additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportBudget: type: object properties: amount: type: number budget_type: type: string effective_amount: type: number name: type: string percent_used: type: number period: type: string remaining: type: number rollover_enabled: type: boolean spent: type: number status: type: string required: - amount - budget_type - effective_amount - name - percent_used - period - remaining - rollover_enabled - spent - status additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportBudgetsResponse: type: object properties: budgets: type: array items: type: object properties: amount: type: number budget_type: type: string effective_amount: type: number name: type: string percent_used: type: number period: type: string remaining: type: number rollover_enabled: type: boolean spent: type: number status: type: string required: - amount - budget_type - effective_amount - name - percent_used - period - remaining - rollover_enabled - spent - status additionalProperties: false generated_at: type: string format: date-time required: - budgets - generated_at additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportGoal: type: object properties: category: type: string current: type: number linked_account: type: - string - "null" monthly_contribution_needed: anyOf: - type: number - type: "null" name: type: string progress_percent: type: number status: type: string target: type: number target_date: type: - string - "null" required: - category - current - linked_account - monthly_contribution_needed - name - progress_percent - status - target - target_date additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportGoalsResponse: type: object properties: goals: type: array items: type: object properties: category: type: string current: type: number linked_account: type: - string - "null" monthly_contribution_needed: anyOf: - type: number - type: "null" name: type: string progress_percent: type: number status: type: string target: type: number target_date: type: - string - "null" required: - category - current - linked_account - monthly_contribution_needed - name - progress_percent - status - target - target_date additionalProperties: false generated_at: type: string format: date-time required: - goals - generated_at additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportHealthResponse: type: object properties: data_completeness: anyOf: - type: number - type: "null" generated_at: type: string format: date-time label: type: - string - "null" message: type: - string - "null" model_version: anyOf: - type: number const: 3 - type: "null" pillars: anyOf: - type: object properties: borrow: anyOf: - type: number - type: "null" build: anyOf: - type: number - type: "null" save: anyOf: - type: number - type: "null" spend: anyOf: - type: number - type: "null" required: - borrow - build - save - spend additionalProperties: false - type: "null" score: anyOf: - type: number - type: "null" record_count: anyOf: - type: integer minimum: 0 - type: "null" required: - data_completeness - generated_at - label - message - model_version - pillars - score - record_count additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportHolding: type: object properties: account_id: type: - string - "null" cost_basis: anyOf: - type: number - type: "null" quantity: anyOf: - type: number - type: "null" security_name: type: - string - "null" symbol: type: - string - "null" type: type: - string - "null" value: anyOf: - type: number - type: "null" required: - account_id - cost_basis - quantity - security_name - symbol - type - value additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportHoldingsResponse: type: object properties: holdings: type: array items: type: object properties: account_id: type: - string - "null" cost_basis: anyOf: - type: number - type: "null" quantity: anyOf: - type: number - type: "null" security_name: type: - string - "null" symbol: type: - string - "null" type: type: - string - "null" value: anyOf: - type: number - type: "null" required: - account_id - cost_basis - quantity - security_name - symbol - type - value additionalProperties: false generated_at: type: string format: date-time required: - holdings - generated_at additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportLiability: type: object properties: account_id: type: - string - "null" apr_percentage: anyOf: - type: number - type: "null" apr_source: type: - string - "null" balance: anyOf: - type: number - type: "null" expected_payoff_date: type: - string - "null" interest_rate_percentage: anyOf: - type: number - type: "null" interest_rate_type: type: - string - "null" interest_rate_source: type: - string - "null" is_overdue: type: - boolean - "null" minimum_payment: anyOf: - type: number - type: "null" next_payment_due_date: type: - string - "null" origination_principal_amount: anyOf: - type: number - type: "null" type: type: - string - "null" required: - account_id - apr_percentage - apr_source - balance - expected_payoff_date - interest_rate_percentage - interest_rate_type - interest_rate_source - is_overdue - minimum_payment - next_payment_due_date - origination_principal_amount - type additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportLiabilitiesResponse: type: object properties: liabilities: type: array items: type: object properties: account_id: type: - string - "null" apr_percentage: anyOf: - type: number - type: "null" apr_source: type: - string - "null" balance: anyOf: - type: number - type: "null" expected_payoff_date: type: - string - "null" interest_rate_percentage: anyOf: - type: number - type: "null" interest_rate_type: type: - string - "null" interest_rate_source: type: - string - "null" is_overdue: type: - boolean - "null" minimum_payment: anyOf: - type: number - type: "null" next_payment_due_date: type: - string - "null" origination_principal_amount: anyOf: - type: number - type: "null" type: type: - string - "null" required: - account_id - apr_percentage - apr_source - balance - expected_payoff_date - interest_rate_percentage - interest_rate_type - interest_rate_source - is_overdue - minimum_payment - next_payment_due_date - origination_principal_amount - type additionalProperties: false generated_at: type: string format: date-time required: - liabilities - generated_at additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportPagination: type: object properties: limit: type: integer exclusiveMinimum: 0 next_cursor: type: string required: - limit - next_cursor additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportRecurring: type: object properties: account_id: type: - string - "null" amount: anyOf: - type: number - type: "null" frequency: type: - string - "null" id: type: string merchant: type: - string - "null" next_date: type: - string - "null" status: type: - string - "null" required: - account_id - amount - frequency - id - merchant - next_date - status additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportRecurringResponse: type: object properties: generated_at: type: string format: date-time recurring_transactions: type: array items: type: object properties: account_id: type: - string - "null" amount: anyOf: - type: number - type: "null" frequency: type: - string - "null" id: type: string merchant: type: - string - "null" next_date: type: - string - "null" status: type: - string - "null" required: - account_id - amount - frequency - id - merchant - next_date - status additionalProperties: false required: - generated_at - recurring_transactions additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportSnapshot: type: object properties: asset_value: anyOf: - type: number - type: "null" investment_value: anyOf: - type: number - type: "null" liability_value: anyOf: - type: number - type: "null" net_worth: anyOf: - type: number - type: "null" period_end: type: string snapshot_date: type: string total_cash: anyOf: - type: number - type: "null" total_debt: anyOf: - type: number - type: "null" required: - asset_value - investment_value - liability_value - net_worth - period_end - snapshot_date - total_cash - total_debt additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportSnapshotsResponse: type: object properties: snapshots: type: array items: type: object properties: asset_value: anyOf: - type: number - type: "null" investment_value: anyOf: - type: number - type: "null" liability_value: anyOf: - type: number - type: "null" net_worth: anyOf: - type: number - type: "null" period_end: type: string snapshot_date: type: string total_cash: anyOf: - type: number - type: "null" total_debt: anyOf: - type: number - type: "null" required: - asset_value - investment_value - liability_value - net_worth - period_end - snapshot_date - total_cash - total_debt additionalProperties: false generated_at: type: string format: date-time required: - snapshots - generated_at additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportTransaction: type: object properties: account_id: type: - string - "null" amount: anyOf: - type: number - type: "null" category: type: - string - "null" date: type: - string - "null" id: type: string merchant: type: - string - "null" name: type: - string - "null" pending: type: - boolean - "null" subcategory: type: - string - "null" required: - account_id - amount - category - date - id - merchant - name - pending - subcategory additionalProperties: false $schema: https://json-schema.org/draft-07/schema# ExportTransactionsResponse: type: object properties: generated_at: type: string format: date-time next_knowledge: type: string format: date-time pagination: type: object properties: limit: type: integer exclusiveMinimum: 0 next_cursor: type: string required: - limit - next_cursor additionalProperties: false transactions: type: array items: type: object properties: account_id: type: - string - "null" amount: anyOf: - type: number - type: "null" category: type: - string - "null" date: type: - string - "null" id: type: string merchant: type: - string - "null" name: type: - string - "null" pending: type: - boolean - "null" subcategory: type: - string - "null" required: - account_id - amount - category - date - id - merchant - name - pending - subcategory additionalProperties: false required: - generated_at - next_knowledge - transactions additionalProperties: false $schema: https://json-schema.org/draft-07/schema# tags: - name: Export description: Export financial data as structured JSON