API v1 रेफ़रेंस — डेवलपर्स के लिए Manilo

परिचय

Manilo API एक JSON REST API है, जिससे आप वही लेजर प्रोग्राम के ज़रिए सँभाल सकते हैं जो iOS ऐप में इस्तेमाल करते हैं — अकाउंट, कैटेगरी, बजट, शेयर्ड ग्रुप और ट्रांज़ैक्शन। इससे इंपोर्टर, एक्सपोर्टर, सिंक ब्रिज और डैशबोर्ड बनाएँ, या अपने ऑटोमेशन चलाएँ।

बेस URL: https://api.manilo.app — पुराना बेस URL api.ledgy.app भी काम करता रहेगा।
वर्ज़न प्रीफ़िक्स: इस दस्तावेज़ के सभी एंडपॉइंट /api/v1/ के अंतर्गत हैं।
ट्रांसपोर्ट: सिर्फ़ HTTPS। HTTP रिक्वेस्ट स्वीकार नहीं की जातीं।
एन्कोडिंग: JSON रिक्वेस्ट और रिस्पॉन्स बॉडी। UTF-8। प्रॉपर्टी के नाम camelCase में।
ऑथेंटिकेशन: Authorization: Bearer … — हर रिक्वेस्ट पर।
Cloud सब्सक्रिप्शन: हर v1 एंडपॉइंट पर ज़रूरी। देखें: सब्सक्रिप्शन गेट।

AI असिस्टेंट चाहिए? अगर आप चाहते हैं कि Claude, ChatGPT या Cursor आपकी ओर से Manilo से बात करें, तो https://api.manilo.app/mcp पर मौजूद Model Context Protocol एंडपॉइंट इस्तेमाल करें — देखें: इंटीग्रेशन। यहाँ जिस REST API का दस्तावेज़ है, वह उस कोड के लिए है जो आप खुद लिखते हैं।

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

अपनी पहली ऑथेंटिकेटेड रिक्वेस्ट तक तीन कदम।

1. Personal Access Token बनाएँ

अपने Manilo डैशबोर्ड में साइन इन करें और Settings → API Access खोलें।
अब + New token पर क्लिक करें।
टोकन को कोई साफ़ नाम दें (जैसे “Zapier — weekly export”), अपनी ज़रूरत के स्कोप चुनें (देखें: स्कोप), और चाहें तो समाप्ति तिथि तय कर दें।
टोकन कॉपी कर लें। यह सिर्फ़ एक बार दिखता है। टोकन lgpat_ प्रीफ़िक्स से शुरू होते हैं, जिसके बाद 64 hex कैरेक्टर आते हैं।

यही पेज आपके चालू टोकन की सूची दिखाता है — आखिरी बार इस्तेमाल का समय और अनुमतियों की गिनती के साथ — “30 दिन में समाप्त” की चेतावनी देता है, और ट्रैश आइकन से किसी भी टोकन को तुरंत रिवोक करने देता है। हर अकाउंट एक समय में 25 तक चालू टोकन रख सकता है।

2. रिक्वेस्ट भेजें

# Replace lgpat_… with your token
curl "https://api.manilo.app/api/v1/accounts" \
  -H "Authorization: Bearer lgpat_a1b2c3d4e5…"

3. रिस्पॉन्स देखें

{
  "items": [
    {
      "id": "acc_01HK8V…",
      "name": "Wise EUR",
      "currencyCode": "EUR",
      "initialBalance": 1240.50,
      "icon": "wallet",
      "color": "#4A90E2",
      "order": 0,
      "createdAt": "2026-04-12T08:13:09Z",
      "updatedAt": "2026-05-01T17:02:31Z"
    }
  ],
  "totalCount": 1
}

अपने टोकन को पासवर्ड की तरह सँभालें। टोकन रखने वाला कोई भी व्यक्ति आपके दिए स्कोप के भीतर आपका लेजर पढ़ या बदल सकता है। लीक हुए टोकन तुरंत Settings → API Access से रिवोक करें।

