Era API

एजेंट को मंज़ूरी देने से एक की बनती है

जब आप OAuth से किसी एजेंट को मंज़ूरी देते हैं, Era उसके लिए एक API की बना देता है। वह उसी डैशबोर्ड सूची में आती है जिसमें आपकी बनाई कीज़ हैं, और नाम Era ख़ुद क्लाइंट के नाम से बनाता है।

उसमें ठीक वही स्कोप होते हैं जो आपने उस स्क्रीन पर मंज़ूर किए थे, और कुछ नहीं। डैशबोर्ड से उसे रद्द करें, और जब तक आप उसे दोबारा मंज़ूर न करें, एजेंट को नई पहुँच नहीं मिलेगी। उसके पास पहले से मौजूद टोकन अपनी मियाद ख़त्म होने तक चलता रहता है, ज़्यादा से ज़्यादा एक घंटे।

राइट आपके एक्टिविटी लॉग में दिखते हैं, रीड नहीं

की बनाना और रद्द करना, दोनों आपके एक्टिविटी लॉग में दिखते हैं, और एजेंट MCP पर जो भी टूल कॉल करता है वह भी। REST राइट भी दिखता है — उस बदलाव के रूप में जो उसने किया, जैसे कोई टैग बना या कोई ट्रांज़ैक्शन बदला। REST रीड कोई एंट्री नहीं बनाता। ये एंट्रियाँ Era हर प्लान पर दर्ज करता है, लेकिन पूरा लॉग पढ़ने के लिए Organize या उससे ऊपर चाहिए — उससे नीचे आपको सिर्फ़ सबसे नई एंट्रियाँ दिखती हैं। राइट की एंट्री में आपके अकाउंट का नाम होता है, उस की का नहीं जिसने बदलाव किया।

किसी की पर कभी शक हो तो उसे रद्द कर दीजिए। आपकी ख़ुद बनाई की अपने अगले ही अनुरोध से REST और MCP पर काम करना बंद कर देती है। किसी एजेंट के लिए बनी की को तुरंत नई पहुँच मिलनी बंद हो जाती है, और उसके पास पहले से मौजूद कोई भी टोकन एक घंटे के भीतर ख़त्म हो जाता है। नई की बनाने में एक मिनट लगता है।

हर जुड़े संस्थान में फैले, वे सारे अकाउंट जो आपको दिखते हैं — और उनके बग़ल में उनकी गिनती भी जो छूट गए: excludedAccountCount, जो दो हिस्सों में बँटी है — tierExcludedAccountCount उन अकाउंट के लिए जिन्हें आपके प्लान की लाइव डेटा स्रोत सीमा बाहर रखती है, और userExcludedAccountCount उनके लिए जिन्हें आपने छिपाया है। accountLimit बताता है कि आपका प्लान आपके सारे कनेक्शन मिलाकर एक साथ लाइव डेटा स्रोत से आने वाले कितने अकाउंट दिखाता है। मैन्युअल अकाउंट इस सीमा में नहीं गिने जाते। accountLimitLift उस सबसे सस्ते प्लान का नाम बताता है जिसमें लाइव डेटा स्रोत से आने वाले आपके हर न-छिपाए अकाउंट के लिए जगह है, और जब आपका प्लान कुछ भी बाहर नहीं रखता, तब यह null होता है। हर अकाउंट अपने साथ अपना accountGroupKey लेकर आता है — वही मान जो बैलेंस वाला एंडपॉइंट अपने पाथ में लेता है — और वह connectionId भी जिससे वह जुड़ा है, इसलिए सबसे पहले यही कॉल कीजिए। connectionId लेता है ताकि आप एक ही कनेक्शन तक सीमित कर सकें (गिनतियाँ भी उसके साथ सीमित होती हैं, accountLimit और accountLimitLift नहीं), includeExcluded ताकि आपके प्लान से बाहर रखे गए और आपके छिपाए हुए अकाउंट भी आ जाएँ, और includeSevered ताकि उन कनेक्शन के अकाउंट भी आ जाएँ जिन्हें आपने डिस्कनेक्ट किया है। हर अकाउंट का archive फ़ील्ड बताता है कि वह आर्काइव है या नहीं, और क्यों; आर्काइव करने से सिर्फ़ यह बदलता है कि अकाउंट सूची में कैसे दिखता है, कोई बैलेंस या गिनती कभी नहीं।

