{"openapi":"3.1.0","info":{"title":"Truenote REST API","version":"0.0.0","description":"Read your Truenote data with a bearer token: an OAuth access token or a personal access token. Every request is checked against the token's scopes and exclusions and written to your audit log. Amounts are integer cents; a transaction's amountCents is positive for money in."},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An OAuth access token (MCP clients; resource /v1) or a personal access token (tn_pat_…) from Connected agents."}},"schemas":{"AgentOverview":{"type":"object","properties":{"today":{"type":"string"},"netWorth":{"anyOf":[{"$ref":"#/components/schemas/NetWorth"},{"type":"null"}]},"month":{"type":["object","null"],"properties":{"start":{"type":"string"},"end":{"type":"string"},"incomeCents":{"type":"integer"},"spentCents":{"type":"integer"},"byEntity":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"household":{"type":"boolean"},"spentCents":{"type":"integer"},"incomeCents":{"type":"integer"}},"required":["name","household","spentCents","incomeCents"]}}},"required":["start","end","incomeCents","spentCents","byEntity"]},"plan":{"type":["object","null"],"properties":{"incomeMonthlyCents":{"type":"integer"},"plannedCents":{"type":"integer"},"unplannedCents":{"type":"integer"},"groups":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"targetCents":{"type":"integer"},"plannedCents":{"type":"integer"},"leftoverCents":{"type":"integer"}},"required":["name","targetCents","plannedCents","leftoverCents"]}}},"required":["incomeMonthlyCents","plannedCents","unplannedCents","groups"]},"planVsActual":{"type":["object","null"],"properties":{"bills":{"type":"object","properties":{"expectedCents":{"type":"integer"},"paidCents":{"type":"integer"},"paid":{"type":"integer"},"count":{"type":"integer"}},"required":["expectedCents","paidCents","paid","count"]},"setAside":{"type":"object","properties":{"plannedCents":{"type":"integer"},"actualCents":{"type":"integer"}},"required":["plannedCents","actualCents"]},"everyday":{"type":"object","properties":{"plannedCents":{"type":"integer"},"actualCents":{"type":"integer"},"status":{"type":"string","enum":["on_track","ahead_of_pace","over"]}},"required":["plannedCents","actualCents","status"]},"chargedToBucketsCents":{"type":"integer"},"leftCents":{"type":"integer"}},"required":["bills","setAside","everyday","chargedToBucketsCents","leftCents"]},"upcomingBills":{"type":["array","null"],"items":{"type":"object","properties":{"description":{"type":"string"},"dueOn":{"type":"string"},"expectedCents":{"type":"integer"},"account":{"type":"string"}},"required":["description","dueOn","expectedCents","account"]}},"goals":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["emergency_fund","savings","debt_payoff","purchase","tax_reserve","other"]},"targetCents":{"type":"integer"},"currentCents":{"type":"integer"},"progressBps":{"type":"integer"}},"required":["id","name","kind","targetCents","currentCents","progressBps"]}},"taxes":{"type":["object","null"],"properties":{"taxYear":{"type":"integer"},"nextDue":{"type":"object","properties":{"quarter":{"type":"integer"},"due":{"type":"string"},"suggestedCents":{"type":"integer"}},"required":["quarter","due","suggestedCents"]},"yearReceivedCents":{"type":"integer"},"yearSetAsideCents":{"type":"integer"},"yearPaidCents":{"type":"integer"}},"required":["taxYear","nextDue","yearReceivedCents","yearSetAsideCents","yearPaidCents"]},"attention":{"type":["array","null"],"items":{"type":"object","properties":{"institution":{"type":"string"},"status":{"type":"string","enum":["healthy","login_required","pending_expiration","revoked","error"]}},"required":["institution","status"]}},"checklist":{"type":["object","null"],"properties":{"open":{"type":"integer"},"next":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"dueOn":{"type":["string","null"]},"state":{"type":"string","enum":["overdue","due_soon","upcoming","someday","done"]}},"required":["id","title","dueOn","state"]}}},"required":["open","next"]},"balanceSheet":{"type":["object","null"],"properties":{"own":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["property","retirement","investments","cash","other"]},"valueCents":{"type":"integer"}},"required":["kind","valueCents"]}},"owe":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["mortgage","loans","cards"]},"valueCents":{"type":"integer"}},"required":["kind","valueCents"]}},"homeEquityCents":{"type":["integer","null"]}},"required":["own","owe","homeEquityCents"]},"saving":{"type":["object","null"],"properties":{"months":{"type":"integer"},"incomeCents":{"type":"integer"},"keptCents":{"type":"integer"},"rateBps":{"type":["integer","null"]}},"required":["months","incomeCents","keptCents","rateBps"]},"emergencyFund":{"type":["object","null"],"properties":{"name":{"type":"string"},"currentCents":{"type":"integer"},"months":{"type":["number","null"]},"targetMonths":{"type":["number","null"]}},"required":["name","currentCents","months","targetMonths"]},"spotlight":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["task","event"]},"title":{"type":"string"},"dueOn":{"type":"string"},"sumCents":{"type":["integer","null"]}},"required":["id","kind","title","dueOn","sumCents"]},"setup":{"anyOf":[{"$ref":"#/components/schemas/SetupChecklist"},{"type":"null"}]},"notIncluded":{"type":"array","items":{"type":"string"}}},"required":["today","netWorth","month","plan","planVsActual","upcomingBills","goals","taxes","attention","checklist","balanceSheet","saving","emergencyFund","spotlight","setup","notIncluded"]},"NetWorth":{"type":"object","properties":{"cashCents":{"type":"integer"},"investmentsCents":{"type":"integer"},"otherAssetsCents":{"type":"integer"},"creditCents":{"type":"integer"},"loansCents":{"type":"integer"},"otherLiabilitiesCents":{"type":"integer"},"assetsCents":{"type":"integer"},"liabilitiesCents":{"type":"integer"},"netWorthCents":{"type":"integer"}},"required":["cashCents","investmentsCents","otherAssetsCents","creditCents","loansCents","otherLiabilitiesCents","assetsCents","liabilitiesCents","netWorthCents"]},"SetupChecklist":{"type":"object","properties":{"done":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SetupItem"}},"next":{"type":["string","null"],"enum":["bank","household","income","plan","goal","buckets",null]},"guidance":{"type":"array","items":{"type":"string"}}},"required":["done","items","next","guidance"],"description":"The setup checklist"},"SetupItem":{"type":"object","properties":{"key":{"type":"string","enum":["bank","household","income","plan","goal","buckets"]},"label":{"type":"string"},"done":{"type":"boolean"},"note":{"type":["string","null"]},"ask":{"type":"string"},"tools":{"type":"array","items":{"type":"string"}}},"required":["key","label","done","note","ask","tools"]},"ErrorBody":{"type":"object","properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string","example":"We couldn't find that."},"field":{"type":"string","example":"state"}},"required":["error","message"],"description":"Error response"},"AgentAccountList":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/AgentAccount"}},"manualAccounts":{"type":"array","items":{"$ref":"#/components/schemas/AgentManualAccount"}},"totals":{"$ref":"#/components/schemas/NetWorth"}},"required":["accounts","manualAccounts","totals"]},"AgentAccount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"institution":{"type":["string","null"]},"type":{"type":"string","enum":["depository","credit","loan","investment","other"]},"subtype":{"type":["string","null"]},"mask":{"type":["string","null"]},"entity":{"type":["string","null"]},"entityId":{"type":["string","null"],"format":"uuid"},"balanceCents":{"type":["integer","null"]},"availableCents":{"type":["integer","null"]},"limitCents":{"type":["integer","null"]},"currency":{"type":"string"},"balancesAsOf":{"type":["string","null"]},"hidden":{"type":"boolean"},"closed":{"type":"boolean"},"connection":{"type":"string","enum":["healthy","login_required","pending_expiration","revoked","error"]},"liability":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["credit","mortgage","student","other"]},"aprBps":{"type":["integer","null"]},"minimumPaymentCents":{"type":["integer","null"]},"nextPaymentDueDate":{"type":["string","null"]}},"required":["kind","aprBps","minimumPaymentCents","nextPaymentDueDate"]},"latestDocument":{"$ref":"#/components/schemas/AgentDocumentRef"}},"required":["id","name","institution","type","subtype","mask","entity","entityId","balanceCents","availableCents","limitCents","currency","balancesAsOf","hidden","closed","connection","liability"]},"AgentDocumentRef":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["paystub","w2","form_1099","form_1098","tax_return","benefits","statement","receipt","other"]},"taxYear":{"type":["integer","null"]},"documentOn":{"type":["string","null"]}},"required":["id","name","kind","taxYear","documentOn"]},"AgentManualAccount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["asset","liability"]},"type":{"type":"string"},"entity":{"type":["string","null"]},"balanceCents":{"type":["integer","null"]},"asOf":{"type":["string","null"]},"latestDocument":{"$ref":"#/components/schemas/AgentDocumentRef"}},"required":["id","name","kind","type","entity","balanceCents","asOf"]},"AgentTransactionPage":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/AgentTransaction"}},"nextCursor":{"type":["string","null"]},"totals":{"type":"object","properties":{"count":{"type":"integer"},"spendingCents":{"type":"integer"},"incomeCents":{"type":"integer"}},"required":["count","spendingCents","incomeCents"]}},"required":["transactions","nextCursor","totals"]},"AgentTransaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"date":{"type":"string"},"description":{"type":"string"},"merchant":{"type":["string","null"]},"amountCents":{"type":"integer"},"pending":{"type":"boolean"},"account":{"type":"string"},"accountId":{"type":"string","format":"uuid"},"category":{"type":["string","null"]},"categoryId":{"type":["string","null"],"format":"uuid"},"entity":{"type":["string","null"]},"entityId":{"type":["string","null"],"format":"uuid"},"flow":{"type":"string","enum":["spending","income","transfer","excluded"]},"note":{"type":["string","null"]},"splitOf":{"type":["string","null"],"format":"uuid"},"ownerContribution":{"type":"boolean","enum":[true]}},"required":["id","date","description","merchant","amountCents","pending","account","accountId","category","categoryId","entity","entityId","flow","note","splitOf"]},"AgentSpending":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"groupBy":{"type":"string","enum":["category","merchant","entity","month"]},"scope":{"type":"string","enum":["household","all","entity"]},"entityId":{"type":["string","null"],"format":"uuid"},"totalCents":{"type":"integer"},"groups":{"type":"array","items":{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":"string"},"spentCents":{"type":"integer"},"count":{"type":"integer"},"shareBps":{"type":"integer"}},"required":["key","label","spentCents","count","shareBps"]}},"otherCents":{"type":"integer"},"otherGroups":{"type":"integer"}},"required":["from","to","groupBy","scope","entityId","totalCents","groups","otherCents","otherGroups"]},"AgentRecurring":{"type":"object","properties":{"streams":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"flow":{"type":"string","enum":["spending","income","transfer"]},"description":{"type":"string"},"merchant":{"type":["string","null"]},"direction":{"type":"string","enum":["inflow","outflow"]},"frequency":{"type":"string","enum":["weekly","biweekly","semi_monthly","monthly","annually","unknown"]},"status":{"type":"string","enum":["mature","early_detection","tombstoned","unknown"]},"active":{"type":"boolean"},"lastAmountCents":{"type":["integer","null"]},"averageAmountCents":{"type":["integer","null"]},"lastDate":{"type":["string","null"]},"nextDate":{"type":["string","null"]},"account":{"type":"string"},"category":{"type":["string","null"]}},"required":["id","flow","description","merchant","direction","frequency","status","active","lastAmountCents","averageAmountCents","lastDate","nextDate","account","category"]}},"monthlyOutflowCents":{"type":"integer"},"monthlyInflowCents":{"type":"integer"},"monthlyTransfersCents":{"type":"integer"}},"required":["streams","monthlyOutflowCents","monthlyInflowCents","monthlyTransfersCents"]},"AgentNetWorthHistory":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"interval":{"type":"string","enum":["day","week","month"]},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"netWorthCents":{"type":"integer"},"assetsCents":{"type":"integer"},"liabilitiesCents":{"type":"integer"},"byType":{"type":"object","properties":{"cashCents":{"type":"integer"},"investmentsCents":{"type":"integer"},"creditCents":{"type":"integer"},"loansCents":{"type":"integer"},"otherCents":{"type":"integer"},"manualCents":{"type":"integer"}},"required":["cashCents","investmentsCents","creditCents","loansCents","otherCents","manualCents"]}},"required":["date","netWorthCents","assetsCents","liabilitiesCents","byType"]}},"heldBack":{"type":"boolean"}},"required":["from","to","interval","points","heldBack"]},"AgentHoldings":{"type":"object","properties":{"totalValueCents":{"type":"integer"},"accounts":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string","format":"uuid"},"account":{"type":"string"},"valueCents":{"type":"integer"},"holdings":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":["string","null"]},"name":{"type":["string","null"]},"type":{"type":["string","null"]},"quantity":{"type":"string"},"priceCents":{"type":["integer","null"]},"valueCents":{"type":["integer","null"]},"costBasisCents":{"type":["integer","null"]},"gainCents":{"type":["integer","null"]}},"required":["symbol","name","type","quantity","priceCents","valueCents","costBasisCents","gainCents"]}}},"required":["accountId","account","valueCents","holdings"]}},"transactions":{"type":["array","null"],"items":{"type":"object","properties":{"date":{"type":"string"},"account":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"subtype":{"type":["string","null"]},"symbol":{"type":["string","null"]},"quantity":{"type":["string","null"]},"amountCents":{"type":"integer"},"feesCents":{"type":["integer","null"]}},"required":["date","account","description","type","subtype","symbol","quantity","amountCents","feesCents"]}}},"required":["totalValueCents","accounts","transactions"]},"AgentInvestmentTransactionPage":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/AgentInvestmentTransaction"}},"nextCursor":{"type":["string","null"]},"totals":{"type":"object","properties":{"count":{"type":"integer"},"byKind":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"subtype":{"type":["string","null"]},"count":{"type":"integer"},"amountCents":{"type":"integer"}},"required":["type","subtype","count","amountCents"]}}},"required":["count","byKind"]}},"required":["transactions","nextCursor","totals"]},"AgentInvestmentTransaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"date":{"type":"string"},"accountId":{"type":"string","format":"uuid"},"account":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"subtype":{"type":["string","null"]},"symbol":{"type":["string","null"]},"security":{"type":["string","null"]},"quantity":{"type":["string","null"]},"priceCents":{"type":["integer","null"]},"amountCents":{"type":"integer"},"feesCents":{"type":["integer","null"]}},"required":["id","date","accountId","account","description","type","subtype","symbol","security","quantity","priceCents","amountCents","feesCents"]},"AgentLiabilities":{"type":"object","properties":{"totalOwedCents":{"type":"integer"},"liabilities":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string","format":"uuid"},"account":{"type":"string"},"kind":{"type":"string","enum":["credit","mortgage","student","other"]},"owedCents":{"type":["integer","null"]},"aprBps":{"type":["integer","null"]},"minimumPaymentCents":{"type":["integer","null"]},"nextPaymentDueDate":{"type":["string","null"]},"lastPaymentCents":{"type":["integer","null"]},"lastPaymentDate":{"type":["string","null"]},"lastStatementBalanceCents":{"type":["integer","null"]},"overdue":{"type":["boolean","null"]},"originationPrincipalCents":{"type":["integer","null"]},"maturityDate":{"type":["string","null"]}},"required":["accountId","account","kind","owedCents","aprBps","minimumPaymentCents","nextPaymentDueDate","lastPaymentCents","lastPaymentDate","lastStatementBalanceCents","overdue","originationPrincipalCents","maturityDate"]}}},"required":["totalOwedCents","liabilities"]},"AgentContext":{"type":"object","properties":{"profile":{"$ref":"#/components/schemas/Profile"},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["personal","business"]},"isDefault":{"type":"boolean"}},"required":["id","name","kind","isDefault"]}},"incomeSources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["1099","w2","business","other"]},"cadence":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","quarterly","annually","irregular"]},"expectedAmountCents":{"type":["integer","null"]},"taxSetAsideBps":{"type":"integer"},"payerMatch":{"type":["string","null"]},"entity":{"type":["string","null"]},"entityId":{"type":["string","null"],"format":"uuid"},"earner":{"type":["string","null"]},"regular":{"type":"boolean"},"active":{"type":"boolean"},"notes":{"type":"string"}},"required":["id","name","type","cadence","expectedAmountCents","taxSetAsideBps","payerMatch","entity","entityId","earner","regular","active","notes"]}},"goals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["emergency_fund","savings","debt_payoff","purchase","tax_reserve","other"]},"targetAmountCents":{"type":"integer"},"targetDate":{"type":["string","null"]},"priority":{"type":"integer"},"notes":{"type":"string"},"archived":{"type":"boolean"},"links":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":["string","null"],"format":"uuid"},"manualAccountId":{"type":["string","null"],"format":"uuid"},"bucketId":{"type":["string","null"],"format":"uuid"},"name":{"type":"string"},"shareBps":{"type":"integer"}},"required":["accountId","manualAccountId","bucketId","name","shareBps"]}},"progress":{"type":["object","null"],"properties":{"currentCents":{"type":"integer"},"progressBps":{"type":"integer"}},"required":["currentCents","progressBps"]}},"required":["id","name","kind","targetAmountCents","targetDate","priority","notes","archived","links","progress"]}},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["expense","income","transfer"]},"parentId":{"type":["string","null"],"format":"uuid"}},"required":["id","name","kind","parentId"]}},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"priority":{"type":"integer"},"conditions":{"$ref":"#/components/schemas/RuleConditions"},"setCategory":{"type":["string","null"]},"setEntity":{"type":["string","null"]},"setExcluded":{"type":["boolean","null"]},"active":{"type":"boolean"}},"required":["id","name","priority","conditions","setCategory","setEntity","setExcluded","active"]}},"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"occurredOn":{"type":["string","null"]},"body":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean"}},"required":["id","occurredOn","body","tags","pinned"]}},"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"updatedAt":{"type":"string"}},"required":["id","name","summary","status","updatedAt"]}},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/AgentTask"}},"documents":{"type":["object","null"],"properties":{"count":{"type":"integer"},"latest":{"type":"array","items":{"$ref":"#/components/schemas/AgentDocumentRef"}}},"required":["count","latest"]},"setup":{"anyOf":[{"$ref":"#/components/schemas/SetupChecklist"},{"type":"null"}]}},"required":["profile","entities","incomeSources","goals","categories","rules","notes","plans","tasks","setup"]},"Profile":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"householdMembers":{"type":"array","items":{"$ref":"#/components/schemas/HouseholdMember"}},"state":{"$ref":"#/components/schemas/UsStateCode"},"filingStatus":{"$ref":"#/components/schemas/FilingStatus"},"riskTolerance":{"$ref":"#/components/schemas/RiskTolerance"},"about":{"type":"string"},"timeZone":{"type":"string"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["name","email","householdMembers","state","filingStatus","riskTolerance","about","timeZone","updatedAt"],"description":"Your household profile"},"HouseholdMember":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"relationship":{"type":"string","enum":["self","partner","child","dependent","other"]},"birthDate":{"type":["string","null"]},"dueDate":{"type":["string","null"]}},"required":["name","relationship","birthDate","dueDate"]},"UsStateCode":{"type":["string","null"],"enum":["AL","AK","AZ","AR","CA","CO","CT","DE","DC","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY",null]},"FilingStatus":{"type":["string","null"],"enum":["single","married_joint","married_separate","head_of_household","qualifying_surviving_spouse",null]},"RiskTolerance":{"type":["string","null"],"enum":["conservative","moderate","aggressive",null]},"RuleConditions":{"type":"object","properties":{"merchantContains":{"type":"string","minLength":1,"maxLength":100},"nameContains":{"type":"string","minLength":1,"maxLength":100},"accountId":{"type":"string","format":"uuid"},"amountMinCents":{"type":"integer","minimum":0},"amountMaxCents":{"type":"integer","minimum":0},"direction":{"type":"string","enum":["inflow","outflow"]}}},"AgentTask":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["task","event"]},"title":{"type":"string"},"dueOn":{"type":["string","null"]},"state":{"type":"string","enum":["overdue","due_soon","upcoming","someday","done"]},"sumCents":{"type":["integer","null"]},"spotlight":{"type":"boolean"},"doneAt":{"type":["string","null"]},"goal":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"bucket":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"notes":{"type":"string"}},"required":["id","kind","title","dueOn","state","sumCents","spotlight","doneAt","goal","bucket","notes"]},"AgentPlan":{"type":"object","properties":{"today":{"type":"string"},"income":{"type":"object","properties":{"monthlyCents":{"type":"integer"},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"earner":{"type":["string","null"]},"monthlyCents":{"type":"integer"}},"required":["id","name","earner","monthlyCents"]}},"missingAmount":{"type":"array","items":{"type":"string"}}},"required":["monthlyCents","sources","missingAmount"]},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["spending","saving"]},"targetBps":{"type":"integer"},"targetCents":{"type":"integer"},"plannedCents":{"type":"integer"},"leftoverCents":{"type":"integer"},"shareBps":{"type":["integer","null"]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"perPaymentCents":{"type":"integer"},"cadence":{"type":"string","enum":["weekly","biweekly","semimonthly","monthly","quarterly","annually"]},"monthlyCents":{"type":"integer"},"everyTwoWeeksCents":{"type":"integer"},"status":{"type":"string","enum":["active","upcoming","ended"]},"startsOn":{"type":["string","null"]},"endsOn":{"type":["string","null"]},"category":{"type":["string","null"]},"categoryId":{"type":["string","null"],"format":"uuid"},"account":{"type":["string","null"]},"accountId":{"type":["string","null"],"format":"uuid"},"bucket":{"type":["string","null"]},"bucketId":{"type":["string","null"],"format":"uuid"},"kind":{"type":"string","enum":["bill","set_aside","everyday"]},"match":{"type":["string","null"]},"notes":{"type":"string"}},"required":["id","name","perPaymentCents","cadence","monthlyCents","everyTwoWeeksCents","status","startsOn","endsOn","category","categoryId","account","accountId","bucket","bucketId","kind","match","notes"]}}},"required":["id","name","kind","targetBps","targetCents","plannedCents","leftoverCents","shareBps","lines"]}},"plannedCents":{"type":"integer"},"unplannedCents":{"type":"integer"},"targetBps":{"type":"integer"},"transfers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"account":{"type":"string"},"everyTwoWeeksCents":{"type":"integer"}},"required":["name","account","everyTwoWeeksCents"]}},"freesUp":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"endsOn":{"type":"string"},"monthlyCents":{"type":"integer"}},"required":["name","endsOn","monthlyCents"]}}},"required":["today","income","groups","plannedCents","unplannedCents","targetBps","transfers","freesUp"]},"AgentPlanActuals":{"type":"object","properties":{"month":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"today":{"type":"string"},"current":{"type":"boolean"},"monthGoneBps":{"type":"integer"},"averageOf":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},"incomeCents":{"type":"integer"},"plannedIncomeCents":{"type":"integer"},"bills":{"type":"object","properties":{"expectedCents":{"type":"integer"},"paidCents":{"type":"integer"},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"group":{"type":"string"},"expectedCents":{"type":"integer"},"paidCents":{"type":"integer"},"paidOn":{"type":["string","null"]},"status":{"type":"string","enum":["paid","due","unpaid","not_this_month"]}},"required":["id","name","group","expectedCents","paidCents","paidOn","status"]}}},"required":["expectedCents","paidCents","lines"]},"setAside":{"type":"object","properties":{"plannedCents":{"type":"integer"},"actualCents":{"type":"integer"},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"group":{"type":"string"},"plannedCents":{"type":"integer"},"actualCents":{"type":"integer"},"via":{"type":["string","null"],"enum":["bucket","account","text",null]},"status":{"type":"string","enum":["met","in_progress","short","not_tracked"]}},"required":["id","name","group","plannedCents","actualCents","via","status"]}}},"required":["plannedCents","actualCents","lines"]},"everyday":{"type":"object","properties":{"plannedCents":{"type":"integer"},"actualCents":{"type":"integer"},"averageCents":{"type":["integer","null"]},"paceCents":{"type":"integer"},"status":{"type":"string","enum":["on_track","ahead_of_pace","over"]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"group":{"type":"string"},"category":{"type":["string","null"]},"plannedCents":{"type":"integer"}},"required":["id","name","group","category","plannedCents"]}},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"categoryId":{"type":["string","null"],"format":"uuid"},"plannedCents":{"type":"integer"},"actualCents":{"type":"integer"},"averageCents":{"type":["integer","null"]},"transactions":{"type":"integer"}},"required":["category","categoryId","plannedCents","actualCents","averageCents","transactions"]}}},"required":["plannedCents","actualCents","averageCents","paceCents","status","lines","categories"]},"chargedToBucketsCents":{"type":"integer"},"taxPaymentsCents":{"type":"integer"},"leftCents":{"type":"integer"}},"required":["month","today","current","monthGoneBps","averageOf","incomeCents","plannedIncomeCents","bills","setAside","everyday","chargedToBucketsCents","taxPaymentsCents","leftCents"]},"AgentTaxProjection":{"type":"object","properties":{"taxYear":{"type":"integer"},"today":{"type":"string"},"filingStatus":{"type":"string","enum":["single","married_joint","married_separate","head_of_household","qualifying_surviving_spouse"]},"figuresSource":{"type":"string"},"settings":{"$ref":"#/components/schemas/TaxSettings"},"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"earner":{"type":["string","null"]},"grossPayCents":{"type":"integer"},"bonusCents":{"type":"integer"},"retirementCents":{"type":"integer"},"otherPretaxCents":{"type":"integer"},"federalWagesCents":{"type":"integer"},"medicareWagesCents":{"type":"integer"},"socialSecurityWagesCents":{"type":"integer"},"withholdingBasis":{"type":"string","enum":["year_to_date","per_paycheck","none"]},"withheldToDateCents":{"type":"integer"},"withheldAsOf":{"type":["string","null"]},"perPaycheckCents":{"type":["integer","null"]},"paychecksProjected":{"type":"integer"},"paychecksLeft":{"type":"integer"},"restOfYearWithholdingCents":{"type":"integer"},"bonusWithholdingAheadCents":{"type":"integer"},"federalWithholdingCents":{"type":"integer"},"additionalMedicareWithheldCents":{"type":"integer"}},"required":["id","name","earner","grossPayCents","bonusCents","retirementCents","otherPretaxCents","federalWagesCents","medicareWagesCents","socialSecurityWagesCents","withholdingBasis","withheldToDateCents","withheldAsOf","perPaycheckCents","paychecksProjected","paychecksLeft","restOfYearWithholdingCents","bonusWithholdingAheadCents","federalWithholdingCents","additionalMedicareWithheldCents"]}},"businesses":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"entityId":{"type":["string","null"],"format":"uuid"},"earner":{"type":["string","null"]},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"receivedCents":{"type":"integer"},"receivedElsewhereCents":{"type":"integer"},"restOfYearCents":{"type":"integer"}},"required":["id","name","receivedCents","receivedElsewhereCents","restOfYearCents"]}},"receivedCents":{"type":"integer"},"receivedElsewhereCents":{"type":"integer"},"restOfYearCents":{"type":"integer"},"grossReceiptsCents":{"type":"integer"},"expensesCents":{"type":"integer"},"expensesFrom":{"type":"string","enum":["estimate","transactions","none"]},"netProfitCents":{"type":"integer"}},"required":["key","name","entityId","earner","sources","receivedCents","receivedElsewhereCents","restOfYearCents","grossReceiptsCents","expensesCents","expensesFrom","netProfitCents"]}},"wagesCents":{"type":"integer"},"businessIncomeCents":{"type":"integer"},"otherIncomeCents":{"type":"integer"},"capitalGainsCents":{"type":"integer"},"totalIncomeCents":{"type":"integer"},"halfSeTaxCents":{"type":"integer"},"agiCents":{"type":"integer"},"deduction":{"type":"object","properties":{"kind":{"type":"string","enum":["standard","itemized"]},"totalCents":{"type":"integer"},"standardCents":{"type":"integer"}},"required":["kind","totalCents","standardCents"]},"qbi":{"type":"object","properties":{"qualifiedIncomeCents":{"type":"integer"},"thresholdCents":{"type":"integer"},"phaseInRangeCents":{"type":"integer"},"phasedOutBps":{"type":"integer","minimum":0,"maximum":10000},"deductionCents":{"type":"integer"}},"required":["qualifiedIncomeCents","thresholdCents","phaseInRangeCents","phasedOutBps","deductionCents"]},"taxableIncomeCents":{"type":"integer"},"capitalGainsTax":{"type":"object","properties":{"slices":{"type":"array","items":{"type":"object","properties":{"rateBps":{"type":"integer","minimum":0,"maximum":10000},"fromCents":{"type":"integer"},"toCents":{"type":"integer"},"taxCents":{"type":"integer"}},"required":["rateBps","fromCents","toCents","taxCents"]}},"taxCents":{"type":"integer"}},"required":["slices","taxCents"]},"incomeTaxCents":{"type":"integer"},"marginalRateBps":{"type":"integer","minimum":0,"maximum":10000},"childTaxCredit":{"type":"object","properties":{"qualifyingChildren":{"type":"integer"},"childrenFrom":{"type":"string","enum":["profile","settings"]},"beforePhaseOutCents":{"type":"integer"},"phaseOutCents":{"type":"integer"},"nonrefundableCents":{"type":"integer"},"refundableCents":{"type":"integer"}},"required":["qualifyingChildren","childrenFrom","beforePhaseOutCents","phaseOutCents","nonrefundableCents","refundableCents"]},"seTax":{"type":"object","properties":{"byEarner":{"type":"array","items":{"type":"object","properties":{"earner":{"type":["string","null"]},"netProfitCents":{"type":"integer"},"netEarningsCents":{"type":"integer"},"socialSecurityWagesCents":{"type":"integer"},"socialSecurityEarningsCents":{"type":"integer"},"socialSecurityCents":{"type":"integer"},"medicareCents":{"type":"integer"},"totalCents":{"type":"integer"}},"required":["earner","netProfitCents","netEarningsCents","socialSecurityWagesCents","socialSecurityEarningsCents","socialSecurityCents","medicareCents","totalCents"]}},"totalCents":{"type":"integer"}},"required":["byEarner","totalCents"]},"additionalMedicareTaxCents":{"type":"integer"},"netInvestmentIncomeTax":{"type":"object","properties":{"incomeCents":{"type":"integer"},"thresholdCents":{"type":"integer"},"taxCents":{"type":"integer"}},"required":["incomeCents","thresholdCents","taxCents"]},"totalTaxCents":{"type":"integer"},"payments":{"type":"object","properties":{"federalWithholdingCents":{"type":"integer"},"additionalMedicareWithheldCents":{"type":"integer"},"estimatedPaymentsCents":{"type":"integer"},"otherPaymentsCents":{"type":"integer"},"excessSocialSecurityCents":{"type":"integer"},"refundableCreditsCents":{"type":"integer"},"totalCents":{"type":"integer"}},"required":["federalWithholdingCents","additionalMedicareWithheldCents","estimatedPaymentsCents","otherPaymentsCents","excessSocialSecurityCents","refundableCreditsCents","totalCents"]},"estimatedPayments":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"paidCents":{"type":"integer"},"quarter":{"type":"integer"},"countedCents":{"type":"integer"}},"required":["date","paidCents","quarter","countedCents"]}},"balanceCents":{"type":"integer"},"breakEven":{"type":"array","items":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"name":{"type":"string"},"paychecksLeft":{"type":"integer"},"perPaycheckCents":{"type":"integer"}},"required":["jobId","name","paychecksLeft","perPaycheckCents"]}},"safeHarbor":{"type":"object","properties":{"basis":{"type":"string","enum":["prior_year_100","prior_year_110","current_year_90","no_tax_last_year"]},"requiredCents":{"type":"integer"},"currentYearTaxCents":{"type":"integer"},"withholdingCents":{"type":"integer"},"estimatedPaymentsCents":{"type":"integer"},"underFloor":{"type":"boolean"},"shortfallCents":{"type":"integer"},"quarters":{"type":"array","items":{"type":"object","properties":{"quarter":{"type":"integer"},"due":{"type":"string"},"requiredCents":{"type":"integer"},"paidCents":{"type":"integer"},"short":{"type":"boolean"}},"required":["quarter","due","requiredCents","paidCents","short"]}},"likelyPenalty":{"type":"boolean"}},"required":["basis","requiredCents","currentYearTaxCents","withholdingCents","estimatedPaymentsCents","underFloor","shortfallCents","quarters","likelyPenalty"]},"safeHarborSummary":{"type":"string"},"effectiveRateBps":{"type":"integer"},"statement":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"figureCents":{"type":"integer"},"detail":{"type":"string"}},"required":["label","figureCents"]}},"assumptions":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"stateNote":{"type":"string"},"ignores":{"type":"array","items":{"type":"string"}},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["paystub","w2","form_1099","form_1098","tax_return","benefits","statement","receipt","other"]},"taxYear":{"type":["integer","null"]},"documentOn":{"type":["string","null"]},"for":{"type":"string"},"incomeSourceId":{"type":["string","null"],"format":"uuid"}},"required":["id","name","kind","taxYear","documentOn","for","incomeSourceId"]}},"outcome":{"type":"object","properties":{"kind":{"type":"string","enum":["refund","owe","even"]},"sumCents":{"type":"integer"},"totalTaxCents":{"type":"integer"},"paidAndProjectedCents":{"type":"integer"}},"required":["kind","sumCents","totalTaxCents","paidAndProjectedCents"]}},"required":["taxYear","today","filingStatus","figuresSource","settings","jobs","businesses","wagesCents","businessIncomeCents","otherIncomeCents","capitalGainsCents","totalIncomeCents","halfSeTaxCents","agiCents","deduction","qbi","taxableIncomeCents","capitalGainsTax","incomeTaxCents","marginalRateBps","childTaxCredit","seTax","additionalMedicareTaxCents","netInvestmentIncomeTax","totalTaxCents","payments","estimatedPayments","balanceCents","breakEven","safeHarbor","safeHarborSummary","effectiveRateBps","statement","assumptions","warnings","stateNote","ignores","outcome"]},"TaxSettings":{"type":"object","properties":{"taxYear":{"type":"integer"},"priorYearTaxCents":{"type":["integer","null"]},"priorYearAgiCents":{"type":["integer","null"]},"otherPaymentsCents":{"type":"integer"},"priorYearPaymentsCents":{"type":"integer"},"otherIncomeCents":{"type":"integer"},"capitalGainsCents":{"type":"integer"},"itemizedDeductionsCents":{"type":["integer","null"]},"qualifyingChildren":{"type":["integer","null"]},"notes":{"type":"string"},"source":{"$ref":"#/components/schemas/ContextSource"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["taxYear","priorYearTaxCents","priorYearAgiCents","otherPaymentsCents","priorYearPaymentsCents","otherIncomeCents","capitalGainsCents","itemizedDeductionsCents","qualifyingChildren","notes","source","updatedAt"]},"ContextSource":{"type":["string","null"],"enum":["user","agent",null]},"AgentTasks":{"type":"object","properties":{"today":{"type":"string"},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/AgentTask"}}},"required":["today","tasks"]},"AgentBuckets":{"type":"object","properties":{"today":{"type":"string"},"pots":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string","format":"uuid"},"account":{"type":"string"},"balanceCents":{"type":["integer","null"]},"bucketedCents":{"type":"integer"},"shortfallCents":{"type":"integer"},"unassignedCents":{"type":["integer","null"]},"overAssigned":{"type":"boolean"},"owedCents":{"type":"integer"},"buckets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"balanceCents":{"type":"integer"},"targetCents":{"type":["integer","null"]},"targetDate":{"type":["string","null"]},"progressBps":{"type":["integer","null"]},"remainingCents":{"type":["integer","null"]},"monthsLeft":{"type":["integer","null"]},"monthlyNeededCents":{"type":["integer","null"]},"plannedMonthlyCents":{"type":"integer"},"fundedBy":{"type":"array","items":{"type":"string"}},"overflow":{"type":"boolean"},"notes":{"type":"string"},"archived":{"type":"boolean"},"owedCents":{"type":"integer"},"recentEntries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"date":{"type":"string"},"kind":{"type":"string","enum":["set_balance","contribution","withdrawal","charge","move"]},"changeCents":{"type":"integer"},"balanceAfterCents":{"type":"integer"},"memo":{"type":"string"},"otherBucket":{"type":["string","null"]},"transactionId":{"type":["string","null"],"format":"uuid"},"transaction":{"type":["string","null"]},"auto":{"type":"boolean"},"settledOn":{"type":["string","null"]}},"required":["id","date","kind","changeCents","balanceAfterCents","memo","otherBucket","transactionId","transaction","auto","settledOn"]}}},"required":["id","name","balanceCents","targetCents","targetDate","progressBps","remainingCents","monthsLeft","monthlyNeededCents","plannedMonthlyCents","fundedBy","overflow","notes","archived","owedCents","recentEntries"]}}},"required":["accountId","account","balanceCents","bucketedCents","shortfallCents","unassignedCents","overAssigned","owedCents","buckets"]}}},"required":["today","pots"]},"AgentReviewItems":{"type":"object","properties":{"openCount":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["deposit","charge","withdrawal"]},"status":{"type":"string","enum":["open","approved","dismissed"]},"title":{"type":"string"},"reason":{"type":"string"},"date":{"type":"string"},"transactionId":{"type":"string","format":"uuid"},"transaction":{"type":"string"},"amountCents":{"type":"integer"},"account":{"type":"string"},"proposal":{"type":"object","properties":{"allocations":{"type":"array","items":{"type":"object","properties":{"bucketId":{"type":"string","format":"uuid"},"bucket":{"type":"string"},"shareCents":{"type":"integer"}},"required":["bucketId","bucket","shareCents"]}},"paysBack":{"type":"array","items":{"type":"object","properties":{"entryId":{"type":"string","format":"uuid"},"bucket":{"type":"string"},"chargedCents":{"type":"integer"},"date":{"type":"string"},"transaction":{"type":["string","null"]}},"required":["entryId","bucket","chargedCents","date","transaction"]}},"rule":{"type":["string","null"]}},"required":["allocations","paysBack","rule"]},"waiting":{"type":"boolean"},"owedCharges":{"type":"array","items":{"type":"object","properties":{"entryId":{"type":"string","format":"uuid"},"bucket":{"type":"string"},"chargedCents":{"type":"integer"},"date":{"type":"string"},"transaction":{"type":["string","null"]}},"required":["entryId","bucket","chargedCents","date","transaction"]}},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","kind","status","title","reason","date","transactionId","transaction","amountCents","account","proposal","waiting","owedCharges","resolvedAt"]}}},"required":["openCount","items"]},"AgentBucketRules":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"bucketId":{"type":"string","format":"uuid"},"bucket":{"type":"string"},"account":{"type":"string"},"matches":{"type":"string"},"chargedCount":{"type":"integer"}},"required":["id","bucketId","bucket","account","matches","chargedCount"]}}},"required":["rules"]},"AgentDocuments":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/AgentDocument"}}},"required":["documents"]},"AgentDocument":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["paystub","w2","form_1099","form_1098","tax_return","benefits","statement","receipt","other"]},"taxYear":{"type":["integer","null"]},"documentOn":{"type":["string","null"]},"uploadedOn":{"type":"string"},"contentType":{"type":"string"},"sizeBytes":{"type":"integer"},"pages":{"type":["integer","null"]},"readable":{"type":"string","enum":["text","image","scan","unreadable"]},"entity":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"incomeSource":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"account":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"manualAccount":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"notes":{"type":"string"},"match":{"type":["string","null"]}},"required":["id","name","kind","taxYear","documentOn","uploadedOn","contentType","sizeBytes","pages","readable","entity","incomeSource","account","manualAccount","notes"]},"AgentDocumentRead":{"type":"object","properties":{"document":{"$ref":"#/components/schemas/AgentDocument"},"text":{"type":["string","null"]},"offset":{"type":"integer"},"nextOffset":{"type":["integer","null"]},"totalChars":{"type":"integer"},"guidance":{"type":"string"}},"required":["document","text","offset","nextOffset","totalChars","guidance"]},"UploadDocument":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"metadata":{"type":"string","maxLength":10000}},"required":["file","metadata"]},"ExportDocument":{"type":"object","properties":{"exportedAt":{"type":"string","format":"date-time"},"format":{"type":"string","enum":["truenote-export/1"]},"tables":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","additionalProperties":{}}}}},"required":["exportedAt","format","tables"]}},"parameters":{}},"paths":{"/v1/overview":{"get":{"operationId":"v1Overview","summary":"Net worth, this month, the plan, bills, goals and the next estimated tax in one call","description":"Needs any read scope. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentOverview"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/accounts":{"get":{"operationId":"v1Accounts","summary":"Accounts with latest balances (debts negative), manual accounts and net worth totals","description":"Needs accounts:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["depository","credit","loan","investment","other"],"description":"Only accounts of this type"},"required":false,"description":"Only accounts of this type","name":"type","in":"query"},{"schema":{"type":"string","description":"Include closed accounts, and accounts the person hid if this token may see hidden accounts"},"required":false,"description":"Include closed accounts, and accounts the person hid if this token may see hidden accounts","name":"includeHidden","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAccountList"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/transactions":{"get":{"operationId":"v1Transactions","summary":"Transactions newest first, filtered, keyset-paged (money in positive)","description":"Needs transactions:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"First day (inclusive); default: all history"},"required":false,"description":"First day (inclusive); default: all history","name":"from","in":"query"},{"schema":{"type":"string","description":"Last day (inclusive)"},"required":false,"description":"Last day (inclusive)","name":"to","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"accountId","in":"query"},{"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","enum":["none"]}],"description":"A category id (its subcategories included), or `none` for uncategorized"},"required":false,"description":"A category id (its subcategories included), or `none` for uncategorized","name":"categoryId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"entityId","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Merchant or description contains this (any case)"},"required":false,"description":"Merchant or description contains this (any case)","name":"merchant","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Description, merchant or note contains this"},"required":false,"description":"Description, merchant or note contains this","name":"q","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Size at least this, in cents (either direction)"},"required":false,"description":"Size at least this, in cents (either direction)","name":"minAmountCents","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"maxAmountCents","in":"query"},{"schema":{"type":"string","enum":["in","out"],"description":"Money in or money out"},"required":false,"description":"Money in or money out","name":"direction","in":"query"},{"schema":{"type":"string"},"required":false,"name":"pending","in":"query"},{"schema":{"type":"string","description":"true: only a business's spending paid from a personal account"},"required":false,"description":"true: only a business's spending paid from a personal account","name":"ownerContribution","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Rows per page (default 50, max 200)"},"required":false,"description":"Rows per page (default 50, max 200)","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"`nextCursor` of the last page"},"required":false,"description":"`nextCursor` of the last page","name":"cursor","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTransactionPage"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/spending":{"get":{"operationId":"v1Spending","summary":"Spending grouped by category, merchant, entity or month: the household's by default (scope=all adds the businesses; entityId picks one)","description":"Needs transactions:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Default: the first of this month"},"required":false,"description":"Default: the first of this month","name":"from","in":"query"},{"schema":{"type":"string","description":"Default: today"},"required":false,"description":"Default: today","name":"to","in":"query"},{"schema":{"type":"string","enum":["category","merchant","entity","month"],"default":"category"},"required":false,"name":"groupBy","in":"query"},{"schema":{"type":"string","enum":["household","all"],"description":"household (default): the personal entities, as the overview's month counts them; all: the household and every business together. Ignored with entityId"},"required":false,"description":"household (default): the personal entities, as the overview's month counts them; all: the household and every business together. Ignored with entityId","name":"scope","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Only this entity's spending (one business)"},"required":false,"description":"Only this entity's spending (one business)","name":"entityId","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Only this category (and its subcategories)"},"required":false,"description":"Only this category (and its subcategories)","name":"categoryId","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Groups to list (default 25); the rest are summed"},"required":false,"description":"Groups to list (default 25); the rest are summed","name":"limit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSpending"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/recurring":{"get":{"operationId":"v1Recurring","summary":"Recurring bills, subscriptions and income with next dates and monthly totals","description":"Needs transactions:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["inflow","outflow"]},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string"},"required":false,"name":"includeInactive","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRecurring"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/net-worth-history":{"get":{"operationId":"v1NetWorthHistory","summary":"Net worth over time by account type (day, week or month points)","description":"Needs accounts:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Default: a year ago"},"required":false,"description":"Default: a year ago","name":"from","in":"query"},{"schema":{"type":"string","description":"Default: today"},"required":false,"description":"Default: today","name":"to","in":"query"},{"schema":{"type":"string","enum":["day","week","month"],"default":"month"},"required":false,"name":"interval","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentNetWorthHistory"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/holdings":{"get":{"operationId":"v1Holdings","summary":"Investment positions by account, optionally the latest investment transactions","description":"Needs investments:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"accountId","in":"query"},{"schema":{"type":"string","description":"Also the latest investment transactions (buys, sells, dividends)"},"required":false,"description":"Also the latest investment transactions (buys, sells, dividends)","name":"includeTransactions","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentHoldings"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/investment-transactions":{"get":{"operationId":"v1InvestmentTransactions","summary":"Investment transactions newest first, filtered by date, account, type, subtype or symbol, keyset-paged, with totals by kind (cash in positive)","description":"Needs investments:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"First day (inclusive); default: all history"},"required":false,"description":"First day (inclusive); default: all history","name":"from","in":"query"},{"schema":{"type":"string","description":"Last day (inclusive)"},"required":false,"description":"Last day (inclusive)","name":"to","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"accountId","in":"query"},{"schema":{"type":"string","enum":["buy","sell","cash","fee","transfer","cancel"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":60,"description":"Plaid's subtype, any case: dividend, interest, buy, sell, deposit…"},"required":false,"description":"Plaid's subtype, any case: dividend, interest, buy, sell, deposit…","name":"subtype","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":20,"description":"Ticker, any case"},"required":false,"description":"Ticker, any case","name":"symbol","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Description contains this"},"required":false,"description":"Description contains this","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Rows per page (default 50, max 200)"},"required":false,"description":"Rows per page (default 50, max 200)","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"`nextCursor` of the last page"},"required":false,"description":"`nextCursor` of the last page","name":"cursor","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentInvestmentTransactionPage"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/liabilities":{"get":{"operationId":"v1Liabilities","summary":"Cards and loans: owed, APR, minimums, due dates","description":"Needs liabilities:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLiabilities"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/context":{"get":{"operationId":"v1Context","summary":"Profile, entities, income sources, goals, categories, rules, notes, plans","description":"Needs context:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentContext"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/plan":{"get":{"operationId":"v1Plan","summary":"The spending plan: regular take-home split into groups and lines","description":"Needs context:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPlan"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/plan/actuals":{"get":{"operationId":"v1PlanActuals","summary":"Plan vs actual for a month: household spending per plan group and category line against the plan, the trailing 3 months' average, and spending no line names","description":"Needs context:read, transactions:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"A month like 2026-10; default this month"},"required":false,"description":"A month like 2026-10; default this month","name":"month","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPlanActuals"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/taxes/projection":{"get":{"operationId":"v1TaxProjection","summary":"The year's federal tax projected from today: the statement line by line, the refund or amount owed, the extra withholding per paycheck that breaks even, the safe harbor","description":"Needs context:read, transactions:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":2000,"maximum":2100},"required":false,"name":"year","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaxProjection"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/tasks":{"get":{"operationId":"v1Tasks","summary":"The checklist: open tasks by due date (status=done|all for the rest)","description":"Needs context:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["open","done","all"],"default":"open"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTasks"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/buckets":{"get":{"operationId":"v1Buckets","summary":"Buckets: each account's virtual split, balances from Truenote's ledger, targets and what's Unassigned","description":"Needs accounts:read, context:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Only this account's buckets"},"required":false,"description":"Only this account's buckets","name":"accountId","in":"query"},{"schema":{"type":"string","description":"Also archived buckets"},"required":false,"description":"Also archived buckets","name":"includeArchived","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":50,"description":"Latest ledger entries per bucket (default 3)"},"required":false,"description":"Latest ledger entries per bucket (default 3)","name":"recentEntries","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentBuckets"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/review-items":{"get":{"operationId":"v1ReviewItems","summary":"The Review queue: deposits to split, spending that looks like a bucket's, money taken out of a bucketed account, each with a proposal","description":"Needs accounts:read, transactions:read, context:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["open","resolved"],"description":"open (default): waiting for a decision; resolved: the latest decided"},"required":false,"description":"open (default): waiting for a decision; resolved: the latest decided","name":"status","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentReviewItems"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/bucket-rules":{"get":{"operationId":"v1BucketRules","summary":"Bucket rules: spending they charge to a bucket automatically, first match wins","description":"Needs accounts:read, context:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentBucketRules"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/documents":{"get":{"operationId":"v1Documents","summary":"Documents the person uploaded (paystubs, tax forms, statements), newest first","description":"Needs documents:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":100,"description":"Words in the name, notes or text (Social Security and account numbers masked)"},"required":false,"description":"Words in the name, notes or text (Social Security and account numbers masked)","name":"q","in":"query"},{"schema":{"type":"string","enum":["paystub","w2","form_1099","form_1098","tax_return","benefits","statement","receipt","other"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"integer","minimum":2000,"maximum":2100},"required":false,"name":"taxYear","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDocuments"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}},"post":{"operationId":"v1UploadDocument","summary":"Keep a document for the person (multipart: file + metadata, a SaveDocument as JSON)","description":"Needs documents:write. A PDF, PNG, JPEG or WebP image, at most 10 MB; the same file twice is a 409. Its entity, income source and account must be ones this token can see. Example: curl -H 'Authorization: Bearer tn_pat_…' -F file=@paystub.pdf -F 'metadata={\"name\":\"Paystub Oct 16\",\"kind\":\"paystub\",\"taxYear\":2026}' <origin>/v1/documents","tags":["v1"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadDocument"}}}},"responses":{"201":{"description":"Kept","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDocument"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"Conflicts with the current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"413":{"description":"The request body is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/documents/{id}":{"get":{"operationId":"v1Document","summary":"One document's text (masked, paged by offset); an image's bytes are at /file","description":"Needs documents:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Id"},"required":true,"description":"Id","name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"description":"Where to continue a long text (the last call's nextOffset)"},"required":false,"description":"Where to continue a long text (the last call's nextOffset)","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDocumentRead"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/documents/{id}/file":{"get":{"operationId":"v1DocumentFile","summary":"A document's file as uploaded (unmasked)","description":"Needs documents:read.","tags":["v1"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Id"},"required":true,"description":"Id","name":"id","in":"path"}],"responses":{"200":{"description":"The file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/export":{"get":{"operationId":"v1Export","summary":"Everything this token can see, every table, as JSON (truenote-export/1)","description":"Needs accounts:read, transactions:read, investments:read, liabilities:read, context:read. Accounts and entities the token excludes are invisible here, totals included.","tags":["v1"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportDocument"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found (or not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/v1/export.zip":{"get":{"operationId":"v1ExportZip","summary":"The same export as a zip of CSV files, one per table","description":"Needs accounts:read, transactions:read, investments:read, liabilities:read, context:read.","tags":["v1"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"A zip of CSVs","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Signed in, but not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}}},"webhooks":{}}