ऑथेंटिकेशन

पाथ /api/v1/ पर की गई हर रिक्वेस्ट में Authorization हेडर होना ज़रूरी है। दो तरह के टोकन स्वीकार किए जाते हैं:

Personal Access Token (PAT) — लंबे समय तक चलने वाला bearer टोकन, जिसे आप डैशबोर्ड के Settings → API Access पेज से बनाते हैं। फ़ॉर्मैट: lgpat_ + 64 hex कैरेक्टर। स्कोप वाला, रिवोक करने लायक, और चाहें तो समाप्ति तिथि वाला। सभी थर्ड-पार्टी इंटीग्रेशन के लिए यही सुझाया जाता है।
Session JWT — पहले-पक्ष के ऐप्स (iOS, डैशबोर्ड) को जारी किया गया अल्पकालिक टोकन। इस पर कोई स्कोप पाबंदी नहीं होती। अगर आप किसी साइन-इन सेशन से एक टोकन निकाल सकें, तो इसे एक बार की टेस्टिंग के लिए इस्तेमाल कर सकते हैं, लेकिन समर्थित रास्ता PAT ही है।

हेडर का फ़ॉर्मैट

Authorization: Bearer lgpat_a1b2c3d4e5f6…

टोकन की सीमाएँ

हर Manilo अकाउंट पर ज़्यादा से ज़्यादा 25 चालू PAT रखे जा सकते हैं।
बनाते समय वैकल्पिक समाप्ति तिथि तय की जा सकती है। समाप्त हो चुके टोकन 401 Unauthorized लौटाते हैं।
रिवोक किए गए टोकन तुरंत काम करना बंद कर देते हैं — Manilo टोकन का सिर्फ़ SHA-256 हैश रखता है, उसका मान कभी नहीं, इसलिए लीक हुआ टोकन वापस पाया नहीं जा सकता, सिर्फ़ रिवोक करके बदला जा सकता है।

ऑथ की आम नाकामियाँ

401: टोकन गायब, गलत बना हुआ, समाप्त या रिवोक किया हुआ है।
403: टोकन सही है, पर माँगे गए एंडपॉइंट को ऐसा स्कोप चाहिए जो आपके PAT के पास नहीं है, या आपका Cloud सब्सक्रिप्शन चालू नहीं है।

स्कोप

PAT deny-by-default मॉडल पर चलते हैं। कोई टोकन सिर्फ़ वही एंडपॉइंट कॉल कर सकता है जिनका ज़रूरी स्कोप उसके पास हो; बाकी सब पर 403 Forbidden मिलता है। आपके इंटीग्रेशन को जितने स्कोप वाकई चाहिए, बस उतने ही दें।

उपलब्ध स्कोप:

accounts:read accounts:write categories:read categories:write budgets:read budgets:write groups:read groups:write transactions:read transactions:write tags:read tags:write recurring:read recurring:write settings:read settings:write

नीचे दिया हर एंडपॉइंट अपना ज़रूरी स्कोप एक छोटी बैंगनी चिप में दिखाता है। :write स्कोप का मतलब :read नहीं होता — दोनों चाहिए तो दोनों माँगें।

सब्सक्रिप्शन गेट

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

HTTP/1.1 403 Forbidden
X-Subscription-Required: true
Content-Type: application/json

{ "error": "Active cloud subscription required" }

इस जवाब का X-Subscription-Required हेडर क्लाइंट को यह पहचानने देता है कि रुकावट सब्सक्रिप्शन की वजह से है या आम अनुमति की। एक्सेस वापस पाने के लिए iOS ऐप में या dashboard.manilo.app/upgrade पर Cloud दोबारा चालू करें।

एरर

एरर मानक HTTP स्टेटस कोड इस्तेमाल करते हैं। रिस्पॉन्स बॉडी एक ही फ़ील्ड वाला JSON ऑब्जेक्ट होती है:

{ "error": "Human-readable message" }

जिन स्टेटस कोड को आपको सँभालना चाहिए:

