Search documentation
Fuzzy search across every docs page and section
API referenceAI products
Fuzzy search across every docs page and section
API referenceAI products
API reference
Nine AI enrichment endpoints: categorization, subscriptions, cash flow, merchant intel, health score, summaries, fraud risk, purchase analysis, weekly reports.
AI products turn raw financial data into decisions. Each endpoint is independently sellable, counts against your AI request quota (plans), and responds in one round trip — no jobs to poll.
access_token mode — pass an item's access token and FeelConnect reads the data it needs. Zero payload engineering. Every AI product is derived from transactions, so the item must have transactions in its Link consent; without it the call returns permission_error / product_not_consented, exactly like /v1/transactions/get.transactions array) with no access token. Use FeelConnect AI on data you aggregated elsewhere. Supported by categorize, subscriptions, fraud-risk, and purchase-analysis; merchant takes only a query.Every AI response reports how it was produced. FeelConnect is rules-first: deterministic engines (merchant tables, cadence detection, scoring formulas) run always; a language model then enhances the result when available. If the AI layer is unreachable, endpoints degrade to rules-only instead of failing.
| engine | Meaning |
|---|---|
rules | Deterministic engines only. Always available. |
ai | Model output (with schema validation) drove the response. |
ai+rules | Rules produced the base result; the model enriched it (narratives, edge cases). |
When a model was used, the response also includes model (for example kimi-k3).
/v1/ai/categorizeMaps transactions onto the category taxonomy with confidence scores.
access_tokenstringtransactions.transactionsobject[][{ id, description, amount, merchant? }] — up to 500 per call.curl https://api.feelconnect.dev/v1/ai/categorize \-H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \-H "Content-Type: application/json" \-d '{"transactions":[{"id":"t1","description":"SQ *BLUE BOTTLE COFFEE OAK","amount":6.75},{"id":"t2","description":"COMCAST CABLE COMM","amount":89.99}]}'
{"categorized": [{"id": "t1","category": "Food & Drink","category_detailed": "Coffee Shops","confidence": 0.98},{"id": "t2","category": "Utilities","category_detailed": "Internet","confidence": 0.95}],"engine": "ai+rules","model": "kimi-k3"}
/v1/ai/subscriptionsFinds paid subscriptions, prices them annually, and flags likely-unused ones.
access_tokenstringtransactions.transactionsobject[]curl https://api.feelconnect.dev/v1/ai/subscriptions \-H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \-H "Content-Type: application/json" \-d '{"access_token":"fc_at_…"}'
{"subscriptions": [{"merchant_name": "Streamflix","cadence": "monthly","average_amount": 15.99,"annual_cost": 191.88,"last_date": "2026-07-12","next_date": "2026-08-12","likely_unused": false,"note": null},{"merchant_name": "FitCloud Pro","cadence": "monthly","average_amount": 29.99,"annual_cost": 359.88,"last_date": "2026-07-03","next_date": "2026-08-03","likely_unused": true,"note": "No gym-adjacent activity in 4 months; consider cancelling."}],"monthly_total": 45.98,"annual_total": 551.76,"engine": "ai+rules","model": "kimi-k3"}
/v1/ai/cashflowProjects daily inflow, outflow, and balance over a horizon, with the lowest point and a risk call.
access_tokenstringrequiredhorizon_daysnumbercurl https://api.feelconnect.dev/v1/ai/cashflow \-H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \-H "Content-Type: application/json" \-d '{"access_token":"fc_at_…","horizon_days":30}'
{"forecast": {"horizon_days": 30,"daily": [{"date": "2026-07-29","inflow": 0,"outflow": 74.2,"balance": 4252.98},{"date": "2026-07-31","inflow": 3184.62,"outflow": 41.5,"balance": 7396.1}],"summary": {"projected_end_balance": 5122.4,"lowest_point": {"date": "2026-08-10","balance": 1874.33},"risk": "low","narrative": "Payroll on Jul 31 comfortably covers the Aug 1 rent; balance stays above $1,800 all month."}},"engine": "ai+rules","model": "kimi-k3"}
/v1/ai/merchantResolves a raw statement descriptor into a clean merchant with category and website.
querystringrequiredSQ *BLUE BOTTLE COF OAK.curl https://api.feelconnect.dev/v1/ai/merchant \-H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \-H "Content-Type: application/json" \-d '{"query":"SQ *BLUE BOTTLE COF OAK"}'
{"merchant": {"query": "SQ *BLUE BOTTLE COF OAK","merchant_name": "Blue Bottle Coffee","category": "Food & Drink","website": "bluebottlecoffee.com","description": "Specialty coffee roaster and cafe chain."},"engine": "ai","model": "kimi-k3"}
/v1/ai/health-scoreA 0–100 financial health score with explainable subscores and one top recommendation.
access_tokenstringrequiredcurl https://api.feelconnect.dev/v1/ai/health-score \-H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \-H "Content-Type: application/json" \-d '{"access_token":"fc_at_…"}'
{"health": {"score": 72,"subscores": {"savings_rate": 68,"cashflow_stability": 81,"debt_ratio": 64,"emergency_fund": 55,"investment_rate": 77},"narrative": "Solid, steady cash flow; the emergency fund is the weak spot at 1.8 months of expenses.","top_recommendation": "Automate $250/mo into savings to reach a 3-month emergency fund by March."},"engine": "ai+rules","model": "kimi-k3"}
/v1/ai/financial-summaryA plain-language summary of the period with highlight bullets — ready to render.
access_tokenstringrequiredperiodstringweek | month | quarter. Defaults to month.curl https://api.feelconnect.dev/v1/ai/financial-summary \-H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \-H "Content-Type: application/json" \-d '{"access_token":"fc_at_…","period":"month"}'
{"summary": "July income of $6,369 against $4,884 in spending left $1,485 net. Dining rose 22% while transport fell 15%; all bills posted on time.","highlights": ["Net positive month: +$1,485","Dining up 22% vs June ($412 → $503)","Subscriptions steady at $46/mo"],"engine": "ai+rules","model": "kimi-k3"}
/v1/ai/fraud-riskScores transactions for fraud and anomaly signals: duplicates, unusual merchants, out-of-pattern amounts and geographies.
access_tokenstringtransactions.transactionsobject[]curl https://api.feelconnect.dev/v1/ai/fraud-risk \-H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \-H "Content-Type: application/json" \-d '{"access_token":"fc_at_…"}'
{"signals": [{"transaction_id": "txn_5jP8wQxV2mB9nY3cRk1z","risk": "high","reasons": ["Merchant never seen in 24 months of history","Amount 6.4x the account's daily average","Charge posted 02:14 local time"]}],"overall_risk": "medium","engine": "ai+rules","model": "kimi-k3"}
/v1/ai/purchase-analysisShould this user buy this thing. Returns a verdict with regret and feeling scores, opportunity cost projections, and budget impact — grounded in the user's actual finances when an access_token is provided.
item.namestringrequireditem.pricenumberrequireditem.urlstringaccess_tokenstringcontextobject{ "reason": "gift" }.curl https://api.feelconnect.dev/v1/ai/purchase-analysis \-H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \-H "Content-Type: application/json" \-d '{"item":{"name":"Aeron office chair","price":1395},"access_token":"fc_at_…"}'
{"analysis": {"verdict": "wait","regret_score": 41,"feeling_score": 74,"opportunity_cost": [{"years": 5,"value": 1899.14},{"years": 10,"value": 2585.98}],"budget_impact": "28% of your typical monthly discretionary spend.","reasoning": "You work from home daily, so utility is high — but this month already runs $310 over the discretionary baseline. Waiting for the September restock avoids dipping into the emergency fund.","alternatives": ["Refurbished Aeron (~$650)","Wait for the Labor Day sale"]},"engine": "ai+rules","model": "kimi-k3"}
/v1/ai/weekly-reportA digest of one week: totals, largest purchases, subscription changes, a win, an opportunity, and one recommended action.
access_tokenstringrequiredweek_ofstringYYYY-MM-DD inside the target week. Defaults to the last full week.curl https://api.feelconnect.dev/v1/ai/weekly-report \-H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \-H "Content-Type: application/json" \-d '{"access_token":"fc_at_…","week_of":"2026-07-20"}'
{"report": {"week_start": "2026-07-20","income": 3184.62,"expenses": 1211.4,"net": 1973.22,"largest_purchases": [{"name": "Alaska Airlines","amount": 348.6,"date": "2026-07-22"},{"name": "GreenMart","amount": 132.15,"date": "2026-07-24"}],"subscription_changes": ["FitCloud Pro renewed at $29.99 (was $24.99)"],"biggest_win": "Groceries came in 18% under the 4-week average.","biggest_opportunity": "FitCloud Pro price hike — cancel or downgrade saves $360/yr.","recommended_action": "Move this week's $1,973 surplus: $1,500 to savings, $473 to the card balance.","narrative": "A strong week — payroll landed, spending stayed routine, and the flight was the only splurge."},"engine": "ai+rules","model": "kimi-k3"}