Era API

क्विकस्टार्ट

शुरू करने से पहले आपको एक Era अकाउंट चाहिए जिसमें कम से कम एक संस्थान जुड़ा हो — कनेक्शन के बिना इन एंडपॉइंट के पास लौटाने को कुछ नहीं होगा।

1. 1

   Era में साइन इन करें और अगर पहले से नहीं किया है तो कोई संस्थान जोड़ें।

2. 2

   डैशबोर्ड में अपनी API कीज़ खोलें और एक की बनाएं। शुरुआत में हर स्कोप पर निशान लगा होता है, इसलिए जो नहीं चाहिए उनसे निशान हटा दें — इन एंडपॉइंट के लिए banking:read बचता है। एक्सपायरी भी आप चुनते हैं; कभी न ख़त्म होने वाला विकल्प है ही नहीं।

3. 3

   की कॉपी कर लें। वह एक ही बार दिखती है, और हम दोबारा नहीं दिखा सकते। इसे कॉपी करके किसी सुरक्षित जगह रखें, जैसे किसी सीक्रेट्स मैनेजर में। अगर की खो जाए, तो आप उसे दोबारा नहीं देख सकते। इसकी जगह एक नई की बनाएँ।

4. 4

   अपनी रिक्वेस्ट के साथ उसे हेडर में भेजें।

curl "https://forge.era.app/api/banking/transactions?page=1&pageSize=20" \
  -H "X-API-Key: fmk_your_key_here"

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

उपलब्ध API

Era API में निम्नलिखित API शामिल हैं:

• GET/banking/accounts

  आपके हर जुड़े हुए संस्थान में, हर वह अकाउंट जिसे आप देख सकते हैं।

• GET/banking/accounts/{accountId}/balance

  एक अकाउंट का बैलेंस, देनदारी होने पर क्रेडिट से जुड़े फ़ील्ड सहित।

• GET/banking/accounts/summary

  आप जो भी अकाउंट देख सकते हैं, उन सबका कुल जोड़।

• GET/banking/transactions

  आपके ट्रांज़ैक्शन, एक बार में एक पेज।

• PUT/banking/transactions/{id}

  एक ट्रांज़ैक्शन बदलें

• PUT/banking/transactions/bulk

  एक साथ 100 तक बदलें

• GET/banking/categories

  पूरा कैटेगरी ढांचा, सब-कैटेगरी भी नेस्टेड।

• POST/banking/categories

  कैटेगरी जोड़ें

• GET/banking/tags

  आपके अकाउंट के सभी टैग, एक ही रिस्पॉन्स में।

• POST/banking/tags

  टैग बनाएँ

प्रमाणीकरण

अपनी की इन दो तरीकों में से किसी एक से भेजें:

हर रिक्वेस्ट TLS से एन्क्रिप्टेड होती है।

कीज़ ख़त्म होती हैं, और कितनी जल्दी — यह आप बनाते वक़्त चुनते हैं। ज़्यादा से ज़्यादा मुफ़्त प्लान पर 90 दिन और पेड प्लान पर 365 दिन। कभी न ख़त्म होने वाला विकल्प नहीं है, इसलिए इस पर बनाई किसी भी चीज़ को की समय रहते बदलने की योजना चाहिए।

रिस्पॉन्स हेडर

हर रिस्पॉन्स में एक रिक्वेस्ट ID आती है। रेट-लिमिट हेडर उन कॉल पर आते हैं जिन्हें Era ने मापा। अगर Era आपका इस्तेमाल माप न पाए, तो वह कॉल पूरी कर देता है और इनमें से कोई हेडर नहीं भेजता।

एरर

यह API ये एरर स्टेटस कोड लौटाता है:

• 400

  गलत इनपुट: कोई ग़लत पैरामीटर, खाली या 100 से ज़्यादा आइटम वाला बल्क अपडेट, या ऐसा राइट जो एक ही कॉल में एक ही फ़ील्ड को सेट भी करे और क्लियर भी।

• 401

  की नहीं है, या ऐसी की जो पार्स नहीं होती। इसे X-API-Key हेडर या बियरर टोकन के रूप में भेजें।

• 402

  प्लान का कोटा आड़े आ रहा है — आज के लिए, यह सिर्फ़ कैटेगरी बनाने पर लागू होता है। यह इस बारे में है कि आप क्या बना रहे हैं, न कि आप कितनी तेज़ी से कॉल कर रहे हैं: इंतज़ार से यह नहीं हटता, बड़े प्लान से हटता है। बहुत तेज़ी से कॉल करने पर इसके बजाय 429 आता है।

• 403

  की के पास इस कॉल को चाहिए वाला स्कोप नहीं है — या, दोनों ट्रांज़ैक्शन राइट में से किसी एक में, id किसी और की है या सिरे से मौजूद ही नहीं है। API इन दोनों में फ़र्क़ नहीं बताता।