200: OK — रिसोर्स लौटाया गया, या सूची लौटाई गई।
201: Created — नया रिसोर्स बन गया। Location हेडर कैनोनिकल URL बताता है।
204: No Content — डिलीट सफल; कोई बॉडी नहीं।
400: वैलिडेशन नाकाम — ज़रूरी फ़ील्ड गायब, मान सीमा से बाहर, या गलत बनी JSON।
401: ऑथेंटिकेशन नाकाम — देखें: ऑथेंटिकेशन।
403: अनुमति नहीं — स्कोप अधूरा है या सब्सक्रिप्शन चालू नहीं है।
404: रिसोर्स नहीं मिला, या अनुमति के पीछे छिपा है।
409: टकराव — जैसे यूनीक कंस्ट्रेंट का उल्लंघन।
5xx: सर्वर की तरफ़ नाकामी। आइडेमपोटेंट रीड को एक्सपोनेंशियल बैकऑफ़ के साथ दोबारा भेजना सुरक्षित है।

पेजिनेशन और फ़िल्टर

लिस्ट एंडपॉइंट डिफ़ॉल्ट रूप से सारे मेल खाते आइटम लौटाते हैं। ट्रांज़ैक्शन ही इकलौता ऐसा रिसोर्स है जो बहुत बड़ा हो सकता है, इसलिए उसमें कर्सर-आधारित पेजिनेशन मिलता है।

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

curl "https://api.manilo.app/api/v1/transactions?limit=50&type=expense&dateFrom=2026-01-01" \
  -H "Authorization: Bearer lgpat_…"

रिस्पॉन्स में एक nextCursor होता है। अगला पेज लाने के लिए उसे cursor क्वेरी पैरामीटर के रूप में वापस भेजें; जब nextCursor का मान null हो, तो समझें कि सूची खत्म हो गई।

limit — पेज का साइज़, सीमा 1..200। डिफ़ॉल्ट 50।
cursor — अपारदर्शी टोकन। इसे ब्लैक बॉक्स की तरह मानें।
type, dateFrom, dateTo, categoryId, accountId, groupId — वैकल्पिक फ़िल्टर; देखें ट्रांज़ैक्शन की सूची एंडपॉइंट।

टाइप और फ़ॉर्मैट

ID — अपारदर्शी स्ट्रिंग। इन्हें पार्स न करें; इन्हें केस-सेंसिटिव UTF-8 पहचानकर्ता मानें।
टाइमस्टैंप — UTC में ISO-8601, आखिर में Z के साथ, जैसे "2026-05-13T10:30:00Z"।
तारीख (जैसे ट्रांज़ैक्शन का date) — वही ISO-8601 रूप, पर सिर्फ़ तारीख वाला हिस्सा मायने रखता है।
रकम — JSON नंबर, मुख्य इकाई में, 4 दशमलव स्थानों तक (जैसे 12.50)। कभी छोटी इकाई में नहीं। हमेशा currencyCode के साथ।
करेंसी कोड — ISO-4217, ठीक तीन बड़े अक्षर (जैसे "EUR", "USD", "GBP")।
डिलीट — सभी डिलीट ऑपरेशन सॉफ़्ट डिलीट होते हैं। डिलीट की गई चीज़ें list/get रिस्पॉन्स में दिखना बंद हो जाती हैं; शेयरिंग पार्टनर और पुरानी रसीदें बनी रहती हैं।
साइड इफ़ेक्ट — कोई अकाउंट, कैटेगरी या ग्रुप डिलीट करने पर उससे जुड़े ट्रांज़ैक्शन बने रहते हैं; बस उनके रेफ़रेंस हट जाते हैं। अकाउंट डिलीट करें एंडपॉइंट में साफ़ तौर पर रणनीति दी जा सकती है।

अकाउंट

अकाउंट वे बकेट हैं जिनमें बैलेंस रहता है — बैंक अकाउंट, क्रेडिट कार्ड, नकद वॉलेट, ब्रोकरेज। हर ट्रांज़ैक्शन किसी एक से जुड़ा होता है (ट्रांसफ़र में दो से)।