{
  "accounts": [
    {
      "accountGroupKey": "uagr_7f3c9a21",
      "connectionId": "ucon_4b19e02c",
      "name": "Everyday Checking",
      "currentBalance": 4820.16,
      "supportsTransactions": true,
      …
    }
  ],
  "excludedAccountCount": 1
}

null लौटने वाला बैलेंस कभी शून्य नहीं होता, और उसका मतलब visibility फ़ील्ड बताता है। जिस अकाउंट को आपने छिपाया है (userExcluded), या जिसे आपका प्लान बाहर रखता है (tierExcluded), उसके बैलेंस वाले फ़ील्ड इसलिए null लौटते हैं कि बैलेंस रोक रखा गया है, ख़ाली नहीं। दिखने वाले अकाउंट में currentBalance का null बताता है कि प्रदाता ने कभी बैलेंस रिपोर्ट नहीं किया, और supportsBalances बताता है कि इस तरह का अकाउंट कोई बैलेंस रिपोर्ट करता भी है या नहीं। प्रदाता ने जो बैलेंस शून्य रिपोर्ट किया हो, वह अब भी 0 ही लौटता है। supportsTransactions का null भी इसी भाव में है: उसका मतलब है कि Era कह नहीं सकता, यह कभी नहीं कि जवाब ना है। प्लान वाले फ़ील्ड के साथ भी यही है: अगर उस कॉल पर Era आपका प्लान नहीं पढ़ पाया, तो tierExcludedAccountCount, userExcludedAccountCount, accountLimit और accountLimitLift सब null लौटते हैं। जिस प्लान में लाइव डेटा स्रोत की कोई सीमा नहीं, उसमें accountLimit भी null होता है, और जब किसी प्लान में इससे ज़्यादा जगह न हो या आपका प्लान कुछ भी बाहर न रखता हो, तो accountLimitLift भी।

One account's balance, with the credit fields filled in when the account is a liability. The path takes that account's accountGroupKey — the same value /banking/accounts returns for it. The key is not checked for shape before the lookup, so a malformed key and an unknown one answer the same way.

{
  "accountGroupKey": "uagr_7f3c9a21",
  "currentBalance": 4820.16,
  "availableBalance": 4712.03,
  "creditLimit": null,
  "currencyCode": "USD",
  "availableCredit": null,
  "asOf": "2026-08-11T09:32:00Z",
  "visibility": null
}

छिपाया हुआ अकाउंट हो, या वह जिसका कनेक्शन टूट चुका है — जवाब फिर भी 200 ही आता है, बस बैलेंस वाले फ़ील्ड null होते हैं। 404 का मतलब है कि अकाउंट सचमुच है ही नहीं, या की की बनावट ही key जैसी नहीं थी। यहाँ visibility फ़ील्ड पर नज़र रखिए: अकाउंट दिखता हो तो वह null है, आपके प्लान की सीमा उसे बाहर रखे तो tier_excluded, आपने उसे छिपाया हो तो user_excluded, और उसका कनेक्शन टूट गया हो तो connection_severed। लाइव डेटा स्रोत से आने वाले tier_excluded अकाउंट के लिए accountLimit आपके प्लान की लाइव डेटा स्रोत सीमा है, और accountLimitLift उस सबसे सस्ते प्लान का नाम बताता है जिसमें इस अकाउंट समेत ऐसे आपके हर न-छिपाए अकाउंट के लिए जगह है। मैन्युअल अकाउंट और बाक़ी हर स्थिति में accountLimitLift null होता है, और connection_severed होने पर accountLimit भी null होता है। दिखने वाले अकाउंट में (visibility null हो) currentBalance का null बताता है कि कोई बैलेंस रिपोर्ट नहीं हुआ, शून्य नहीं। अकाउंट सूची में उस अकाउंट की पंक्ति का supportsBalances बताता है कि इस तरह का अकाउंट कोई बैलेंस रिपोर्ट करता भी है या नहीं।

जो अकाउंट आपको दिखते हैं, उन सबका जोड़, डिफ़ॉल्ट रूप से लाइव अकाउंट का: totalAssets, totalLiabilities, और netWorthHint, जो पहले में से दूसरा घटाकर बनता है। कौन-से मोड गिने जाएँ, यह चुनने के लिए simulationModes दें: अकाउंट की सूची और कुल जोड़ में सिर्फ़ वही मोड आते हैं जो आप बताते हैं। includedSimulationModes हर जवाब में बताता है कि ये कौन-से मोड गिनते हैं। simulationExcludedAccountCount उन अकाउंट की गिनती है जो आपको दिखते हैं पर अपने मोड की वजह से बाहर रह गए। totalHiddenCount अलग गिनती है: वे अकाउंट जिन्हें आपका प्लान या आपकी अपनी विज़िबिलिटी सेटिंग किसी भी मोड में छिपाती है, और simulationModes ने जिन्हें बाहर रखा, वे कभी इसमें नहीं आते।