• 404

  ऐसा अकाउंट जो मौजूद नहीं है। यह सिर्फ़ बैलेंस एंडपॉइंट देता है: ऐसा accountGroupKey जो किसी अकाउंट को नहीं दर्शाता, या जिसकी बनावट ही key जैसी नहीं है, बिना बॉडी के 404 लौटाता है। ट्रांज़ेक्शन कभी 404 नहीं देते — 403 देखें।

• 409

  आप लिख ही रहे थे कि किसी और चीज़ ने वह रो बदल दी। इसे फिर पढ़ें और अपना राइट फिर भेजें।

• 429

  बहुत ज़्यादा अनुरोध। आपने अपना दैनिक बजट ख़र्च कर दिया है या प्रति-मिनट बर्स्ट सीमा तक पहुँच गए हैं। कितना रुकना है, यह Retry-After बताता है, और 402 के उलट, यहाँ इंतज़ार से बात बन जाती है। किस सीमा ने मना किया और प्लान के हिसाब से आँकड़े, दोनों लिमिट में देखें।

एरर के फ़ॉर्मेट

ज़्यादातर एरर एक ही फ़ॉर्मेट में लौटते हैं: statusCode, message, और एक errors ऑब्जेक्ट जो बताता है कि क्या गड़बड़ थी। सभी नहीं: 401 और 404 बिना किसी बॉडी के लौटते हैं, इसलिए बॉडी पढ़ने से पहले स्टेटस पढ़ें।

{
  "statusCode": 403,
  "message": "One or more errors occurred!",
  "errors": {
    "generalErrors": ["Transaction does not belong to the authenticated user"]
  }
}

रिक्वेस्ट ID

हर रिस्पॉन्स में एक fly-request-id हेडर होता है। किसी ख़ास रिक्वेस्ट के बारे में सपोर्ट से बात करते समय इसे बताएं।

# Print the response headers, including fly-request-id; discard the body
curl -sS -D - -o /dev/null "https://forge.era.app/api/banking/transactions?page=1&pageSize=20" \
  -H "X-API-Key: fmk_your_key_here"

# A write call: same header, plus a JSON body
curl -sS -D - -X PUT "https://forge.era.app/api/banking/transactions/utgr_your_transaction_id" \
  -H "X-API-Key: fmk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"categoryKey": "fcat_dining", "merchantName": "Corner Cafe"}'

आम एरर

• एक ही राइट में किसी फ़ील्ड को सेट करना और क्लियर करना — 400।

• बल्क अपडेट में 100 से ज़्यादा id — 400, और कुछ नहीं बदलता। एक से कम भी वैसा ही है।

• ऐसा ट्रांज़ैक्शन जो आपका नहीं है, या सिरे से मौजूद ही नहीं — 403, कभी 404 नहीं। यानी रिस्पॉन्स कभी नहीं बताता कि कोई id मौजूद है या नहीं, बस इतना बताता है कि वह आपकी नहीं है।

• किसी और चीज़ ने पहले ही वह रो बदल दी — 409।

लिमिट

डॉक्यूमेंटेड दस एंडपॉइंट्स में से दो, एक कॉल में आप कितना मांग सकते हैं इस पर सीमा लगाते हैं। बाकी आठ नहीं लगाते।

इसका मतलब असीमित नहीं है: कीज़ अभी भी ख़त्म होती हैं, राइट्स पर अभी भी फ़ील्ड-लंबाई की सीमाएं हैं, कैटेगरी बनाना प्लान के कोटा से टकरा सकता है, और आपका प्लान अभी भी पुराना इतिहास छुपा सकता है। इनमें से कुछ भी रेट लिमिट नहीं है — नीचे देखें।

• अकाउंट्स, बैलेंस, समरी, कैटेगरी और टैग की लिस्ट, कैटेगरी बनाना, टैग बनाना, और सिंगल-ट्रांज़ेक्शन राइट पर कोई पर-कॉल वॉल्यूम सीमा नहीं है। आपको पूरा सेट वापस मिलता है, या वही एक रो जो आपने नाम से मांगी।

• pageSize को मना नहीं किया जाता, 100 पर सीमित कर दिया जाता है। ज़्यादा माँगें तो भी आपको 200 के साथ 100 रो मिलेंगी — जो भेजा उस पर भरोसा करने की बजाय रिस्पॉन्स में pagination.pageSize पढ़ें।

• ट्रांज़ैक्शन का बल्क राइट 100 id पर सीमित है, और pageSize से उलट इसे सीमित नहीं, मना कर दिया जाता है: 101 भेजें तो 400 मिलेगा और कुछ नहीं बदलेगा।