GET /api/v1/accounts accounts:read

उन सभी अकाउंट को लौटाता है, जिनका मालिक ऑथेंटिकेटेड यूज़र है या जिन तक उसकी पहुँच है।

GET /api/v1/accounts/{id} accounts:read

id से एक अकाउंट लाता है। न मिलने पर 404।

POST /api/v1/accounts accounts:write

नया अकाउंट बनाता है। 201 के साथ बना हुआ ऑब्जेक्ट और Location हेडर लौटाता है।

रिक्वेस्ट बॉडी

फ़ील्ड	टाइप	विवरण
name	string	ज़रूरीदिखने वाला नाम। ज़्यादा से ज़्यादा 100 कैरेक्टर।
currencyCode	string	ज़रूरीISO-4217। ठीक 3 अक्षर।
initialBalance	number	ज़रूरीशुरुआती बैलेंस, `currencyCode` में।
order	integer	ज़रूरीक्रम में जगह। छोटा नंबर पहले आता है।
icon	string	वैकल्पिकआइकन पहचानकर्ता, /api/v1/icons से। ज़्यादा से ज़्यादा 50।
color	string	वैकल्पिकहेक्स रंग, जैसे `"#4A90E2"`। ज़्यादा से ज़्यादा 20।
iconColor	string	वैकल्पिकआइकन का रंग बदल दें।

POST /api/v1/accounts
{
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E"
}

{
  "id": "acc_01HK8V…",
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E",
  "iconColor": null,
  "shareInviteToken": null,
  "createdAt": "2026-05-13T10:30:00Z",
  "updatedAt": "2026-05-13T10:30:00Z"
}

PUT /api/v1/accounts/{id} accounts:write

मौजूदा अकाउंट को बदल देता है। बॉडी Create जैसी ही है; सभी फ़ील्ड देने ज़रूरी हैं।

DELETE /api/v1/accounts/{id} accounts:write

अकाउंट को सॉफ़्ट-डिलीट करता है। उसके ट्रांज़ैक्शन का क्या हो, यह action क्वेरी पैरामीटर से तय करें।

क्वेरी पैरामीटर

फ़ील्ड	टाइप	विवरण
action	enum	वैकल्पिक`Detach` (डिफ़ॉल्ट): हर ट्रांज़ैक्शन से अकाउंट का रेफ़रेंस हटा देता है। `Move`: ट्रांज़ैक्शन को `moveTargetAccountId` पर भेज देता है। `DeleteAll`: आपके अपने सभी जुड़े ट्रांज़ैक्शन सॉफ़्ट-डिलीट कर देता है।
moveTargetAccountId	string	वैकल्पिकतब ज़रूरी, जब `action=Move` हो। जिस अकाउंट में भेजना है, उसकी id।

कैटेगरी

कैटेगरी बताती है कि ट्रांज़ैक्शन किस लिए है (किराना, किराया, फ़्रीलांस आमदनी)। सिस्टम कैटेगरी सिर्फ़ पढ़ने के लिए होती हैं और सभी यूज़र्स के लिए एक जैसी होती हैं; यूज़र कैटेगरी आपकी अपनी होती हैं, जिन्हें आप सँभालते हैं। कैटेगरी ग्रुप आपस में जुड़ी कैटेगरी को एक साथ बाँधते हैं।

GET /api/v1/categories/system-categories categories:read

Manilo का चुना हुआ “well-known” कैटेगरी सेट लौटाता है — वही शुरुआती सेट, जो iOS ऐप के साथ आता है। ये विश्व-स्तर पर वर्ज़न किए जाते हैं, इसलिए version के आधार पर इन्हें कैश करना सुरक्षित है।

यूज़र कैटेगरी

GET /api/v1/categories categories:read

सभी यूज़र-निर्धारित कैटेगरी की सूची देता है।

GET /api/v1/categories/{id} categories:read

id से एक यूज़र कैटेगरी लाता है।

POST /api/v1/categories categories:write