{
  "userId": "7d1c0b93a8e24f60",
  "accounts": [ … ],
  "totalVisibleCount": 6,
  "totalHiddenCount": 2,
  "totalAssets": 48210.75,
  "totalLiabilities": 9327.40,
  "netWorthHint": 38883.35,
  "includedSimulationModes": [ "live" ],
  "simulationExcludedAccountCount": 0,
  "computedAt": "2026-08-11T09:32:00Z"
}

netWorthHint सिर्फ़ इसी रिस्पॉन्स में आए अकाउंट गिनता है, और क्या छूट रहा है यह दो गिनतियाँ बताती हैं। simulationExcludedAccountCount उन अकाउंट की संख्या है जो आपके माँगे गए मोड से बाहर हैं। totalHiddenCount उन अकाउंट की संख्या है जो किसी भी मोड में आपसे छिपे हैं। यह दो हिस्सों में बँटती है: tierExcludedAccountCount उन अकाउंट के लिए जिन्हें आपके प्लान की लाइव डेटा स्रोत सीमा बाहर रखती है, और userExcludedAccountCount उनके लिए जिन्हें आपने ख़ुद छिपाया है। अगर उस कॉल पर Era आपका प्लान नहीं पढ़ पाया, तो दोनों null होते हैं। accountLimitLift उस सबसे सस्ते प्लान का नाम बताता है जो पहली तरह के अकाउंट वापस ले आता है, और जब ऐसे अकाउंट न हों, तो यह null होता है। जिस अकाउंट का बैलेंस रिपोर्ट नहीं हुआ, वह सूची में आता है, पर कुल में कुछ नहीं जोड़ता। netWorthHint को आख़िरी नेट वर्थ नहीं, शुरुआती आँकड़ा मानकर चलिए।

आपके ट्रांज़ैक्शन, एक बार में एक पेज, पेजिंग की गिनती के साथ लपेटकर। page और pageSize लेता है (ऊपरी सीमा 100), साथ में अकाउंट, तारीख़ की सीमा, लागू नियम और लगाए गए टैग के वैकल्पिक फ़िल्टर।

{
  "transactions": [ … ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 412,
    "totalPages": 21
  },
  "historyWindowApplied": true,
  "historyWindowFloorDate": "2026-06-28",
  "historyWindowHiddenCount": 137,
  "historyWindowEarliestDate": "2024-03-02",
  "historyWindowDegraded": false
}

ऐसी कोई कॉल नहीं है जो id से अकेला एक ट्रांज़ैक्शन पढ़े। GET /banking/transactions/{id} पर Allow: PUT के साथ 405 मिलता है, क्योंकि वह पाथ सिर्फ़ ट्रांज़ैक्शन बदलने के लिए है। एक ट्रांज़ैक्शन पढ़ने के लिए उस तक पहुँचाने वाले फ़िल्टर के साथ सूची माँगें — accountId में उसका accountGroupKey, fromDate और toDate दोनों उसकी transactionDate पर, और व्यापारी के नाम या राशि पर search — फिर जो लौटे उसमें उसे उसके id से ढूँढें। अगर वह हाल का पेंडिंग चार्ज है, तो includePending भी जोड़ें।

