{ "openapi": "3.0.0", "components": { "examples": {}, "headers": {}, "parameters": {}, "requestBodies": {}, "responses": {}, "schemas": { "TravelWindowKindDto": { "type": "string", "enum": [ "vacation", "work" ] }, "TravelWindowAccountDto": { "properties": { "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "name", "id" ], "type": "object" }, "TravelWindowDto": { "properties": { "accounts": { "items": { "$ref": "#/components/schemas/TravelWindowAccountDto" }, "type": "array" }, "location": { "type": "string", "nullable": true }, "endDate": { "type": "string" }, "startDate": { "type": "string" }, "kind": { "$ref": "#/components/schemas/TravelWindowKindDto" }, "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "accounts", "location", "endDate", "startDate", "kind", "name", "id" ], "type": "object" }, "TravelWindowsDto": { "properties": { "windows": { "items": { "$ref": "#/components/schemas/TravelWindowDto" }, "type": "array" } }, "required": [ "windows" ], "type": "object" }, "TravelWindowWriteDto": { "properties": { "accounts": { "items": { "$ref": "#/components/schemas/TravelWindowAccountDto" }, "type": "array" }, "location": { "type": "string", "nullable": true }, "endDate": { "type": "string" }, "startDate": { "type": "string" }, "kind": { "$ref": "#/components/schemas/TravelWindowKindDto" }, "name": { "type": "string" } }, "required": [ "accounts", "location", "endDate", "startDate", "kind", "name" ], "type": "object" }, "TravelBiasDto": { "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "AccountDto": { "properties": { "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "name", "id" ], "type": "object" }, "AccountsDto": { "properties": { "accounts": { "items": { "$ref": "#/components/schemas/AccountDto" }, "type": "array" } }, "required": [ "accounts" ], "type": "object" }, "SpendChartCategoryDto": { "properties": { "dailyMilliunits": { "items": { "type": "number", "format": "double" }, "type": "array", "description": "One value per entry in `SpendChartDto.days`, in milliunits, after smoothing." }, "totalMilliunits": { "type": "number", "format": "double", "description": "Net spend dated inside the range, in milliunits, before any smoothing." }, "windowDays": { "type": "number", "format": "double", "description": "1 when the category is charted as spent; otherwise each purchase is spread over this many days." }, "groupName": { "type": "string" }, "categoryName": { "type": "string" }, "categoryId": { "type": "string" } }, "required": [ "dailyMilliunits", "totalMilliunits", "windowDays", "groupName", "categoryName", "categoryId" ], "type": "object" }, "SpendChartDto": { "properties": { "categories": { "items": { "$ref": "#/components/schemas/SpendChartCategoryDto" }, "type": "array", "description": "Categories with any spend touching the range, largest total first." }, "days": { "items": { "type": "string" }, "type": "array", "description": "Every day from `startDate` to `endDate` inclusive, as `YYYY-MM-DD`." }, "endDate": { "type": "string" }, "startDate": { "type": "string" } }, "required": [ "categories", "days", "endDate", "startDate" ], "type": "object" }, "CategorySmoothingDto": { "properties": { "windowDays": { "type": "number", "format": "double", "description": "1 turns smoothing off." }, "categoryId": { "type": "string" } }, "required": [ "windowDays", "categoryId" ], "type": "object" }, "CategorySmoothingWriteDto": { "properties": { "windowDays": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 365 } }, "required": [ "windowDays" ], "type": "object" }, "ReceiptExtractStatus": { "type": "string", "enum": [ "pending", "gated", "ungated", "failed" ] }, "ReceiptBindSource": { "type": "string", "enum": [ "capture", "manual", "auto" ], "description": "`capture` = photographed from a transaction card; `auto` = the binder, confirmed by Jev." }, "ReceiptBindCheckOutcome": { "type": "string", "enum": [ "bound", "no-candidate", "not-confirmed", "ambiguous", "jev-unavailable", "lost-race" ], "description": "Why the last auto-bind attempt left a receipt unbound (or `bound`)." }, "ReceiptDto": { "properties": { "bindCheckOutcome": { "allOf": [ { "$ref": "#/components/schemas/ReceiptBindCheckOutcome" } ], "nullable": true }, "bindCheckedAt": { "type": "string", "nullable": true, "description": "Last background auto-bind attempt and what it concluded." }, "bindJevScore": { "type": "number", "format": "double", "nullable": true, "description": "Jev same-purchase probability behind an `auto` bind." }, "boundAt": { "type": "string", "nullable": true }, "bindSource": { "allOf": [ { "$ref": "#/components/schemas/ReceiptBindSource" } ], "nullable": true, "description": "How the current binding was made; null when unbound." }, "hasProcessed": { "type": "boolean" }, "frameCount": { "type": "number", "format": "double" }, "totalsDisagree": { "type": "boolean" }, "contentHash": { "type": "string" }, "transactionId": { "type": "string", "nullable": true }, "extractCostUsd": { "type": "number", "format": "double", "nullable": true }, "rawText": { "type": "string", "nullable": true }, "extractJson": { "type": "string", "nullable": true }, "extractStatus": { "$ref": "#/components/schemas/ReceiptExtractStatus" }, "printedMilliunits": { "type": "number", "format": "double", "nullable": true }, "purchaseDate": { "type": "string", "nullable": true }, "vendor": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "id": { "type": "string" } }, "required": [ "bindCheckOutcome", "bindCheckedAt", "bindJevScore", "boundAt", "bindSource", "hasProcessed", "frameCount", "totalsDisagree", "contentHash", "transactionId", "extractCostUsd", "rawText", "extractJson", "extractStatus", "printedMilliunits", "purchaseDate", "vendor", "createdAt", "id" ], "type": "object" }, "ReceiptsDto": { "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `cursor` for the next page; null on the last page or an unpaged list." }, "receipts": { "items": { "$ref": "#/components/schemas/ReceiptDto" }, "type": "array" } }, "required": [ "nextCursor", "receipts" ], "type": "object" }, "ReceiptBoundFilter": { "type": "string", "enum": [ "bound", "unbound" ] }, "ReceiptIssue": { "type": "string", "enum": [ "unreadable", "needs-look", "flagged", "extracting", "bind-ambiguous", "bind-not-confirmed", "bind-jev-unavailable", "bind-no-charge" ], "description": "Something stored on a receipt that says it needs a person. Each is a recorded fact, never a guess:\n- `unreadable`: the extract failed (vendor, date, or total missing).\n- `needs-look`: the extract finished but its amounts don't add up, or the two printed reads disagree.\n- `flagged`: the extract finished but a step errored or the verify pass flagged it.\n- `extracting`: the extract hasn't finished.\n- `bind-*`: unbound, and the last auto-bind check stopped for this reason." }, "ReceiptIssueFilter": { "anyOf": [ { "$ref": "#/components/schemas/ReceiptIssue" }, { "type": "string", "enum": [ "any" ] } ], "description": "`any` is every issue except the ones a fresh receipt has while it waits: extracting and no charge yet." }, "CreateReceiptDto": { "properties": { "transactionId": { "type": "string" }, "processed": { "type": "string" }, "frames": { "items": { "type": "string" }, "type": "array" } }, "required": [ "frames" ], "type": "object" }, "ClosePairReason": { "type": "string", "enum": [ "fuzzy-tip", "blocked-exact" ] }, "ClosePairMatch": { "properties": { "tipRatio": { "type": "number", "format": "double" }, "tipMilliunits": { "type": "number", "format": "double" }, "payeeSimilarity": { "type": "number", "format": "double" }, "reason": { "$ref": "#/components/schemas/ClosePairReason" }, "transactionId": { "type": "string" }, "receiptId": { "type": "string" } }, "required": [ "tipRatio", "tipMilliunits", "payeeSimilarity", "reason", "transactionId", "receiptId" ], "type": "object" }, "ReceiptMatchCloseDto": { "$ref": "#/components/schemas/ClosePairMatch" }, "ReceiptBindCandidateDto": { "properties": { "memo": { "type": "string", "nullable": true }, "categoryName": { "type": "string", "nullable": true }, "accountName": { "type": "string" }, "importPayeeNameOriginal": { "type": "string", "nullable": true }, "importPayeeName": { "type": "string", "nullable": true }, "payeeName": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "double" }, "date": { "type": "string" }, "id": { "type": "string" } }, "required": [ "memo", "categoryName", "accountName", "importPayeeNameOriginal", "importPayeeName", "payeeName", "amount", "date", "id" ], "type": "object" }, "ReceiptSplitDraftCategoryDto": { "properties": { "groupName": { "type": "string" }, "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "groupName", "name", "id" ], "type": "object" }, "ReceiptSplitDraftLineDto": { "properties": { "category": { "$ref": "#/components/schemas/ReceiptSplitDraftCategoryDto", "description": "Pre-picked category (the reimbursable share); absent when the reviewer picks." }, "memo": { "type": "string", "nullable": true }, "amountMilliunits": { "type": "number", "format": "double" } }, "required": [ "memo", "amountMilliunits" ], "type": "object" }, "ReceiptSplitDraftDto": { "properties": { "lines": { "items": { "$ref": "#/components/schemas/ReceiptSplitDraftLineDto" }, "type": "array" }, "kind": { "type": "string", "enum": [ "single", "split" ] } }, "required": [ "lines", "kind" ], "type": "object" }, "ReceiptMatchDto": { "properties": { "splitDraft": { "allOf": [ { "$ref": "#/components/schemas/ReceiptSplitDraftDto" } ], "nullable": true }, "bindCandidates": { "items": { "$ref": "#/components/schemas/ReceiptBindCandidateDto" }, "type": "array" }, "closeMatches": { "items": { "$ref": "#/components/schemas/ReceiptMatchCloseDto" }, "type": "array" }, "exactTransactionId": { "type": "string", "nullable": true }, "exactReceiptId": { "type": "string", "nullable": true }, "autoBind": { "type": "boolean" }, "amazonSkipped": { "type": "boolean" } }, "required": [ "splitDraft", "bindCandidates", "closeMatches", "exactTransactionId", "exactReceiptId", "autoBind", "amazonSkipped" ], "type": "object" }, "MatchPreviewReceiptDto": { "properties": { "extractJson": { "type": "string", "nullable": true }, "extractStatus": { "allOf": [ { "$ref": "#/components/schemas/ReceiptExtractStatus" } ], "nullable": true }, "totalsDisagree": { "type": "boolean" }, "printedMilliunits": { "type": "number", "format": "double", "nullable": true }, "purchaseDate": { "type": "string", "nullable": true }, "vendor": { "type": "string", "nullable": true }, "id": { "type": "string" } }, "required": [ "totalsDisagree", "printedMilliunits", "purchaseDate", "vendor", "id" ], "type": "object" }, "MatchPreviewTransactionDto": { "properties": { "importPayeeNameOriginal": { "type": "string", "nullable": true }, "importPayeeName": { "type": "string", "nullable": true }, "payeeName": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "double" }, "date": { "type": "string" }, "id": { "type": "string" } }, "required": [ "importPayeeNameOriginal", "importPayeeName", "payeeName", "amount", "date", "id" ], "type": "object" }, "MatchPreviewDto": { "properties": { "extraDays": { "type": "number", "format": "double", "description": "Receipt-only preview: widen the listed charges by this many days either side (0, 14, 30, 90 or 365)." }, "transaction": { "$ref": "#/components/schemas/MatchPreviewTransactionDto" }, "transactionId": { "type": "string" }, "receipts": { "items": { "$ref": "#/components/schemas/MatchPreviewReceiptDto" }, "type": "array" } }, "required": [ "receipts" ], "type": "object" }, "ExtractPreviewResultDto": { "properties": { "rawText": { "type": "string", "nullable": true }, "extractJson": { "type": "string", "nullable": true }, "totalsDisagree": { "type": "boolean" }, "printedMilliunits": { "type": "number", "format": "double", "nullable": true }, "purchaseDate": { "type": "string", "nullable": true }, "vendor": { "type": "string", "nullable": true }, "extractStatus": { "allOf": [ { "$ref": "#/components/schemas/ReceiptExtractStatus" } ], "nullable": true }, "droppedAsAmazon": { "type": "boolean" } }, "required": [ "rawText", "extractJson", "totalsDisagree", "printedMilliunits", "purchaseDate", "vendor", "extractStatus", "droppedAsAmazon" ], "type": "object" }, "ExtractPreviewDto": { "properties": { "processed": { "type": "string" }, "frames": { "items": { "type": "string" }, "type": "array" } }, "required": [ "frames" ], "type": "object" }, "PatchReceiptLineDto": { "properties": { "quantity": { "type": "number", "format": "double", "nullable": true }, "amountMilliunits": { "type": "number", "format": "double", "nullable": true }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "PatchReceiptReimbursableDto": { "properties": { "amountMilliunits": { "type": "number", "format": "double", "nullable": true, "description": "The reimbursable share, positive; null when only the mark is known." } }, "required": [ "amountMilliunits" ], "type": "object" }, "PatchReceiptDto": { "properties": { "reimbursable": { "allOf": [ { "$ref": "#/components/schemas/PatchReceiptReimbursableDto" } ], "nullable": true, "description": "Omit to keep the extracted reimbursable mark; null clears it." }, "lines": { "items": { "$ref": "#/components/schemas/PatchReceiptLineDto" }, "type": "array" }, "tipMilliunits": { "type": "number", "format": "double", "description": "Omit to keep the previously extracted tip." }, "discountMilliunits": { "type": "number", "format": "double" }, "taxMilliunits": { "type": "number", "format": "double" }, "printedMilliunits": { "type": "number", "format": "double", "nullable": true }, "purchaseDate": { "type": "string", "nullable": true }, "vendor": { "type": "string", "nullable": true } }, "required": [ "lines", "discountMilliunits", "taxMilliunits", "printedMilliunits", "purchaseDate", "vendor" ], "type": "object" }, "BindReceiptDto": { "properties": { "transactionId": { "type": "string" } }, "required": [ "transactionId" ], "type": "object" }, "PeriodicCadence": { "type": "string", "enum": [ "Weekly", "Biweekly", "Monthly", "Quarterly", "Yearly" ] }, "TransactionClearedStatus": { "type": "string", "enum": [ "uncleared", "cleared", "reconciled" ], "description": "YNAB `cleared` field. Uncleared transactions are excluded from the review queue." }, "YnabFlagColor": { "type": "string", "enum": [ "red", "orange", "yellow", "green", "blue", "purple" ], "description": "YNAB transaction `flag_color`. Kept as a literal union so tsoa can describe it." }, "TransactionDetailDto": { "properties": { "importPayeeNameOriginal": { "type": "string", "nullable": true }, "importPayeeName": { "type": "string", "nullable": true }, "importId": { "type": "string", "nullable": true }, "categoryName": { "type": "string", "nullable": true }, "categoryId": { "type": "string", "nullable": true }, "payeeName": { "type": "string", "nullable": true }, "payeeId": { "type": "string", "nullable": true }, "accountName": { "type": "string" }, "accountId": { "type": "string" }, "flagName": { "type": "string", "nullable": true, "description": "YNAB's user-defined name for `flagColor`, when set." }, "flagColor": { "allOf": [ { "$ref": "#/components/schemas/YnabFlagColor" } ], "nullable": true, "description": "YNAB flag color, or null when unflagged. Unrelated to the ML `CategorizationFlagsDto`." }, "approved": { "type": "boolean" }, "cleared": { "$ref": "#/components/schemas/TransactionClearedStatus" }, "memo": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "double" }, "date": { "type": "string" }, "id": { "type": "string" } }, "required": [ "importPayeeNameOriginal", "importPayeeName", "importId", "categoryName", "categoryId", "payeeName", "payeeId", "accountName", "accountId", "flagName", "flagColor", "approved", "cleared", "memo", "amount", "date", "id" ], "type": "object" }, "PeriodicSeriesDto": { "properties": { "relatedTransactions": { "items": { "$ref": "#/components/schemas/TransactionDetailDto" }, "type": "array" }, "relatedTransactionIds": { "items": { "type": "string" }, "type": "array" }, "cadenceFit": { "type": "number", "format": "double" }, "categoryStable": { "type": "boolean" }, "categoryVoteShare": { "type": "number", "format": "double" }, "category": { "type": "string", "nullable": true, "description": "Majority historical category, or null when the series has no usable labels." }, "expectedNextDate": { "type": "string" }, "lastDate": { "type": "string" }, "medianAmount": { "type": "number", "format": "double" }, "occurrenceCount": { "type": "number", "format": "double" }, "cadence": { "$ref": "#/components/schemas/PeriodicCadence" }, "payeeName": { "type": "string" }, "id": { "type": "string" } }, "required": [ "relatedTransactions", "relatedTransactionIds", "cadenceFit", "categoryStable", "categoryVoteShare", "category", "expectedNextDate", "lastDate", "medianAmount", "occurrenceCount", "cadence", "payeeName", "id" ], "type": "object" }, "PeriodicSeriesListDto": { "properties": { "series": { "items": { "$ref": "#/components/schemas/PeriodicSeriesDto" }, "type": "array" } }, "required": [ "series" ], "type": "object" }, "OperatingModeDto": { "properties": { "mode": { "type": "string", "enum": [ "practice", "live" ] } }, "required": [ "mode" ], "type": "object" }, "HealthDto": { "properties": { "ok": { "type": "boolean", "enum": [ true ], "nullable": false } }, "required": [ "ok" ], "type": "object" }, "QueueSummaryDto": { "properties": { "blocked": { "type": "number", "format": "double" }, "review": { "type": "number", "format": "double" }, "suggested": { "type": "number", "format": "double" }, "autoApply": { "type": "number", "format": "double" }, "total": { "type": "number", "format": "double" } }, "required": [ "blocked", "review", "suggested", "autoApply", "total" ], "type": "object" }, "ApprovalTier": { "type": "string", "enum": [ "AutoApply", "Suggested", "Review", "Blocked" ] }, "CategorizationFlagsDto": { "properties": { "isTravelWindow": { "type": "boolean" }, "isPeriodicConflict": { "type": "boolean" }, "isPeriodic": { "type": "boolean" }, "requiresManualReview": { "type": "boolean" }, "isExcluded": { "type": "boolean" }, "isNovelImport": { "type": "boolean" }, "isAmbiguous": { "type": "boolean" } }, "required": [ "isTravelWindow", "isPeriodicConflict", "isPeriodic", "requiresManualReview", "isExcluded", "isNovelImport", "isAmbiguous" ], "type": "object" }, "CategorizationMethod": { "type": "string", "enum": [ "ImportAmountLookup", "ImportLookup", "PayeeIdLookup", "CanonicalPayeeLookup", "PayeeClusterLookup", "PayeeModel", "HierarchicalModel", "CategoryModel", "PeriodicSeriesLookup", "Consensus", "LlmCategorization", "TravelWindow", "Excluded", "ManualReview", "None" ] }, "CategorizationRouteReason": { "type": "string", "enum": [ "None", "ExcludedPayee", "ExcludedCheck", "AmbiguousMerchant", "UntrainedCategory", "NovelImportString", "LowConfidence" ] }, "ProposalGapReason": { "type": "string", "enum": [ "None", "AmbiguousMerchant", "InsufficientAgreement", "TwoMethodSuggestion", "SingleMethodSuggestion", "ImportAmountNearMiss", "NoQualifiedSignals", "LlmSuggestion", "Excluded", "PeriodicConflict" ] }, "MethodSignalDto": { "properties": { "confidence": { "type": "number", "format": "double" }, "category": { "type": "string" }, "method": { "$ref": "#/components/schemas/CategorizationMethod" } }, "required": [ "confidence", "category", "method" ], "type": "object" }, "CategoryOptionDto": { "properties": { "supportingMethods": { "items": { "$ref": "#/components/schemas/MethodSignalDto" }, "type": "array" }, "confidence": { "type": "number", "format": "double" }, "categoryId": { "type": "string", "nullable": true }, "categoryGroup": { "type": "string", "nullable": true }, "category": { "type": "string" }, "rank": { "type": "number", "format": "double" } }, "required": [ "supportingMethods", "confidence", "categoryId", "categoryGroup", "category", "rank" ], "type": "object" }, "ConfidenceIntervalDto": { "properties": { "spread": { "type": "number", "format": "double" }, "third": { "type": "number", "format": "double", "nullable": true }, "second": { "type": "number", "format": "double", "nullable": true }, "top": { "type": "number", "format": "double" } }, "required": [ "spread", "third", "second", "top" ], "type": "object" }, "PayeeResolutionMethod": { "type": "string", "enum": [ "ExactLookup", "ClusterLookup", "Model", "Llm", "Unresolved" ] }, "PayeeSuggestionDto": { "properties": { "needsRename": { "type": "boolean" }, "confidence": { "type": "number", "format": "double" }, "method": { "$ref": "#/components/schemas/PayeeResolutionMethod" }, "name": { "type": "string" } }, "required": [ "needsRename", "confidence", "method", "name" ], "type": "object" }, "PeriodicMatchDto": { "properties": { "cadenceFit": { "type": "number", "format": "double" }, "relatedTransactionIds": { "items": { "type": "string" }, "type": "array" }, "categoryVoteShare": { "type": "number", "format": "double" }, "category": { "type": "string", "nullable": true, "description": "Majority historical category, or null when the series has no usable labels." }, "lastDate": { "type": "string" }, "medianAmount": { "type": "number", "format": "double" }, "occurrenceCount": { "type": "number", "format": "double" }, "cadence": { "$ref": "#/components/schemas/PeriodicCadence" } }, "required": [ "cadenceFit", "relatedTransactionIds", "categoryVoteShare", "category", "lastDate", "medianAmount", "occurrenceCount", "cadence" ], "type": "object" }, "TravelLocationMatch": { "type": "string", "enum": [ "match", "mismatch", "unknown", "unspecified" ] }, "TravelWindowHitDto": { "properties": { "merchantCity": { "type": "string", "nullable": true }, "locationMatch": { "$ref": "#/components/schemas/TravelLocationMatch" }, "location": { "type": "string", "nullable": true }, "targetCategory": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "vacation", "work" ] }, "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "merchantCity", "locationMatch", "location", "targetCategory", "kind", "name", "id" ], "type": "object" }, "CategorizationProposalDto": { "properties": { "travelWindow": { "allOf": [ { "$ref": "#/components/schemas/TravelWindowHitDto" } ], "nullable": true }, "periodicMatch": { "allOf": [ { "$ref": "#/components/schemas/PeriodicMatchDto" } ], "nullable": true }, "notes": { "type": "string", "nullable": true }, "payeeSuggestion": { "allOf": [ { "$ref": "#/components/schemas/PayeeSuggestionDto" } ], "nullable": true }, "resolvedPayee": { "type": "string", "nullable": true }, "featureText": { "type": "string" }, "confidenceInterval": { "$ref": "#/components/schemas/ConfidenceIntervalDto" }, "options": { "items": { "$ref": "#/components/schemas/CategoryOptionDto" }, "type": "array" }, "agreeingSignals": { "items": { "$ref": "#/components/schemas/MethodSignalDto" }, "type": "array" }, "signals": { "items": { "$ref": "#/components/schemas/MethodSignalDto" }, "type": "array" }, "gapReason": { "$ref": "#/components/schemas/ProposalGapReason" }, "routeReason": { "$ref": "#/components/schemas/CategorizationRouteReason" }, "method": { "$ref": "#/components/schemas/CategorizationMethod" }, "confidence": { "type": "number", "format": "double" }, "suggestedCategoryId": { "type": "string", "nullable": true }, "suggestedCategoryGroup": { "type": "string", "nullable": true }, "suggestedCategory": { "type": "string", "nullable": true }, "flags": { "$ref": "#/components/schemas/CategorizationFlagsDto" }, "tier": { "$ref": "#/components/schemas/ApprovalTier" }, "transactionId": { "type": "string" } }, "required": [ "travelWindow", "periodicMatch", "notes", "payeeSuggestion", "resolvedPayee", "featureText", "confidenceInterval", "options", "agreeingSignals", "signals", "gapReason", "routeReason", "method", "confidence", "suggestedCategoryId", "suggestedCategoryGroup", "suggestedCategory", "flags", "tier", "transactionId" ], "type": "object" }, "CategorizationQueueItemDto": { "properties": { "relatedTransactions": { "items": { "$ref": "#/components/schemas/TransactionDetailDto" }, "type": "array", "description": "Prior charges in this periodic series, newest first (ids from `proposal.periodicMatch`)." }, "proposal": { "allOf": [ { "$ref": "#/components/schemas/CategorizationProposalDto" } ], "nullable": true, "description": "Local ML proposal when the transaction has been scored; otherwise null." }, "transaction": { "$ref": "#/components/schemas/TransactionDetailDto" } }, "required": [ "relatedTransactions", "proposal", "transaction" ], "type": "object" }, "CategorizationQueueDto": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CategorizationQueueItemDto" }, "type": "array" }, "hasMoreOlder": { "type": "boolean", "description": "True when older pending rows exist after this response window." }, "hasMoreNewer": { "type": "boolean", "description": "True when newer pending rows exist before this response window." }, "hasMore": { "type": "boolean", "description": "True when pending transactions exist that have not been scored yet." }, "scoredCount": { "type": "number", "format": "double", "description": "Unfiltered scored working-set size." }, "pendingCount": { "type": "number", "format": "double" }, "llm": { "type": "boolean" }, "generatedAt": { "type": "string" }, "summary": { "$ref": "#/components/schemas/QueueSummaryDto" } }, "required": [ "items", "hasMoreOlder", "hasMoreNewer", "hasMore", "scoredCount", "pendingCount", "llm", "generatedAt", "summary" ], "type": "object" }, "LlmSuggestOverlayDto": { "properties": { "options": { "items": { "$ref": "#/components/schemas/CategoryOptionDto" }, "type": "array", "description": "Ranked LLM categories: primary first, then an optional everyday/trip counterpart." }, "payeeSuggestion": { "allOf": [ { "$ref": "#/components/schemas/PayeeSuggestionDto" } ], "nullable": true }, "notes": { "type": "string", "nullable": true }, "confidence": { "type": "number", "format": "double" }, "suggestedCategoryId": { "type": "string", "nullable": true }, "suggestedCategoryGroup": { "type": "string", "nullable": true }, "suggestedCategory": { "type": "string", "nullable": true }, "model": { "type": "string" }, "transactionId": { "type": "string" } }, "required": [ "options", "payeeSuggestion", "notes", "confidence", "suggestedCategoryId", "suggestedCategoryGroup", "suggestedCategory", "model", "transactionId" ], "type": "object" }, "LlmSuggestRequestDto": { "properties": { "forceRefresh": { "type": "boolean", "description": "Bypass the cached overlay and ask the LLM again." }, "transactionId": { "type": "string" } }, "required": [ "transactionId" ], "type": "object" }, "AmazonMatchKindDto": { "type": "string", "enum": [ "payment", "batched-orders", "partial-order", "unmatched" ] }, "AmazonMatchedPaymentDto": { "properties": { "isRefund": { "type": "boolean" }, "vendor": { "type": "string", "nullable": true }, "cardLast4": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "amount": { "type": "number", "format": "double" }, "paymentDate": { "type": "string" }, "id": { "type": "string" } }, "required": [ "isRefund", "vendor", "cardLast4", "currency", "amount", "paymentDate", "id" ], "type": "object" }, "AmazonMatchedOrderDto": { "properties": { "promotion": { "type": "number", "format": "double", "nullable": true }, "shipping": { "type": "number", "format": "double", "nullable": true }, "tax": { "type": "number", "format": "double", "nullable": true }, "total": { "type": "number", "format": "double", "nullable": true }, "orderDate": { "type": "string", "nullable": true }, "orderId": { "type": "string" } }, "required": [ "promotion", "shipping", "tax", "total", "orderDate", "orderId" ], "type": "object" }, "AmazonSplitItemDto": { "properties": { "categoryGroup": { "type": "string", "nullable": true }, "categoryName": { "type": "string", "nullable": true }, "categoryId": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "double" }, "quantity": { "type": "number", "format": "double" }, "asin": { "type": "string", "nullable": true }, "title": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "categoryGroup", "categoryName", "categoryId", "amount", "quantity", "asin", "title", "orderId" ], "type": "object" }, "AmazonSplitLineDto": { "properties": { "memo": { "type": "string", "nullable": true }, "categoryGroup": { "type": "string" }, "categoryName": { "type": "string" }, "categoryId": { "type": "string" }, "amount": { "type": "number", "format": "double" } }, "required": [ "memo", "categoryGroup", "categoryName", "categoryId", "amount" ], "type": "object" }, "AmazonSplitOverlayDto": { "properties": { "notes": { "type": "string", "nullable": true }, "rationale": { "type": "string", "nullable": true }, "collapsed": { "type": "boolean" }, "lines": { "items": { "$ref": "#/components/schemas/AmazonSplitLineDto" }, "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/AmazonSplitItemDto" }, "type": "array" }, "orderIds": { "items": { "type": "string" }, "type": "array" }, "orders": { "items": { "$ref": "#/components/schemas/AmazonMatchedOrderDto" }, "type": "array" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/AmazonMatchedPaymentDto" } ], "nullable": true }, "match": { "$ref": "#/components/schemas/AmazonMatchKindDto" }, "dataStatus": { "type": "string", "enum": [ "ready", "not-synced" ] }, "transactionId": { "type": "string" } }, "required": [ "notes", "rationale", "collapsed", "lines", "items", "orderIds", "orders", "payment", "match", "dataStatus", "transactionId" ], "type": "object" }, "AmazonSuggestRequestDto": { "properties": { "transactionId": { "type": "string" } }, "required": [ "transactionId" ], "type": "object" }, "CategorizationPredictDto": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CategorizationQueueItemDto" }, "type": "array" }, "generatedAt": { "type": "string" } }, "required": [ "items", "generatedAt" ], "type": "object" }, "CategorizationPredictRequestDto": { "properties": { "transactionIds": { "items": { "type": "string" }, "type": "array" } }, "required": [ "transactionIds" ], "type": "object" }, "ClassificationDecisionsResponseDto": { "properties": { "pendingCount": { "type": "number", "format": "double" }, "accepted": { "type": "number", "format": "double" } }, "required": [ "pendingCount", "accepted" ], "type": "object" }, "ClassificationDecisionKind": { "type": "string", "enum": [ "category", "split", "annotate" ], "description": "`category` and `split` categorize and approve the transaction.\n`annotate` only sets the parent memo and/or YNAB flag; the transaction stays in the review queue." }, "ClassificationDecisionLineDto": { "properties": { "memo": { "type": "string", "nullable": true }, "categoryId": { "type": "string" }, "amount": { "type": "number", "format": "double" } }, "required": [ "categoryId", "amount" ], "type": "object" }, "ClassificationDecisionDto": { "properties": { "flagColor": { "allOf": [ { "$ref": "#/components/schemas/YnabFlagColor" } ], "nullable": true, "description": "YNAB flag. Omit to leave YNAB's flag unchanged; null clears it. Annotate needs memo and/or flagColor." }, "memo": { "type": "string", "nullable": true, "description": "Parent transaction memo, at most 500 characters. Omit to leave YNAB's memo unchanged;\nnull or blank clears it. Annotate needs memo and/or flagColor." }, "lines": { "items": { "$ref": "#/components/schemas/ClassificationDecisionLineDto" }, "type": "array", "description": "Required when kind is split. Not allowed for category or annotate." }, "payeeName": { "type": "string", "description": "Not allowed for annotate." }, "categoryId": { "type": "string", "description": "Required when kind is category. Not allowed for split or annotate." }, "kind": { "$ref": "#/components/schemas/ClassificationDecisionKind" }, "transactionId": { "type": "string" } }, "required": [ "kind", "transactionId" ], "type": "object" }, "ClassificationDecisionsRequestDto": { "properties": { "decisions": { "items": { "$ref": "#/components/schemas/ClassificationDecisionDto" }, "type": "array" } }, "required": [ "decisions" ], "type": "object" }, "OutboundSyncStatusDto": { "properties": { "lastError": { "type": "string", "nullable": true }, "oldestPendingAt": { "type": "string", "nullable": true }, "syncedUnconfirmedCount": { "type": "number", "format": "double" }, "failedCount": { "type": "number", "format": "double" }, "syncingCount": { "type": "number", "format": "double" }, "pendingCount": { "type": "number", "format": "double" } }, "required": [ "lastError", "oldestPendingAt", "syncedUnconfirmedCount", "failedCount", "syncingCount", "pendingCount" ], "type": "object" }, "OutboundSyncFlushDto": { "properties": { "skipReason": { "type": "string" }, "skipped": { "type": "boolean" }, "failed": { "type": "number", "format": "double" }, "synced": { "type": "number", "format": "double" }, "attempted": { "type": "number", "format": "double" } }, "required": [ "skipped", "failed", "synced", "attempted" ], "type": "object" }, "YnabFlagDto": { "properties": { "name": { "type": "string", "nullable": true, "description": "Most recent YNAB name seen on a mirrored transaction with this color, or null." }, "color": { "$ref": "#/components/schemas/YnabFlagColor" } }, "required": [ "name", "color" ], "type": "object" }, "YnabFlagsDto": { "properties": { "flags": { "items": { "$ref": "#/components/schemas/YnabFlagDto" }, "type": "array", "description": "Every YNAB flag color, in YNAB's display order." } }, "required": [ "flags" ], "type": "object" }, "CategoryDto": { "properties": { "note": { "type": "string", "nullable": true }, "hidden": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "note", "hidden", "name", "id" ], "type": "object" }, "CategoryGroupDto": { "properties": { "categories": { "items": { "$ref": "#/components/schemas/CategoryDto" }, "type": "array" }, "hidden": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "categories", "hidden", "name", "id" ], "type": "object" }, "CategoriesDto": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/CategoryGroupDto" }, "type": "array" } }, "required": [ "groups" ], "type": "object" }, "AuthUserDto": { "properties": { "username": { "type": "string" }, "id": { "type": "string" } }, "required": [ "username", "id" ], "type": "object", "description": "The signed-in principal. Deliberately carries no hash, no session id, and no token." }, "LoginResponseDto": { "properties": { "expiresAt": { "type": "string", "description": "ISO instant at which the session lapses if unused. Slides forward as the app is used." }, "user": { "$ref": "#/components/schemas/AuthUserDto" } }, "required": [ "expiresAt", "user" ], "type": "object" }, "LoginRequestDto": { "properties": { "password": { "type": "string" }, "username": { "type": "string" } }, "required": [ "password", "username" ], "type": "object" }, "LogoutResponseDto": { "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "ChangePasswordResponseDto": { "properties": { "revokedSessions": { "type": "number", "format": "double", "description": "How many other sessions were signed out. The caller's own session is kept alive." }, "ok": { "type": "boolean" } }, "required": [ "revokedSessions", "ok" ], "type": "object" }, "ChangePasswordRequestDto": { "properties": { "newPassword": { "type": "string" }, "currentPassword": { "type": "string" } }, "required": [ "newPassword", "currentPassword" ], "type": "object" }, "AmazonOrdersDateRangeDto": { "properties": { "end": { "type": "string" }, "start": { "type": "string" } }, "required": [ "end", "start" ], "type": "object" }, "AmazonOrdersStatusDto": { "properties": { "items": { "type": "number", "format": "double" }, "orders": { "type": "number", "format": "double" }, "payments": { "type": "number", "format": "double" }, "coveredRanges": { "items": { "$ref": "#/components/schemas/AmazonOrdersDateRangeDto" }, "type": "array" }, "lastAuthenticated": { "type": "boolean" }, "lastAuthCheck": { "type": "string", "nullable": true }, "mcpConfigured": { "type": "boolean" }, "region": { "type": "string" } }, "required": [ "items", "orders", "payments", "coveredRanges", "lastAuthenticated", "lastAuthCheck", "mcpConfigured", "region" ], "type": "object" }, "AmazonOrdersSyncDto": { "properties": { "coveredRanges": { "items": { "$ref": "#/components/schemas/AmazonOrdersDateRangeDto" }, "type": "array" }, "items": { "type": "number", "format": "double" }, "orders": { "type": "number", "format": "double" }, "payments": { "type": "number", "format": "double" }, "fetchedOrderIds": { "items": { "type": "string" }, "type": "array" }, "scrapedPaymentGaps": { "items": { "$ref": "#/components/schemas/AmazonOrdersDateRangeDto" }, "type": "array" }, "to": { "type": "string" }, "from": { "type": "string" }, "region": { "type": "string" } }, "required": [ "coveredRanges", "items", "orders", "payments", "fetchedOrderIds", "scrapedPaymentGaps", "to", "from", "region" ], "type": "object" }, "AmazonOrdersSyncRequestDto": { "properties": { "region": { "type": "string" }, "to": { "type": "string" }, "from": { "type": "string" } }, "required": [ "to", "from" ], "type": "object" } }, "securitySchemes": {} }, "info": { "title": "@budget-tools/api", "version": "0.0.0", "contact": {} }, "paths": { "/travel-windows": { "get": { "operationId": "ListTravelWindows", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelWindowsDto" } } } } }, "summary": "listTravelWindows", "tags": [ "travel-windows" ], "security": [], "parameters": [] }, "post": { "operationId": "CreateTravelWindow", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelWindowDto" } } } }, "409": { "description": "Overlapping travel window" } }, "summary": "createTravelWindow", "tags": [ "travel-windows" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelWindowWriteDto" } } } } } }, "/travel-windows/{id}": { "put": { "operationId": "UpdateTravelWindow", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelWindowDto" } } } }, "409": { "description": "Overlapping travel window" } }, "summary": "updateTravelWindow", "tags": [ "travel-windows" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelWindowWriteDto" } } } } }, "delete": { "operationId": "DeleteTravelWindow", "responses": { "204": { "description": "No content" } }, "summary": "deleteTravelWindow", "tags": [ "travel-windows" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/travel-bias": { "get": { "operationId": "GetTravelBias", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelBiasDto" } } } } }, "summary": "getTravelBias", "tags": [ "travel-bias" ], "security": [], "parameters": [] }, "patch": { "operationId": "PatchTravelBias", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelBiasDto" } } } } }, "summary": "patchTravelBias", "tags": [ "travel-bias" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelBiasDto" } } } } } }, "/accounts": { "get": { "operationId": "ListAccounts", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsDto" } } } } }, "description": "Distinct YNAB accounts present on synced transactions, for the trip card picker.", "summary": "listAccounts", "tags": [ "accounts" ], "security": [], "parameters": [] } }, "/spend-chart": { "get": { "operationId": "GetSpendChart", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendChartDto" } } } } }, "description": "Daily spend per category, with smoothed categories spread over their window.", "summary": "getSpendChart", "tags": [ "spend-chart" ], "security": [], "parameters": [ { "description": "First day, `YYYY-MM-DD`.", "in": "query", "name": "start", "required": true, "schema": { "type": "string" } }, { "description": "Last day, `YYYY-MM-DD`, inclusive.", "in": "query", "name": "end", "required": true, "schema": { "type": "string" } } ] } }, "/spend-chart/smoothing/{categoryId}": { "put": { "operationId": "PutCategorySmoothing", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategorySmoothingDto" } } } } }, "description": "Sets how many days each purchase in a category is spread over. 1 turns smoothing off.", "summary": "putCategorySmoothing", "tags": [ "spend-chart" ], "security": [], "parameters": [ { "in": "path", "name": "categoryId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategorySmoothingWriteDto" } } } } } }, "/receipts": { "get": { "operationId": "ListReceipts", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptsDto" } } } }, "400": { "description": "Invalid page" } }, "description": "Newest first. Without `limit` every receipt comes back in one response; with it, pass\nthe previous page's `nextCursor` as `cursor` to continue.", "summary": "listReceipts", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "format": "double", "type": "number" } }, { "description": "Case-insensitive substring filter over vendor, date, total, extracted lines, and the reimbursable note; every term must match", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Only receipts marked reimbursable", "in": "query", "name": "reimbursable", "required": false, "schema": { "type": "boolean" } }, { "description": "Only receipts bound to a transaction, or only unbound ones", "in": "query", "name": "bound", "required": false, "schema": { "$ref": "#/components/schemas/ReceiptBoundFilter" } }, { "description": "Only receipts with this problem; `any` leaves out the waiting states (`extracting`, `bind-no-charge`)", "in": "query", "name": "issue", "required": false, "schema": { "$ref": "#/components/schemas/ReceiptIssueFilter" } } ] }, "post": { "operationId": "CreateReceipt", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptDto" } } } }, "400": { "description": "Invalid frames" }, "403": { "description": "Practice mode" }, "413": { "description": "JSON body too large" } }, "summary": "createReceipt", "tags": [ "receipts" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReceiptDto" } } } } } }, "/receipts/lookup-by-transaction": { "get": { "operationId": "LookupByTransaction", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptMatchDto" } } } }, "403": { "description": "Practice mode" }, "404": { "description": "Not found" } }, "summary": "lookupByTransaction", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "query", "name": "transactionId", "required": true, "schema": { "type": "string" } } ] } }, "/receipts/lookup-by-receipt": { "get": { "operationId": "LookupByReceipt", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptMatchDto" } } } }, "400": { "description": "Invalid extraDays" }, "403": { "description": "Practice mode" }, "404": { "description": "Not found" } }, "summary": "lookupByReceipt", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "query", "name": "receiptId", "required": true, "schema": { "type": "string" } }, { "description": "Widen the listed charges by this many days either side of the receipt date (0, 14, 30, 90 or 365). Matching and auto-bind ignore it.", "in": "query", "name": "extraDays", "required": false, "schema": { "format": "double", "type": "number" } } ] } }, "/receipts/match-preview": { "post": { "operationId": "MatchPreview", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptMatchDto" } } } }, "400": { "description": "Invalid preview" }, "404": { "description": "Not found" } }, "summary": "matchPreview", "tags": [ "receipts" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchPreviewDto" } } } } } }, "/receipts/extract-preview": { "post": { "operationId": "ExtractPreview", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractPreviewResultDto" } } } }, "400": { "description": "Invalid frames" }, "503": { "description": "Extract unavailable" } }, "summary": "extractPreview", "tags": [ "receipts" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractPreviewDto" } } } } } }, "/receipts/{id}/image": { "get": { "operationId": "GetReceiptImage", "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid frame" }, "404": { "description": "Not found" } }, "summary": "getReceiptImage", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "variant", "required": false, "schema": { "default": "original", "type": "string", "enum": [ "original", "processed", "thumb" ] } }, { "in": "query", "name": "frame", "required": false, "schema": { "default": 0, "format": "double", "type": "number" } } ] } }, "/receipts/{id}": { "get": { "operationId": "GetReceipt", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptDto" } } } }, "404": { "description": "Not found" } }, "summary": "getReceipt", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "patch": { "operationId": "PatchReceipt", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptDto" } } } }, "400": { "description": "Invalid extract edit" }, "403": { "description": "Practice mode" }, "404": { "description": "Not found" }, "409": { "description": "Extract still pending" } }, "summary": "patchReceipt", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchReceiptDto" } } } } }, "delete": { "operationId": "DeleteReceipt", "responses": { "204": { "description": "No content" }, "403": { "description": "Practice mode" } }, "summary": "deleteReceipt", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/receipts/{id}/retry-extract": { "post": { "operationId": "RetryReceiptExtract", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptDto" } } } }, "403": { "description": "Practice mode" }, "404": { "description": "Not found" }, "409": { "description": "Extract is already pending" } }, "summary": "retryReceiptExtract", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/receipts/{id}/bind": { "post": { "operationId": "BindReceipt", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptDto" } } } }, "403": { "description": "Practice mode" }, "404": { "description": "Not found" } }, "summary": "bindReceipt", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindReceiptDto" } } } } }, "delete": { "operationId": "DetachReceipt", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptDto" } } } }, "403": { "description": "Practice mode" }, "404": { "description": "Not found" } }, "description": "Detaching also stops the background binder from re-attaching this charge.", "summary": "detachReceipt", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/receipts/{id}/auto-bind": { "post": { "operationId": "AutoBindReceipt", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptDto" } } } }, "404": { "description": "Not found" } }, "description": "Runs the server auto-bind (exact amount + Jev confirmation) for an unbound\nreceipt right now instead of waiting for the background sweep. A no-op for\nbound, incomplete, or Practice receipts.", "summary": "autoBindReceipt", "tags": [ "receipts" ], "security": [], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/periodic-series": { "get": { "operationId": "ListPeriodicSeries", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeriodicSeriesListDto" } } } }, "503": { "description": "Warm scorer unavailable" } }, "description": "Catalog of repeating series detected from ledger history.", "summary": "listPeriodicSeries", "tags": [ "periodic-series" ], "security": [], "parameters": [] } }, "/operating-mode": { "get": { "operationId": "GetOperatingMode", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatingModeDto" } } } } }, "summary": "getOperatingMode", "tags": [ "operating-mode" ], "security": [], "parameters": [] }, "patch": { "operationId": "PatchOperatingMode", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatingModeDto" } } } } }, "summary": "patchOperatingMode", "tags": [ "operating-mode" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatingModeDto" } } } } } }, "/health": { "get": { "operationId": "GetHealth", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthDto" } } } } }, "tags": [ "health" ], "security": [], "parameters": [] } }, "/categorization/queue": { "get": { "operationId": "GetCategorizationQueue", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategorizationQueueDto" } } } } }, "description": "Pending review queue joined to cached local ML proposals.\nWindow queries (`around` / `olderThan` / `newerThan`) list pending rows without scoring.", "tags": [ "categorization" ], "security": [], "parameters": [ { "description": "Comma-separated ApprovalTier values to include", "in": "query", "name": "tier", "required": false, "schema": { "type": "string" } }, { "description": "Filter to a single YNAB account id", "in": "query", "name": "accountId", "required": false, "schema": { "type": "string" } }, { "description": "Case-insensitive substring filter over payee, import names, memo, category, account, date, and amount", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Discard cached scores and rescore the newest batch", "in": "query", "name": "refresh", "required": false, "schema": { "type": "boolean" } }, { "description": "Score the next never-scored batch; ignored when refresh is true", "in": "query", "name": "expand", "required": false, "schema": { "type": "boolean" } }, { "description": "Center a pending window on this transaction id", "in": "query", "name": "around", "required": false, "schema": { "type": "string" } }, { "description": "Next older pending batch after this transaction id", "in": "query", "name": "olderThan", "required": false, "schema": { "type": "string" } }, { "description": "Next newer pending batch before this transaction id", "in": "query", "name": "newerThan", "required": false, "schema": { "type": "string" } } ] } }, "/categorization/llm-suggest": { "post": { "operationId": "PostLlmSuggest", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmSuggestOverlayDto" } } } } }, "description": "Just-in-time LLM category (and optional payee) overlay for one scored queue transaction.", "summary": "postLlmSuggest", "tags": [ "categorization" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmSuggestRequestDto" } } } } } }, "/categorization/amazon-suggest": { "post": { "operationId": "PostAmazonSuggest", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmazonSplitOverlayDto" } } } } }, "description": "Amazon-only split overlay for one scored Amazon queue transaction.", "summary": "postAmazonSuggest", "tags": [ "categorization" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmazonSuggestRequestDto" } } } } } }, "/categorization/predict": { "post": { "operationId": "PostPredict", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategorizationPredictDto" } } } } }, "description": "Score pending transactions with the local ML models and cache the proposals.", "summary": "postPredict", "tags": [ "categorization" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategorizationPredictRequestDto" } } } } } }, "/categorization/decisions": { "post": { "operationId": "PostClassificationDecisions", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationDecisionsResponseDto" } } } }, "403": { "description": "YNAB writes are disabled in practice mode" }, "404": { "description": "Transaction not found" }, "409": { "description": "Decision cannot replace an in-flight or already-pushed row" } }, "description": "Record live classification decisions. Enqueues YNAB writes; does not call YNAB on this request.", "summary": "postClassificationDecisions", "tags": [ "categorization" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationDecisionsRequestDto" } } } } } }, "/categorization/decisions/{transactionId}": { "delete": { "operationId": "DeleteClassificationDecision", "responses": { "204": { "description": "Retracted" }, "403": { "description": "YNAB writes are disabled in practice mode" }, "409": { "description": "Decision has already been flushed" } }, "description": "Retract a pending or failed live decision.", "summary": "deleteClassificationDecision", "tags": [ "categorization" ], "security": [], "parameters": [ { "in": "path", "name": "transactionId", "required": true, "schema": { "type": "string" } } ] } }, "/categorization/outbound-sync": { "get": { "operationId": "GetOutboundSync", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundSyncStatusDto" } } } } }, "description": "Outbound YNAB sync queue counts.", "summary": "getOutboundSync", "tags": [ "categorization" ], "security": [], "parameters": [] } }, "/categorization/outbound-sync/flush": { "post": { "operationId": "PostOutboundSyncFlush", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundSyncFlushDto" } } } }, "503": { "description": "YNAB credentials missing" } }, "description": "Flush pending classification rows to YNAB now, still respecting rate limits.", "summary": "postOutboundSyncFlush", "tags": [ "categorization" ], "security": [], "parameters": [] } }, "/categorization/ynab-flags": { "get": { "operationId": "GetYnabFlags", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YnabFlagsDto" } } } } }, "description": "Every YNAB flag color with its user-defined name, taken from mirrored transactions.", "summary": "getYnabFlags", "tags": [ "categorization" ], "security": [], "parameters": [] } }, "/categories": { "get": { "operationId": "GetCategories", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoriesDto" } } } } }, "tags": [ "categories" ], "security": [], "parameters": [] } }, "/auth/login": { "post": { "operationId": "PostLogin", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponseDto" } } } } }, "description": "Exchanges a username and password for a long-lived session cookie.", "summary": "postLogin", "tags": [ "auth" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequestDto" } } } } } }, "/auth/logout": { "post": { "operationId": "PostLogout", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResponseDto" } } } } }, "description": "Clears the current session. Safe to call when already signed out.", "summary": "postLogout", "tags": [ "auth" ], "security": [], "parameters": [] } }, "/auth/me": { "get": { "operationId": "GetMe", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthUserDto" } } } } }, "description": "The signed-in user. 401s when there is no valid session — this is how the web app\ndiscovers whether it needs to show the login page.", "summary": "getMe", "tags": [ "auth" ], "security": [], "parameters": [] } }, "/auth/password": { "patch": { "operationId": "PatchPassword", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordResponseDto" } } } } }, "description": "Changes the signed-in user's own password, re-authenticating them with their current one.\n\nEvery other session for the user is revoked, so anyone holding a stolen cookie is booted;\nthe caller's own session survives, because signing someone out of the tab they just used to\nchange their password is a hostile way to confirm success.", "summary": "patchPassword", "tags": [ "auth" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequestDto" } } } } } }, "/amazon-orders/status": { "get": { "operationId": "GetAmazonOrdersStatus", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmazonOrdersStatusDto" } } } } }, "description": "Auth and durable cache status. Does not start Playwright.", "summary": "getAmazonOrdersStatus", "tags": [ "amazon-orders" ], "security": [], "parameters": [] } }, "/amazon-orders/sync": { "post": { "operationId": "PostAmazonOrdersSync", "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmazonOrdersSyncDto" } } } } }, "description": "Index Amazon payments from the oldest uncategorized Amazon charge through today,\r\nthen fetch invoices for order IDs in the requested classify window. Uses amazon-sync when\r\nAMAZON_SYNC_URL is set, else starts the MCP subprocess if needed.", "summary": "postAmazonOrdersSync", "tags": [ "amazon-orders" ], "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmazonOrdersSyncRequestDto" } } } } } } }, "servers": [ { "url": "/" } ] }