यूज़र कैटेगरी बनाता है।

रिक्वेस्ट बॉडी

फ़ील्ड	टाइप	विवरण
name	string	ज़रूरीदिखने वाला नाम। ज़्यादा से ज़्यादा 100।
type	string	ज़रूरी`"income"` या `"expense"`।
order	integer	ज़रूरीअपने ग्रुप के भीतर क्रम में जगह।
isPinned	boolean	ज़रूरीपिकर में सबसे ऊपर पिन करें।
categoryGroupId	string	वैकल्पिकपैरेंट ग्रुप की id, या बिना ग्रुप वाली कैटेगरी के लिए `null`।
icon	string	वैकल्पिकआइकन पहचानकर्ता।
color	string	वैकल्पिकहेक्स रंग।

PUT /api/v1/categories/{id} categories:write

यूज़र कैटेगरी को बदल देता है। बॉडी Create जैसी ही है।

DELETE /api/v1/categories/{id} categories:write

यूज़र कैटेगरी को सॉफ़्ट-डिलीट करता है। ट्रांज़ैक्शन डिलीट नहीं होते; बस उनका categoryId खाली कर दिया जाता है।

कैटेगरी ग्रुप

GET /api/v1/categories/groups categories:read

आपके कैटेगरी ग्रुप की सूची देता है।

GET /api/v1/categories/groups/{id} categories:read

एक कैटेगरी ग्रुप लाता है।

POST /api/v1/categories/groups categories:write

कैटेगरी ग्रुप बनाता है।

रिक्वेस्ट बॉडी

फ़ील्ड	टाइप	विवरण
name	string	ज़रूरीदिखने वाला नाम। ज़्यादा से ज़्यादा 100।
order	integer	ज़रूरीक्रम में जगह।
icon	string	वैकल्पिकआइकन पहचानकर्ता।
color	string	वैकल्पिकहेक्स रंग।

PUT /api/v1/categories/groups/{id} categories:write

कैटेगरी ग्रुप को बदल देता है।

DELETE /api/v1/categories/groups/{id} categories:write

ग्रुप को सॉफ़्ट-डिलीट करता है। उसकी चाइल्ड कैटेगरी बनी रहती हैं — बस उनका categoryGroupId खाली कर दिया जाता है।

बजट

बजट किसी कैटेगरी पर (या जब categoryId null हो, तो पूरे लेजर पर) एक दोहराई जाने वाली अवधि में खर्च की सीमा तय करता है। groupId सेट करके बजट किसी ग्रुप के साथ शेयर करें।

GET /api/v1/budgets budgets:read

सभी बजट की सूची देता है।

GET /api/v1/budgets/{id} budgets:read

एक बजट लाता है।

POST /api/v1/budgets budgets:write

बजट बनाता है।

रिक्वेस्ट बॉडी

फ़ील्ड	टाइप	विवरण
amount	number	ज़रूरीहर अवधि की सीमा। 0 से बड़ी होनी चाहिए।
currencyCode	string	ज़रूरीISO-4217।
period	integer	ज़रूरी`0` साप्ताहिक · `1` मासिक · `2` तिमाही · `3` सालाना।
startDate	string (ISO-8601)	ज़रूरीपहली अवधि की शुरुआत।
isActive	boolean	ज़रूरीयह बजट अभी लागू है या नहीं।
endDate	string (ISO-8601)	वैकल्पिकइस तारीख के बाद ट्रैक करना बंद कर दें।
name	string	वैकल्पिकलेबल। ज़्यादा से ज़्यादा 200।
categoryId	string	वैकल्पिकजिस कैटेगरी को ट्रैक करना है। पूरे खर्च का बजट बनाना हो तो छोड़ दें।
groupId	string	वैकल्पिकजिस ग्रुप के साथ शेयर करना है। निजी बजट के लिए छोड़ दें।

PUT /api/v1/budgets/{id} budgets:write

बजट को बदल देता है।

DELETE /api/v1/budgets/{id} budgets:write

बजट को सॉफ़्ट-डिलीट करता है।