आपका प्लान हिस्ट्री-विंडो की एक सीमा लगा सकता है, जो उससे पुराने ट्रांज़ैक्शन छिपा देती है। रिस्पॉन्स में historyWindow वाले फ़ील्ड इसीलिए आते हैं: historyWindowApplied बताता है कि सीमा ने सचमुच कुछ छिपाया, historyWindowFloorDate बताता है वह कहाँ पड़ी, historyWindowHiddenCount बताता है उसके पीछे कितनी पंक्तियाँ हैं, और historyWindowEarliestDate बताता है कि आपकी हिस्ट्री असल में कहाँ तक जाती है। इनके बिना छोटा नतीजा उस अकाउंट से अलग नहीं दिखता जिसमें इससे पुराने ट्रांज़ैक्शन हैं ही नहीं। इनमें से दो आपका कोड बदल देते हैं: सीमा लगी होने पर भी historyWindowHiddenCount null हो सकता है, इसलिए null को शून्य नहीं, अनजान मानकर पढ़ें; और जब historyWindowDegraded true हो, तो उस कॉल पर Era आपके प्लान की पुष्टि नहीं कर पाया, इसलिए सीमा की तारीख़ तथ्य नहीं, अनुमान है। जिस पेड कॉल में प्लान की पुष्टि हो जाती है, वहाँ कोई सीमा नहीं लगती और historyWindowApplied false लौटता है। आपके प्लान की लाइव डेटा स्रोत सीमा ट्रांज़ैक्शन भी बाहर रखती है: tierExcludedAccountCount बताता है कि वह आपके कितने अकाउंट इस कॉल से बाहर रखती है, और userExcludedAccountCount कि आपने कितने छिपाए हैं — अगर आपने किसी अकाउंट पर फ़िल्टर किया है, तो दोनों सिर्फ़ उसी अकाउंट तक सीमित रहते हैं। अगर उस कॉल पर Era आपका प्लान नहीं पढ़ पाया, तो दोनों null होते हैं।

लंबी हिस्ट्री को पेज-दर-पेज पढ़ने में अनुरोध ख़र्च होते हैं। आपका प्लान तय करता है कि आप कितनी तेज़ी से कॉल कर सकते हैं और, मुफ़्त प्लान पर, दिन में कितनी कॉल मिलती हैं; पेड प्लान उचित उपयोग पर चलते हैं। प्लान के हिसाब से आँकड़े, रेट-लिमिट हेडर, और 429 आपको क्या बताता है — सब लिमिट में है।

पूरी कैटेगरी व्यवस्था: कैटेगरी का हर समूह, जिसके अंदर उसकी उप-कैटेगरी नेस्टेड हैं। यह व्यवस्था साझा है, हर अकाउंट के लिए अलग नहीं।

{
  "packs": [
    {
      "packSlug": "default",
      "packName": "Era default categories",
      "isDefault": true,
      "categories": [
        {
          "projectionKey": "fcat_food_dining",
          "categoryName": "Food & dining",
          "isTopLevel": true,
          "children": [ … ]
        }
      ]
    }
  ],
  "meterLimit": 25,
  "canCreateCustomCategories": true
}

आपके अकाउंट के सारे टैग, एक ही सूची में। कोई पेजिंग नहीं — एक ही रिस्पॉन्स में सब लौट आते हैं।

{
  "tags": [
    {
      "tagKey": "ftag_3fG7kL9p",
      "name": "business-expense",
      "displayName": "Business expense",
      "tagType": "user",
      "color": "#6DC6BA",
      "transactionCount": 42
    }
  ]
}

आपके ट्रांज़ैक्शन में बार-बार आने वाले शुल्क, बिल और आय, सबसे बड़े estimatedAmount से शुरू करके। सूची दो में से किसी एक जगह से आती है। जब Era आपके ट्रांज़ैक्शन में आवर्ती पैटर्न पहचान लेता है, तो वह उन्हीं को लिस्ट करता है, हर एक confidence system के साथ। तब तक, वह हाल के ऐसे ट्रांज़ैक्शन को, जिन्हें आपके बैंक का डेटा आवर्ती, सब्सक्रिप्शन, बिल भुगतान या आय के रूप में चिह्नित करता है, मर्चेंट और मुद्रा के हिसाब से समूहों में बाँटता है, हर समूह confidence provider के साथ। हर आइटम में merchant होता है; estimatedAmount, हर बार की आम रक़म, जो कभी ऋणात्मक नहीं होती, पैसा चाहे किसी भी दिशा में जाए; frequency, Era का अनुमान कि यह कितनी बार दोहराता है; category, जो कोई न होने पर null होती है और Era के पहचाने पैटर्न में हमेशा null; lastSeen, सबसे हाल के ट्रांज़ैक्शन की तारीख़, या Era के पहचाने पैटर्न के लिए वह तारीख़ जब Era ने उसे पहचाना; type; और confidence। type तब subscription, bill या income होता है जब आपके बैंक का डेटा बताता है कि कौन-सा, और न बताने पर recurring, जो Era के पहचाने हर पैटर्न के साथ होता है। इसलिए जिस आइटम का type recurring है, उस पर कुछ नहीं बताता कि पैसा आ रहा है या जा रहा है। लंबित शुल्क शामिल नहीं होते। कोई पैरामीटर नहीं लेता, और आप जो भेजें उन्हें अनदेखा करता है।