• की बनाते समय आपके चुने शेड्यूल पर एक्सपायर होती है — फ़्री प्लान पर ज़्यादा से ज़्यादा 90 दिन, पेड प्लान पर 365 दिन। कभी न एक्सपायर होने का कोई विकल्प नहीं है।

• आपका प्लान एक हिस्ट्री-विंडो फ़्लोर लगा सकता है जो पुराने ट्रांज़ैक्शन छुपा देता है। ट्रांज़ैक्शन के रिस्पॉन्स में historyWindow फ़ील्ड होते हैं जो बताते हैं कि कोई फ़्लोर लागू हुआ या नहीं और कहाँ।

रेट लिमिट

हर प्लान इस API को कॉल कर सकता है, और हर प्लान की गिनती होती है। गिनती में आती हैं वे कॉल जो आप किसी की से करते हैं। दो सीमाएँ एक साथ लागू होती हैं — दैनिक बजट और प्रति-मिनट बर्स्ट सीमा — और इनमें से किसी एक से भी आगे जाने पर 429 मिलता है।

आपका दैनिक बजट आपका है, किसी की का नहीं। आपके अकाउंट की हर REST की उसी एक दैनिक बजट से कटती है, इसलिए दूसरी की बनाने से ज़्यादा कॉल नहीं मिलतीं। MCP टूल कॉल अलग से गिनी जाती हैं: एक खर्च करने से दूसरी कभी कम नहीं होती।

जब Era किसी कॉल को मापता है, तो रिस्पॉन्स में X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset आते हैं। तीनों आपके दैनिक बजट की बात करते हैं, जो आधी रात को रीसेट नहीं होता बल्कि 24 घंटों में लगातार आगे खिसकता है: जैसे-जैसे आपकी सबसे पुरानी कॉल 24 घंटे पुरानी होती हैं, अनुरोध एक-एक करके वापस मिलते हैं। प्रति-मिनट बर्स्ट सीमा का कोई हेडर नहीं है, इसलिए टेबल के आँकड़े के हिसाब से अपनी रफ़्तार ख़ुद तय करें। Remaining शून्य से काफ़ी ऊपर हो सकता है, फिर भी कोई बर्स्ट 429 के साथ लौट सकता है। अगर Era आपका इस्तेमाल माप न पाए, तो वह कॉल पूरी कर देता है और कोई रेट-लिमिट हेडर नहीं भेजता, इसलिए हेडर न मिलें तो इसे त्रुटि नहीं, बल्कि छूटा हुआ माप समझें।

429 आपको क्या बताता है

एक problem-details बॉडी। इसका detail फ़ील्ड सादा टेक्स्ट है, स्ट्रक्चर्ड फ़ील्ड नहीं: यह बताता है कि आप किस सीमा से टकराए, वह सीमा कितना देती है, आपका अगला अनुरोध कब खाली होगा, और कौन सा प्लान इसे बढ़ाता है, या यह कि आप पहले से सबसे ऊँचे प्लान पर हैं। इसे पार्स न करें। कोड में ब्रांच करने के लिए हेडर पढ़ें: Remaining 0 हो तो दैनिक बजट ने मना किया, और 0 से ऊपर हो तो प्रति-मिनट बर्स्ट सीमा ने।

{
  "type": "https://httpstatuses.com/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You've used up your daily budget of 250 requests. Your next request frees up at 2026-09-16T09:00:00Z. The Organize plan raises it."
}

429 के साथ Retry-After भी आता है — सेकंड की एक पूरी संख्या, जो उस सीमा से मापी जाती है जिसने मना किया: प्रति-मिनट बर्स्ट सीमा के लिए एक मिनट तक, दैनिक बजट के लिए 24 घंटे तक। मना हुई कॉल कुछ ख़र्च नहीं करती, इसलिए जल्दी दोबारा कोशिश करने में कोई नुक़सान नहीं, पर वह फिर 429 के साथ लौटेगी। Retry-After पूरा होने पर एक अनुरोध खाली होता है, पूरा बजट नहीं। उसे भेजें, फिर हेडर या अगला Retry-After पढ़ें।

इनमें से कुछ भी उस की को नहीं बचाता जिसका आपको पता ही नहीं रहा। लीक हुई की आपका बजट ठीक वैसे ही खर्च करती है जैसे आप करते। किसी की को लेकर शक हो, तो उसे रद्द कर दें। नीचे सुरक्षा और की प्रबंधन देखें।

आम तौर-तरीक़े

रिस्पॉन्स के फ़ील्ड camelCase में होते हैं। क्वेरी पैरामीटर छोटे-बड़े अक्षर का फ़र्क़ नहीं देखते, इसलिए वहाँ भी camelCase चल जाता है — प्रकाशित स्पेक उन्हें PascalCase में लिखता है, इसीलिए आपको दोनों रूप दिखते हैं।