ग्रुप

ग्रुप शेयर्ड लेजर होते हैं — एक घर, एक ट्रिप, एक साझा अपार्टमेंट। हर मेंबर को वही ट्रांज़ैक्शन दिखते हैं; मालिकाना हक निजी ही रहता है। मेंबरशिप और इनवाइट iOS ऐप में सँभाले जाते हैं; यहाँ API सिर्फ़ रिसोर्स ही देता है।

GET /api/v1/groups groups:read

उन ग्रुप की सूची देता है, जिनके आप मालिक या मेंबर हैं।

GET /api/v1/groups/{id} groups:read

एक ग्रुप लाता है।

POST /api/v1/groups groups:write

ग्रुप बनाता है। आप उसके मालिक बन जाते हैं; मेंबर iOS ऐप से जोड़ें।

रिक्वेस्ट बॉडी

फ़ील्ड	टाइप	विवरण
name	string	ज़रूरीदिखने वाला नाम। ज़्यादा से ज़्यादा 100।
description	string	वैकल्पिकमुक्त टेक्स्ट। ज़्यादा से ज़्यादा 500।
icon	string	वैकल्पिकआइकन पहचानकर्ता।
color	string	वैकल्पिकहेक्स रंग।

PUT /api/v1/groups/{id} groups:write

ग्रुप का मेटाडेटा बदल देता है।

DELETE /api/v1/groups/{id} groups:write

ग्रुप को सॉफ़्ट-डिलीट करता है। मेंबर की विज़िबिलिटी खत्म हो जाती है; अंदर के ट्रांज़ैक्शन निजी हो जाते हैं।

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

ट्रांज़ैक्शन लेजर की क्रियाएँ हैं। ये चार रूपों में आते हैं: income, expense, transfer (अकाउंट से अकाउंट), और adjustment (एक बार का बैलेंस सुधार)। बेस एंडपॉइंट income/expense बनाता है; ट्रांसफ़र का अपना अलग एंडपॉइंट है; बड़ी मात्रा में इंपोर्ट करने वालों के लिए बल्क वर्ज़न मौजूद हैं।

GET /api/v1/transactions transactions:read

कर्सर पेजिनेशन और फ़िल्टर के साथ ट्रांज़ैक्शन की सूची देता है।

क्वेरी पैरामीटर

फ़ील्ड	टाइप	विवरण
limit	integer	वैकल्पिकपेज का साइज़। `1..200`। डिफ़ॉल्ट `50`।
cursor	string	वैकल्पिकपिछले रिस्पॉन्स से मिला अपारदर्शी कंटिन्युएशन टोकन।
type	string	वैकल्पिक`"income"`, `"expense"`, `"transfer"`, या `"adjustment"`।
dateFrom	string (ISO-8601)	वैकल्पिकनिचली सीमा, इसे भी शामिल करते हुए।
dateTo	string (ISO-8601)	वैकल्पिकऊपरी सीमा, इसे भी शामिल करते हुए।
categoryId	string	वैकल्पिकसिर्फ़ एक कैटेगरी तक सीमित करें।
accountId	string	वैकल्पिकसिर्फ़ एक अकाउंट तक सीमित करें।
groupId	string	वैकल्पिककिसी शेयर्ड ग्रुप तक सीमित करें।

{
  "items": [ /* TransactionDto[] */ ],
  "totalCount": 317,
  "nextCursor": "eyJrIjoiMjAyNi0wNS0xM1QxMDoz…"
}

GET /api/v1/transactions/{id} transactions:read

एक ट्रांज़ैक्शन लाता है।

POST /api/v1/transactions transactions:write

एक income या expense ट्रांज़ैक्शन बनाता है। ट्रांसफ़र के लिए /transfer इस्तेमाल करें।

रिक्वेस्ट बॉडी