{
  "items": [
    {
      "merchant": "Netflix",
      "estimatedAmount": { "amount": 15.49, "currency": "usd", … },
      "frequency": "monthly",
      "category": "Entertainment",
      "lastSeen": "2026-09-28",
      "type": "subscription",
      "confidence": "provider"
    },
    …
  ]
}

एक अवधि में आने और जाने वाला पैसा: income, expense और net, जो पहले में से दूसरा घटाकर बनता है, हर तरफ़ के पीछे की कैटेगरी के साथ — incomeCategories और expenseCategories, सबसे बड़ी पहले, हर एक के साथ उसकी रक़म, उस तरफ़ के कुल में उसका हिस्सा, और उसमें कितने ट्रांज़ैक्शन हैं। आपके अपने अकाउंट के बीच के ट्रांसफ़र, लंबित शुल्क, और वे ट्रांज़ैक्शन जिन्हें आपने छिपाया है या जो ऐसे अकाउंट पर हैं जिन्हें आपने छिपाया है या जिन्हें आपके प्लान की लाइव डेटा स्रोत सीमा बाहर रखती है, शामिल नहीं होते; excludedAccountCount उन अकाउंट को गिनता है। income और expense अपनी तरफ़ की हर कैटेगरी गिनते हैं, उन्हें भी जिन्हें topN सूची से बाहर रखता है, इसलिए लौटी कैटेगरी का जोड़ उस तरफ़ के कुल से कम हो सकता है; हर percentOfTotal उसी पूरे कुल का हिस्सा है। आपकी मांगी अवधि अपनी शुरुआत, अंत और एक पढ़ने लायक़ लेबल के साथ लौटती है। जब incomePercentOfTotalUnavailable या expensePercentOfTotalUnavailable true हो, तो उस तरफ़ के percentOfTotal मान 0 होते हैं क्योंकि हिस्सा निकाला नहीं जा सका, इसलिए नहीं कि कैटेगरी उसका 0% है — इन्हें ग़ायब मानें। डिफ़ॉल्ट रूप से इस महीने का।

{
  "period": { "period": "last_month", "start": "2026-09-01", "end": "2026-09-30", "label": "September 2026" },
  "income": { "amount": 5200.00, "currency": "usd", … },
  "expense": { "amount": 4000.00, "currency": "usd", … },
  "net": { "amount": 1200.00, "currency": "usd", … },
  "incomeCategories": [ … ],
  "expenseCategories": [
    {
      "label": "Groceries",
      "categoryKey": "fcat_groceries",
      "amount": { "amount": 600.00, "currency": "usd", … },
      "percentOfTotal": 15,
      "transactionCount": 14,
      "children": null
    },
    …
  ],
  "excludedAccountCount": 0,
  "excludedAccountNote": null,
  "incomePercentOfTotalUnavailable": false,
  "expensePercentOfTotalUnavailable": false
}

आपके अकाउंट के सभी ऑटोमेशन नियम — जो आपने बनाए और जो Era ने अपनी नियम लाइब्रेरी से आपके लिए सेट किए — हर एक उसकी शर्तों (filters), वह क्या करता है (actions), वह चालू है या नहीं, और उसके वर्ज़न के साथ। कोई पेजिंग नहीं: एक ही रिस्पॉन्स में सब लौट आते हैं। बंद नियम तब तक नहीं आते जब तक आप उन्हें न मांगें।

{
  "rules": [
    {
      "id": "rule_4c1e7a90",
      "ruleName": "Coffee shops",
      "isActive": true,
      "version": 3,
      "priority": 10,
      "filters": [{ "type": "merchant_match", "pattern": "Blue Bottle", "mode": "contains" }],
      "actions": [{ "type": "set_category", "categoryKey": "fcat_coffee_shops", "categoryDisplayName": "Coffee shops" }],
      "source": "user",
      "matchedTransactionCount": 42,
      …
    }
  ]
}

filters और actions टाइप किए गए ऑब्जेक्ट की सूचियाँ हैं। हर ऑब्जेक्ट एक type फ़ील्ड में अपना प्रकार बताता है — फ़िल्टर में merchant_match या category, एक्शन में set_category या add_tag — और क्विकस्टार्ट में लिंक किया गया OpenAPI डॉक्यूमेंट हर प्रकार और उसके फ़ील्ड की सूची देता है।