जो फ़ील्ड कैलेंडर का एक दिन बताता है, वह YYYY-MM-DD में होता है। जो फ़ील्ड एक पल बताता है, वह ऑफ़सेट के साथ ISO 8601 में होता है।

पेज का आकार ठुकराया नहीं जाता, बस सीमा तक काट दिया जाता है। pageSize में 500 माँगिए और आपको 100 पंक्तियाँ और एक 200 मिलेगा, कोई एरर नहीं — इसलिए जो भेजा उस पर भरोसा करने के बजाय pagination.pageSize वापस पढ़िए।

किसी रिस्पॉन्स में ऐसे फ़ील्ड आ सकते हैं जो इस पेज पर गिनाए नहीं गए। जिन्हें आप नहीं पहचानते, उन पर अटकने के बजाय उन्हें छोड़ दीजिए — यही वह बात है जो API के बढ़ते जाने पर भी आपके क्लाइंट को चलता रखती है।

REST सादा HTTP है, इसलिए इसे कॉल करने के लिए किसी SDK की ज़रूरत नहीं — HTTP क्लाइंट वाली कोई भी भाषा काफ़ी है। इंस्टॉल करने को कुछ नहीं है।

वर्ज़निंग और बदलाव

यहाँ जो कुछ दर्ज है, वह सब इस नीति के दायरे में है।

पाथ में वर्ज़न नंबर नहीं है और कोई वर्ज़न हेडर भी नहीं। हर एंडपॉइंट का एक ही वर्ज़न चालू रहता है, और वही है जो यहाँ दर्ज है।

जो हम बिना बताए बदल सकते हैं

इनमें से कोई भी ऊपर दी गई परिपाटियों का पालन करने वाले क्लाइंट को नहीं तोड़ता।

• कोई एंडपॉइंट जोड़ना, या पहले से मौजूद किसी पर कोई ऑपरेशन जोड़ना।

• रिस्पॉन्स में कोई फ़ील्ड जोड़ना।

• कोई वैकल्पिक पैरामीटर जोड़ना। न भेजें तो कुछ नहीं बदलता।

• तय विकल्पों में कोई मान जोड़ना, जैसे कोई स्टेटस या कोई क़िस्म।

• कोई रिस्पॉन्स हेडर जोड़ना।

जो हम बिना बताए नहीं बदलते

इनमें से कोई भी चलते हुए क्लाइंट को तोड़ सकता है।

• कोई एंडपॉइंट हटाना, या उसका पाथ या मेथड बदलना।

• रिस्पॉन्स का कोई फ़ील्ड हटाना या उसका नाम बदलना।

• किसी फ़ील्ड का टाइप या उसका मतलब बदलना।

• जो पैरामीटर आज वैकल्पिक है, उसे अनिवार्य बनाना।

• जो इनपुट आज स्वीकार होता है, उसे अस्वीकार करना।

• किसी एंडपॉइंट को जिस स्कोप की ज़रूरत है, उसे बदलना।

इनमें से कोई भी बदलाव करने से कम से कम 90 दिन पहले changelog में बताया जाता है और यह भी कि आपको क्या बदलना है। जो आज चलता है, वह तब तक चलता रहेगा।

बदलाव changelog में बताए जाते हैं, जिसका लिंक नीचे 'Changelog' सेक्शन में है। ईमेल या फ़ीड अभी नहीं है, इसलिए API पर काम की योजना बनाते समय वहाँ देख लीजिए।

जब तक API बीटा में है, दर्ज किया गया दायरा बढ़ता रहेगा। जो पहले से यहाँ है, वह बिना चेतावनी आपका काम नहीं तोड़ेगा।

Changelog

Era Developer Platform के अपडेट, जिनमें Era API शामिल है, सबसे नया पहले। ऊपर की नीति बताती है कि किस बात की चेतावनी मिलेगी और कितनी पहले; changelog वह जगह है जहाँ वे चेतावनियाँ दिखती हैं।

सुरक्षा और की प्रबंधन

अकाउंट

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

अकाउंट का बैलेंस

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

अकाउंट का सार

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

ट्रांज़ैक्शन

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

{
  "transaction": { … }
}

{
  "transactions": [ … ]
}

कैटेगरी

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

{
  "categoryKey": "fcat_side_hustle_9f2a",
  "overlayProjectionKey": "fcov_9f2a1c",
  "action": "created",
  "isQuotaExceeded": false,
  "createdMappingRuleKeys": [ … ],
  …
}

टैग

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

{
  "tag": {
    "tagKey": "utag_9c2f01ab",
    "name": "business-expense",
    "displayName": "Business expense",
    "tagType": "user",
    "version": 1,
    "createdAt": "2026-08-26T09:15:00Z"
  }
}