फ़ील्ड	टाइप	विवरण
type	string	ज़रूरी`"income"` या `"expense"`।
amount	number	ज़रूरीधनात्मक रकम, `currencyCode` में।
currencyCode	string	ज़रूरीISO-4217।
date	string (ISO-8601)	ज़रूरीट्रांज़ैक्शन कब हुआ (UTC)।
accountId	string	वैकल्पिकस्रोत/गंतव्य अकाउंट।
categoryId	string	वैकल्पिककैटेगरी लेबल।
payee	string	वैकल्पिकमर्चेंट या दूसरा पक्ष। ज़्यादा से ज़्यादा 200।
note	string	वैकल्पिकमुक्त नोट। ज़्यादा से ज़्यादा 2000।
groupId	string	वैकल्पिककिसी ग्रुप के साथ शेयर करें।
exchangeRate	number	वैकल्पिकFX रेट, जब `currencyCode` ≠ यूज़र की मुख्य करेंसी हो।
convertedAmount	number	वैकल्पिकयूज़र की मुख्य करेंसी में रकम।

POST /api/v1/transactions
{
  "type": "expense",
  "amount": 8.50,
  "currencyCode": "EUR",
  "date": "2026-05-12T09:14:00Z",
  "accountId": "acc_01HK8V…",
  "categoryId": "cat_food_drinks",
  "payee": "Pret",
  "note": "Flat white"
}

PUT /api/v1/transactions/{id} transactions:write

ट्रांज़ैक्शन को बदल देता है। बॉडी Create जैसी ही है।

DELETE /api/v1/transactions/{id} transactions:write

एक ट्रांज़ैक्शन को सॉफ़्ट-डिलीट करता है।

POST /api/v1/transactions/transfer transactions:write

दो अकाउंट के बीच ट्रांसफ़र बनाता है। कोई कैटेगरी नहीं। अलग-अलग करेंसी वाले ट्रांसफ़र के लिए exchangeRate और गंतव्य करेंसी में convertedAmount दें।

रिक्वेस्ट बॉडी

फ़ील्ड	टाइप	विवरण
fromAccountId	string	ज़रूरीस्रोत अकाउंट।
toAccountId	string	ज़रूरीगंतव्य अकाउंट। स्रोत से अलग होना चाहिए।
amount	number	ज़रूरीभेजी गई रकम, `currencyCode` में।
currencyCode	string	ज़रूरीस्रोत करेंसी, ISO-4217।
date	string (ISO-8601)	ज़रूरीट्रांसफ़र की तारीख।
exchangeRate	number	वैकल्पिकतब ज़रूरी, जब स्रोत और गंतव्य की करेंसी अलग हों।
convertedAmount	number	वैकल्पिकगंतव्य में जमा हुई रकम, उसी की करेंसी में।
note	string	वैकल्पिकज़्यादा से ज़्यादा 2000।

बल्क ऑपरेशन

इंपोर्टर के लिए बनाया गया। हर बैच की सीमा 100 आइटम है और यह best-effort चलता है: एक खराब पंक्ति बाकी को रोलबैक नहीं करती। सफल आइटम और हर पंक्ति की गलतियाँ अलग-अलग बताई जाती हैं, ताकि आप नाकाम पंक्तियाँ दोबारा भेज सकें।

POST /api/v1/transactions/bulk transactions:write

एक ही कॉल में 100 तक ट्रांज़ैक्शन बनाता है।

{
  "items": [ /* successful TransactionDto[] */ ],
  "errors": [
    { "index": 3, "error": "Invalid currency code" }
  ]
}

PUT /api/v1/transactions/bulk transactions:write

एक ही कॉल में 100 तक ट्रांज़ैक्शन अपडेट करता है। हर आइटम में पूरी ट्रांज़ैक्शन बॉडी के साथ उसकी id भी होनी चाहिए।

POST /api/v1/transactions/bulk-delete transactions:write

एक ही कॉल में 100 तक ट्रांज़ैक्शन सॉफ़्ट-डिलीट करता है। यह POST का इस्तेमाल करता है, DELETE का नहीं, ताकि रिक्वेस्ट बॉडी सभी HTTP क्लाइंट स्वीकार करें।

रिक्वेस्ट बॉडी

