{ "openapi": "3.1.0", "components": { "examples": {}, "headers": {}, "parameters": {}, "requestBodies": {}, "responses": {}, "schemas": { "Transaction": { "description": "Transaction object from Google Sheets", "properties": { "transactionId": { "type": "string", "description": "Stable transaction identifier from Direct Fill (only present if the Transaction Id column exists)" }, "date": { "type": "string", "description": "Transaction date (ISO 8601 format)" }, "description": { "type": "string", "description": "Transaction description" }, "amount": { "type": "number", "format": "double", "description": "Transaction amount (negative for expenses, positive for income)" }, "category": { "type": "string", "description": "Transaction category" }, "account": { "type": "string", "description": "Account name" }, "institution": { "type": "string", "description": "Financial institution name" }, "tags": { "type": "string", "description": "User-defined tags (only present if the Tags column exists in the sheet)" }, "note": { "type": "string", "description": "User-defined note (only present if the Note column exists in the sheet)" }, "categoryType": { "type": "string", "description": "Category type resolved by joining `category` against the Categories sheet (Income/Expense/\nTransfer, or the Uncategorized/Unknown buckets, or a custom Type value). Internal, dot-free\ncounterpart of the external `category.type` field. Set only when the query triggers the join." }, "categoryGroup": { "type": "string", "description": "Category group resolved from the Categories sheet — internal counterpart of `category.group`.\nSet only when the query triggers the join." }, "categoryHideFromReports": { "type": "boolean", "description": "Whether the resolved category is marked Hide From Reports. Used by the aggregation hide-policy;\nnot returned as a field. A boolean only when the join matched a Categories row (so the flag is\nknown); undefined for the Uncategorized/Unknown buckets, where there's no row to read it from —\nundefined means \"unknown\", not \"not hidden\", and the exclusion keeps such rows." } }, "required": [ "date", "description", "amount", "category", "account", "institution" ], "type": "object", "additionalProperties": false }, "AggregationResult": { "description": "Aggregation result for grouped transactions", "properties": { "group": { "type": "string", "description": "The group key (e.g., category name, month, etc.)" }, "sum": { "type": "number", "format": "double", "description": "Sum of transaction amounts in this group" }, "avg": { "type": "number", "format": "double", "description": "Average transaction amount in this group" }, "count": { "type": "number", "format": "double", "description": "Count of transactions in this group" }, "min": { "type": "number", "format": "double", "description": "Minimum transaction amount in this group" }, "max": { "type": "number", "format": "double", "description": "Maximum transaction amount in this group" } }, "required": [ "group" ], "type": "object", "additionalProperties": false }, "LoadStep": { "description": "First step: the base table, origin of the row chain. Row conservation differs by step\nkind and the funnel closes by adjacency (`step[i].rowsOut === step[i+1].rowsIn`, the\nchain entering at `load.rowsOut`): load originates; filter/search/hideFromReports/\npaginate remove; a left join and compare preserve (rows kept/annotated/tagged);\naggregate collapses to a group count (terminal).", "properties": { "kind": { "type": "string", "enum": [ "load" ], "nullable": false }, "sheet": { "type": "string" }, "rowsAvailable": { "type": "number", "format": "double" }, "rowsOut": { "type": "number", "format": "double", "description": "Rows loaded (== rowsAvailable unless some were unparseable); feeds the next step's rowsIn." } }, "required": [ "kind", "sheet", "rowsAvailable", "rowsOut" ], "type": "object", "additionalProperties": false }, "FilterClause": { "allOf": [ { "properties": { "$not": { "$ref": "#/components/schemas/FilterClause" }, "$nor": { "items": { "$ref": "#/components/schemas/FilterClause" }, "type": "array" }, "$or": { "items": { "$ref": "#/components/schemas/FilterClause" }, "type": "array" }, "$and": { "items": { "$ref": "#/components/schemas/FilterClause" }, "type": "array" } }, "type": "object" }, { "properties": { "transactionId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "date": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "amount": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "account": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "institution": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "tags": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "categoryType": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "categoryGroup": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "categoryHideFromReports": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] } }, "type": "object" }, { "properties": { "category.type": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] }, "category.group": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" }, { "properties": { "$exists": { "type": "boolean" }, "$options": { "type": "string" }, "$regex": { "type": "string" }, "$nin": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$in": { "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "type": "array" }, "$lte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$lt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gte": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$gt": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$ne": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] }, "$eq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "double" }, { "type": "boolean" } ] } }, "type": "object" } ] } }, "type": "object" } ], "description": "MongoDB-style filter, validated against the operators/fields actually supported by the\nquery engine. `.strict()` rejects unknown keys — e.g. a stray top-level `aggregate`, or\n`month`/`year` (which are aggregation-only, not filterable) — instead of letting sift\ntreat them as never-matching field lookups." }, "FilterStep": { "properties": { "source": { "type": "string", "enum": [ "explicit", "default" ], "description": "`explicit` = caller asked; `default` = a resolved default supplied it (the \"did you realize?\" signal)." }, "rowsIn": { "type": "number", "format": "double" }, "rowsOut": { "type": "number", "format": "double", "description": "`rowsIn - rowsOut` = rows this step removed (0 for a left join / compare tag)." }, "kind": { "type": "string", "enum": [ "filter" ], "nullable": false }, "filter": { "$ref": "#/components/schemas/FilterClause" } }, "required": [ "source", "rowsIn", "rowsOut", "kind", "filter" ], "type": "object", "additionalProperties": false }, "SearchStep": { "properties": { "source": { "type": "string", "enum": [ "explicit", "default" ], "description": "`explicit` = caller asked; `default` = a resolved default supplied it (the \"did you realize?\" signal)." }, "rowsIn": { "type": "number", "format": "double" }, "rowsOut": { "type": "number", "format": "double", "description": "`rowsIn - rowsOut` = rows this step removed (0 for a left join / compare tag)." }, "kind": { "type": "string", "enum": [ "search" ], "nullable": false }, "search": { "type": "string" } }, "required": [ "source", "rowsIn", "rowsOut", "kind", "search" ], "type": "object", "additionalProperties": false }, "ResolutionThresholds": { "description": "Per-state share thresholds (0..1, not percentages). `infoAt` -> footnote (\"Note:\");\n`materialAt` -> caveat (\"Materially incomplete:\") and the contextual fail upgrade above it\nwhen the join is load-bearing; `failAt` -> absolute fail regardless of load-bearing. Shape\nis uniform across states; the per-state values differ (blank keys tolerate more than defects).", "properties": { "infoAt": { "type": "number", "format": "double" }, "materialAt": { "type": "number", "format": "double" }, "failAt": { "type": "number", "format": "double" } }, "required": [ "infoAt", "materialAt", "failAt" ], "type": "object", "additionalProperties": false }, "JoinPolicy": { "properties": { "weightField": { "type": "string", "description": "Base field summed (abs, 2dp) for dollar-weighted shares, e.g. \"amount\". Omitted = count-only." }, "blankKey": { "$ref": "#/components/schemas/ResolutionThresholds" }, "unmatchedKey": { "$ref": "#/components/schemas/ResolutionThresholds" }, "nullProjection": { "$ref": "#/components/schemas/ResolutionThresholds" } }, "required": [ "blankKey", "unmatchedKey", "nullProjection" ], "type": "object", "additionalProperties": false }, "NullProjection": { "properties": { "field": { "type": "string" }, "count": { "type": "number", "format": "double" }, "keys": { "items": { "type": "string" }, "type": "array", "description": "Distinct lookup keys whose projected field is null — the fix list (e.g. category names)." } }, "required": [ "field", "count", "keys" ], "type": "object", "additionalProperties": false }, "JoinResolution": { "description": "Counts + offending VALUES only — owner/remedy/share live in findings. matched + blankKey + unmatchedKey === rowsIn.", "properties": { "matched": { "type": "number", "format": "double" }, "blankKey": { "type": "number", "format": "double", "description": "Base join-key cell empty." }, "unmatchedKey": { "type": "number", "format": "double", "description": "Key present, no matching lookup row." }, "unmatchedValues": { "items": { "type": "string" }, "type": "array", "description": "Distinct unmatched key values (the add/rename list). Empty unless unmatchedKey > 0." }, "nullProjections": { "items": { "$ref": "#/components/schemas/NullProjection" }, "type": "array", "description": "Per projected field: matched a lookup row but the projected cell is null." } }, "required": [ "matched", "blankKey", "unmatchedKey", "unmatchedValues", "nullProjections" ], "type": "object", "additionalProperties": false }, "JoinStep": { "description": "An enrichment join. `resolution` is captured here, against `rowsIn` — the set scoped by\nevery earlier (base) step — so a later projected-field filter cannot retroactively shrink\nthese counts. Step order replaces any separate \"scope integrity by non-enrichment\npredicates\" rule.", "properties": { "source": { "type": "string", "enum": [ "explicit", "default" ], "description": "`explicit` = caller asked; `default` = a resolved default supplied it (the \"did you realize?\" signal)." }, "rowsIn": { "type": "number", "format": "double" }, "rowsOut": { "type": "number", "format": "double", "description": "`rowsIn - rowsOut` = rows this step removed (0 for a left join / compare tag)." }, "kind": { "type": "string", "enum": [ "join" ], "nullable": false }, "sheet": { "type": "string" }, "joinType": { "type": "string", "enum": [ "left", "inner" ], "description": "\"left\" keeps unmatched (rowsOut === rowsIn); \"inner\" drops them (rowsOut === resolution.matched)." }, "joinOn": { "properties": { "lookupField": { "type": "string" }, "baseField": { "type": "string" } }, "required": [ "lookupField", "baseField" ], "type": "object" }, "lookupRowsAvailable": { "type": "number", "format": "double" }, "policy": { "$ref": "#/components/schemas/JoinPolicy", "description": "Requiredness policy + thresholds. Emitted so the warn-vs-fail verdict is reproducible by the caller." }, "resolution": { "$ref": "#/components/schemas/JoinResolution", "description": "Query-time resolution facts" } }, "required": [ "source", "rowsIn", "rowsOut", "kind", "sheet", "joinType", "joinOn", "lookupRowsAvailable", "policy", "resolution" ], "type": "object", "additionalProperties": false }, "HideFromReportsStep": { "properties": { "source": { "type": "string", "enum": [ "explicit", "default" ], "description": "`explicit` = caller asked; `default` = a resolved default supplied it (the \"did you realize?\" signal)." }, "rowsIn": { "type": "number", "format": "double" }, "rowsOut": { "type": "number", "format": "double", "description": "`rowsIn - rowsOut` = rows this step removed (0 for a left join / compare tag)." }, "kind": { "type": "string", "enum": [ "hideFromReports" ], "nullable": false }, "excludeCategoriesHiddenFromReports": { "type": "boolean", "enum": [ true ], "nullable": false, "description": "Always true when present: rows in hide-from-reports categories were excluded." } }, "required": [ "source", "rowsIn", "rowsOut", "kind", "excludeCategoriesHiddenFromReports" ], "type": "object", "additionalProperties": false }, "PaginateStep": { "properties": { "source": { "type": "string", "enum": [ "explicit", "default" ], "description": "`explicit` = caller asked; `default` = a resolved default supplied it (the \"did you realize?\" signal)." }, "rowsIn": { "type": "number", "format": "double" }, "rowsOut": { "type": "number", "format": "double", "description": "`rowsIn - rowsOut` = rows this step removed (0 for a left join / compare tag)." }, "kind": { "type": "string", "enum": [ "paginate" ], "nullable": false }, "limit": { "type": [ "number", "null" ], "format": "double", "description": "Caller's `limit`, or the default cap on an uncapped raw query." }, "offset": { "type": "number", "format": "double" } }, "required": [ "source", "rowsIn", "rowsOut", "kind", "limit", "offset" ], "type": "object", "additionalProperties": false }, "Required_AggregateConfig_": { "properties": { "groupBy": { "type": "string", "enum": [ "category", "account", "category.type", "category.group", "month", "year" ], "description": "Field to group results by. \"category.type\" and \"category.group\" are derived dimensions\nresolved from the Categories sheet.", "example": "category" }, "functions": { "items": { "type": "string", "enum": [ "sum", "avg", "count", "min", "max" ] }, "type": "array", "description": "Aggregation functions to apply", "example": [ "sum", "avg", "count" ] } }, "required": [ "groupBy", "functions" ], "type": "object", "description": "Make all properties in T required" }, "AggregateStep": { "properties": { "source": { "type": "string", "enum": [ "explicit", "default" ], "description": "`explicit` = caller asked; `default` = a resolved default supplied it (the \"did you realize?\" signal)." }, "rowsIn": { "type": "number", "format": "double" }, "rowsOut": { "type": "number", "format": "double", "description": "`rowsIn - rowsOut` = rows this step removed (0 for a left join / compare tag)." }, "kind": { "type": "string", "enum": [ "aggregate" ], "nullable": false }, "aggregate": { "$ref": "#/components/schemas/Required_AggregateConfig_", "description": "Terminal reduce. rowsIn = pre-aggregation count; rowsOut = distinct group-key count." } }, "required": [ "source", "rowsIn", "rowsOut", "kind", "aggregate" ], "type": "object", "additionalProperties": false }, "PipelineStep": { "anyOf": [ { "$ref": "#/components/schemas/LoadStep" }, { "$ref": "#/components/schemas/FilterStep" }, { "$ref": "#/components/schemas/SearchStep" }, { "$ref": "#/components/schemas/JoinStep" }, { "$ref": "#/components/schemas/HideFromReportsStep" }, { "$ref": "#/components/schemas/PaginateStep" }, { "$ref": "#/components/schemas/AggregateStep" } ] }, "FindingCode": { "type": "string", "enum": [ "UNRESOLVED_BASE_KEYS", "UNMATCHED_LOOKUP_KEYS", "NULL_PROJECTION", "RESULT_TRUNCATED", "DEFAULT_APPLIED", "HIDE_FROM_REPORTS_SKIPPED" ] }, "Finding": { "properties": { "code": { "$ref": "#/components/schemas/FindingCode" }, "severity": { "type": "string", "enum": [ "info", "warn" ], "description": "info = below material (footnote); warn = material. A material + load-bearing state never appears — it upgrades to fail (no audit)." }, "state": { "type": "string", "enum": [ "blankKey", "unmatchedKey", "nullProjection" ], "description": "Which resolution state, when this finding came from a join." }, "owner": { "type": "string", "enum": [ "baseRow", "lookupSheet" ], "description": "Who fixes it. Deterministic from `state`; emitted so the consumer needn't know the mapping." }, "remedy": { "type": "string", "enum": [ "assignKey", "addLookupRow", "fillLookupField" ], "description": "assignKey = user tags the base row; addLookupRow = add/rename in lookup sheet; fillLookupField = fill the null cell." }, "field": { "type": "string", "description": "Projected field, for state === \"nullProjection\"." }, "relatedStepIndex": { "type": "number", "format": "double", "description": "Index into `pipeline` of the causing step; its resolution/unmatchedValues hold the offending values." }, "metric": { "properties": { "dollarShare": { "type": "number", "format": "double", "description": "weighted share, 3dp, present when the join's policy.weightField is set — surfaced separately so a low-count/high-dollar finding can lead with dollar impact." }, "countShare": { "type": "number", "format": "double", "description": "count / ofCount, 3dp." }, "ofCount": { "type": "number", "format": "double" }, "count": { "type": "number", "format": "double" } }, "required": [ "countShare", "ofCount", "count" ], "type": "object", "description": "Quantified basis. `ofCount` is the honestly-scoped denominator (the related step's rowsIn)." }, "message": { "type": "string", "description": "Plain, user-presentable sentence generated from the fields above. Copy principles locked by\ncomprehension testing: defect states (unmatched/nullProjection) require an explicit contrast\nclause + affirmative exoneration of the unaffected rows; the user-action state (blankKey) does\nnot; severity prefix \"Note:\" (info) vs \"Materially incomplete:\" (warn); dollar-driven cases\nlead with dollar volume." } }, "required": [ "code", "severity", "message" ], "type": "object", "additionalProperties": false }, "QueryAudit": { "description": "Attached to a successful query response so the caller can verify the result matches its intent\nby reading the plan that produced it. `fail` emits NO audit (corrective prose instead), so\n`verdict` here is only \"ok\" | \"warn\". Lossless, typed structured data — renderable directly by a\nfuture UI; `findings[].message` is the one human-readable affordance.", "properties": { "pipeline": { "items": { "$ref": "#/components/schemas/PipelineStep" }, "type": "array", "description": "The executed plan: load -> (base filter/search) -> join -> (projected filter) -> hideFromReports -> paginate -> aggregate. Array order = execution order." }, "ordering": { "type": "string", "enum": [ "sheetOrder", "groupAscending" ], "description": "\"sheetOrder\" — raw rows in sheet order (a limited page is the first N sheet rows, not newest/oldest); \"groupAscending\" — aggregation groups by key ascending." }, "returnedCoverage": { "properties": { "latestDate": { "type": "string" }, "earliestDate": { "type": "string" } }, "required": [ "latestDate", "earliestDate" ], "type": [ "object", "null" ], "description": "Date bounds of the RETURNED rows only (not the full matched set). Null when none returned — so on a truncated page it is narrower than the matched set." }, "truncated": { "type": "boolean", "description": "More rows matched than were returned (a limit — caller's or default — cut off the tail). Derivable from the paginate step; kept as a convenience signal." }, "verdict": { "type": "string", "enum": [ "ok", "warn" ], "description": "Bubbled decision. Reproducible from `findings` + each join step's policy thresholds." }, "findings": { "items": { "$ref": "#/components/schemas/Finding" }, "type": "array", "description": "Flat decision layer; references the pipeline by `relatedStepIndex`." } }, "required": [ "pipeline", "ordering", "returnedCoverage", "truncated", "verdict", "findings" ], "type": "object", "additionalProperties": false }, "TransactionQueryResponse": { "description": "Response for successful transaction query", "properties": { "transactions": { "items": { "$ref": "#/components/schemas/Transaction" }, "type": "array", "description": "List of transactions matching the query filters (if no aggregation)" }, "aggregations": { "items": { "$ref": "#/components/schemas/AggregationResult" }, "type": "array", "description": "Aggregation results (if aggregation was requested)" }, "count": { "type": "number", "format": "double", "description": "Total number of items returned (transactions or aggregation groups)" }, "audit": { "$ref": "#/components/schemas/QueryAudit", "description": "Audit metadata describing what source data was used and what criteria were actually\napplied, so the result can be verified against intent" } }, "required": [ "count" ], "type": "object", "additionalProperties": false }, "AccountMetadata": { "description": "Account metadata for AI tools", "properties": { "account": { "type": "string", "description": "Display name for the account (user-friendly name or institution-provided name)" }, "accountId": { "type": "string", "description": "External account identifier from the financial data aggregator" }, "institution": { "type": "string", "description": "Financial institution name (e.g., \"Chase\", \"Charles Schwab\", \"Capital One\")" }, "type": { "type": "string", "description": "Account type (e.g., \"checking\", \"savings\", \"credit card\", \"401k\", \"ira\", \"cd\", \"money market\", \"hsa\", \"student\")" }, "class": { "type": "string", "description": "Account class - \"Asset\" or \"Liability\"" }, "status": { "type": "string", "description": "Account status" } }, "required": [ "account", "accountId", "institution", "type", "class", "status" ], "type": "object", "additionalProperties": false }, "SpreadsheetMetadata": { "description": "Extended spreadsheet metadata for AI tools", "properties": { "spreadsheet_id": { "type": "string", "description": "Google Sheets or Excel spreadsheet ID - use this ID when calling other API endpoints" }, "spreadsheetType": { "type": [ "string", "null" ], "enum": [ "gsuite", "office", "feedbot", null ], "description": "Type of spreadsheet" }, "spreadsheetTitle": { "type": "string", "description": "Spreadsheet title/name" }, "alternateLink": { "type": "string", "description": "URL to access the spreadsheet" }, "mostRecentFill": { "type": "string", "description": "Date of most recent data fill (ISO 8601)" }, "accountCount": { "type": "number", "format": "double", "description": "Number of accounts connected to this spreadsheet" }, "backendAutoFill": { "type": "boolean", "description": "Whether backend auto-fill is enabled" }, "accounts": { "items": { "$ref": "#/components/schemas/AccountMetadata" }, "type": "array", "description": "List of financial accounts linked to this spreadsheet. Only ACTIVE accounts are included." } }, "required": [ "spreadsheet_id", "spreadsheetType", "accountCount", "accounts" ], "type": "object", "additionalProperties": false }, "SpreadsheetListResponse": { "description": "Response for spreadsheet list query", "properties": { "spreadsheets": { "items": { "$ref": "#/components/schemas/SpreadsheetMetadata" }, "type": "array", "description": "List of user's spreadsheets with metadata" }, "count": { "type": "number", "format": "double", "description": "Total number of spreadsheets" } }, "required": [ "spreadsheets", "count" ], "type": "object", "additionalProperties": false }, "Record_string.number_": { "properties": {}, "additionalProperties": { "type": "number", "format": "double" }, "type": "object", "description": "Construct a type with a set of properties K of type T" }, "CategoryMetadata": { "description": "Category metadata", "properties": { "category": { "type": "string", "description": "Category name - use this when filtering or categorizing transactions" }, "group": { "type": "string", "description": "Category group (optional)" }, "type": { "type": "string", "description": "Category type (optional)" }, "hideFromReports": { "type": "boolean", "description": "Whether this category is hidden from reports (optional)" }, "budgets": { "$ref": "#/components/schemas/Record_string.number_", "description": "Monthly budget amounts keyed by month column header (e.g. \"Jan 2022\", \"Feb 2022\"). Only present if the sheet has budget columns." } }, "required": [ "category" ], "type": "object", "additionalProperties": false }, "CategoryListResponse": { "description": "Response for category list query", "properties": { "categories": { "items": { "$ref": "#/components/schemas/CategoryMetadata" }, "type": "array", "description": "List of available categories" }, "count": { "type": "number", "format": "double", "description": "Total number of categories" } }, "required": [ "categories", "count" ], "type": "object", "additionalProperties": false } }, "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.tillermoney.com/authorize", "tokenUrl": "https://auth.tillermoney.com/oauth/token", "scopes": { "openid": "OpenID Connect authentication", "profile": "Access user profile information", "email": "Access user email address", "offline_access": "Maintain access when user is not present (refresh token)" } } } } } }, "info": { "title": "Tiller AI Tools API", "version": "1.0.0", "contact": {}, "description": "AI-callable tool endpoints for querying and analyzing financial transactions. These endpoints require OAuth2 authentication and an active Tiller subscription." }, "paths": { "/ai/spreadsheet/{spreadsheetId}/transactions/query": { "get": { "operationId": "QueryTransactions", "responses": { "200": { "description": "List of transactions or aggregation results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionQueryResponse" } } } } }, "description": "Query transactions with filters, full-text search, and aggregations. Returns: date, description, amount, category, account, institution, tags, note. Supports complex queries (AND/OR/NOT), comparison operators, fuzzy search, and grouping with sum/avg/count/min/max.", "tags": [ "AI Tools" ], "security": [ { "oauth2": [ "openid", "profile", "email", "offline_access" ] } ], "parameters": [ { "description": "The ID of the spreadsheet to query", "in": "path", "name": "spreadsheetId", "required": true, "schema": { "type": "string" } }, { "description": "JSON-encoded query object with optional filter, search, aggregate, limit, and offset fields", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } } ] } }, "/ai/spreadsheets": { "get": { "operationId": "GetSpreadsheets", "responses": { "200": { "description": "List of spreadsheets with metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpreadsheetListResponse" } } } } }, "description": "Get list of user's spreadsheets with extended metadata including account count and most recent fill date.", "tags": [ "AI Tools" ], "security": [ { "oauth2": [ "openid", "profile", "email", "offline_access" ] } ], "parameters": [] } }, "/ai/spreadsheet/{spreadsheetId}/categories": { "get": { "operationId": "GetCategories", "responses": { "200": { "description": "List of categories with metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryListResponse" } } } } }, "description": "Get list of available categories from the user's Categories sheet.\nUse these category names when filtering transactions or generating category updates.", "tags": [ "AI Tools" ], "security": [ { "oauth2": [ "openid", "profile", "email", "offline_access" ] } ], "parameters": [ { "description": "The ID of the spreadsheet to get categories from", "in": "path", "name": "spreadsheetId", "required": true, "schema": { "type": "string" } } ] } } }, "servers": [ { "url": "https://ai-tools.tillermoney.com", "description": "AI Tools API Server" } ], "tags": [ { "name": "AI Tools", "description": "AI-callable tool endpoints for transaction queries and analysis" } ], "security": [ { "oauth2": [ "openid", "profile", "email", "offline_access" ] } ] }