फ़ील्ड	टाइप	विवरण
ids	string[]	ज़रूरी1 से 100 तक ट्रांज़ैक्शन id।

{
  "deleted": 97,
  "notFound": [ "tx_old1", "tx_old2", "tx_old3" ]
}

ट्रांज़ैक्शन ऑब्जेक्ट

फ़ील्ड	टाइप	विवरण
id	string	अपारदर्शी पहचानकर्ता।
type	string	`income` · `expense` · `transfer` · `adjustment`.
amount	number	रकम, `currencyCode` में।
currencyCode	string	ISO-4217।
exchangeRate	number \| null	अलग-अलग करेंसी वाली एंट्री पर सेट होता है।
convertedAmount	number \| null	यूज़र की मुख्य करेंसी में वही मान।
date	string	ISO-8601 UTC।
accountId	string \| null	ट्रांसफ़र में यह स्रोत अकाउंट होता है।
toAccountId	string \| null	सिर्फ़ ट्रांसफ़र में गंतव्य अकाउंट।
categoryId	string \| null	ट्रांसफ़र पर null होता है।
groupId	string \| null	किसी ग्रुप के साथ शेयर होने पर सेट होता है।
payee	string \| null	मर्चेंट या दूसरा पक्ष।
note	string \| null	मुक्त टेक्स्ट।
receiptImagePath	string \| null	जुड़ी रसीद का पाथ। रसीद एंडपॉइंट से लाएँ (v1 से अलग)।
recurringTransactionId	string \| null	अगर यह पंक्ति किसी रेकरिंग नियम से बनी है, तो सेट होता है।
source	string	स्रोत टैग — `api`, `mobile`, `web`, `import`, वगैरह।
createdAt	string	ISO-8601 UTC।
updatedAt	string	ISO-8601 UTC।

आइकन

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

GET /api/v1/icons

पूरी आइकन लाइब्रेरी लौटाता है, कैटेगरी में बँटी हुई, साथ में समर्थित कलर पैलेट भी। यह वर्ज़न वाली है — version फ़ील्ड के आधार पर कैश करना सुरक्षित है।

{
  "version": "2026.05.10",
  "library": "font-awesome-6",
  "categories": [
    {
      "id": "finance",
      "name": "Finance",
      "icons": [ "wallet", "credit-card", "piggy-bank" ]
    }
  ],
  "colors": [
    { "name": "Blue", "hex": "#4A90E2" },
    { "name": "Green", "hex": "#22C55E" }
  ]
}

वर्ज़निंग

v1 के भीतर कोई ब्रेकिंग बदलाव नहीं। हम सिर्फ़ नए एंडपॉइंट, नई वैकल्पिक फ़ील्ड और नए enum मान जोड़ेंगे। किसी फ़ील्ड का टाइप, nullability या ज़रूरी होना नहीं बदलेगा।
नए enum मान ब्रेकिंग नहीं हैं। अनजाने type, source, या action मानों को क्रैश करने के बजाय “रेंडर न करें” की तरह लें — प्रोडक्ट बढ़ने पर हम इन्हें जोड़ते रहेंगे।
तारीख से चिह्नित ब्रेकिंग बदलाव (अगर कभी ज़रूरत पड़ी) /api/v2/ के तहत आएँगे — कम से कम 6 महीने तक साथ-साथ उपलब्धता और v1 के रिस्पॉन्स पर deprecation हेडर के साथ।

सपोर्ट

कोई बग मिला, कोई एंडपॉइंट चाहिए, या कुछ ऐसा दिखा जो दस्तावेज़ में नहीं है? हेल्प सेंटर खोलें या support@manilo.app पर ईमेल करें — दिक्कत बताते समय कृपया request id ज़रूर दें (जो X-Request-Id रिस्पॉन्स हेडर में लौटती है)।

सुरक्षा से जुड़ी संवेदनशील जानकारी (टोकन लीक, अनुमति बायपास, बिना अनुमति पढ़ा जाना) के लिए security@manilo.app पर लिखें।