API और MCP दस्तावेज़

पहली कॉल करें

API HTTPS पर JSON का उपयोग करता है। यह कॉल Apple के पिछले पाँच वार्षिक आय विवरण लौटाती है। इसके लिए किसी कुंजी की आवश्यकता नहीं है।

curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"

विवरण income_statement, balance_sheet, cash_flow या supplemental में से एक होता है। अवधि का प्रकार annual, quarterly, ltm या ytd में से एक होता है।

कंपनी निर्दिष्ट करें

हर कंपनी रूट एक company पैरामीटर लेता है।

• ticker:AAPL, या एक्सचेंज निर्दिष्ट करने के लिए ticker:AAPL.XNAS
• cik:320193, SEC की कंपनी संख्या
• fmd_<id>, वह आईडी जो FinancialMD कंपनी को देता है

बिना किसी उपसर्ग वाला AAPL टिकर के रूप में और केवल अंक CIK के रूप में पढ़े जाते हैं। प्रतिक्रिया में meta.company.matched_by बताता है कि किस आधार पर मिलान हुआ।

मान पढ़ें

सफल प्रतिक्रिया { data, meta } होती है। data के भीतर कोई संख्या कभी अकेली नहीं होती। वह एक वैल्यू ऑब्जेक्ट होती है:

{
  "value": 391035000000,
  "unit": "USD",
  "currency": "USD",
  "decimals": -6,
  "period": { "start": "2023-10-01", "end": "2024-09-28", "type": "annual", "fiscal_year": 2024, "fiscal_period": "FY" },
  "known": { "from": "YYYY-MM-DDThh:mm:ssZ", "to": null },
  "restated": false,
  "method": "as_filed",
  "calc_type": "as_filed",
  "proof": { "id": "p_...", "accession": "0000320193-24-000123", "form": "10-K", "filed": "2024-11-01", "taxonomy": "us-gaap", "tag": "...", "source_url": "https://www.sec.gov/..." }
}

known वह समयावधि है जिसमें यह फाइलिंग में दर्ज सबसे हालिया आँकड़ा था। restated केवल तभी true होता है जब बाद की फाइलिंग ने आँकड़ा बदला हो; तब restatement_kind बताता है कि कैसे। proof.id को GET /proof/{id} पर खोलने से उस मान की फाइलिंग और उसके पीछे के मूल तथ्य मिलते हैं।

अतीत को उस समय ज्ञात रूप में पढ़ें

• किसी भी रीड रूट पर as_of=2024-06-30 उस क्षण ज्ञात जानकारी लौटाता है।
• original=true हर अवधि का पहली बार रिपोर्ट किया गया संस्करण लौटाता है।
• history=true हर अवधि के सभी संस्करण लौटाता है, सबसे पुराना पहले।
• GET /v1/changes?since=<timestamp> उस समय के बाद ज्ञात हुए तथ्यों की सूची देता है।

रूट

OpenAPI दस्तावेज़ में हर पैरामीटर और रिस्पॉन्स स्कीमा है। llms.txt, llms-full.txt और स्किल फ़ाइल एजेंटों के लिए यही जानकारी देते हैं; https://api.financial.md/docs इंटरैक्टिव संदर्भ है और https://api.financial.md/changelog बदलावों की सूची देता है।

किसी संख्या की जाँच करें

curl -X POST "https://api.financial.md/v1/verify" -H "content-type: application/json" \
  -d '{"company":"ticker:AAPL","concept":"income_statement_total_revenues","period":"FY2024","value":391035000000}'

उत्तर में matches, differs या unknown वाला verdict, फाइलिंग में दर्ज मान उसके प्रमाण के साथ, अंतर, और आपकी संख्या दस की किसी घात के गुणक से गलत होने पर scale_hint होता है।

सीमाएँ

बिना कुंजी वाली कॉल की सीमा प्रति IP पते, प्रति दिन तय है।

• 25 मीटर की गई कॉल: अनुपात, स्क्रीनिंग और सत्यापन
• 1,000 फाइलिंग-स्तर रीड: विवरण, रिपोर्ट किए गए मूल तथ्य, फाइलिंग, स्वामित्व और कीमतें
• 1,000 मेटाडेटा रीड: निर्देशिका, प्रोफ़ाइल, मेट्रिक्स, प्रमाण और बदलाव

हर रिस्पॉन्स में RateLimit-Limit, RateLimit-Remaining और RateLimit-Reset होते हैं। 429 में Retry-After होता है।

अधिक सीमा वाली API कुंजियाँ अभी जारी नहीं की जातीं। देखें API कुंजियाँ। api.financial.md पर कॉल निःशुल्क हैं। एजेंट agent.financial.md पर प्रति कॉल भुगतान कर सकते हैं। देखें मूल्य निर्धारण।

कवरेज में क्या शामिल है

कवरेज में वे कंपनियाँ शामिल हैं जो SEC में फाइलिंग करती हैं और आज किसी अमेरिकी एक्सचेंज पर सूचीबद्ध हैं।

• US GAAP के तहत रिपोर्ट करने वाले फाइलिंगकर्ताओं के लिए मानकीकृत वित्तीय विवरण उपलब्ध हैं।
• IFRS के तहत रिपोर्ट करने वाले फाइलिंगकर्ताओं, जैसे Form 20-F या 40-F दाखिल करने वाली कई विदेशी कंपनियों, की फाइलिंग उपलब्ध हैं, लेकिन अभी मानकीकृत वित्तीय विवरण नहीं हैं।
• डीलिस्ट की गई कंपनियाँ अपने वित्तीय विवरणों और फाइलिंग के साथ निर्देशिका में हैं। उन्हें CIK से खोजें: उनके लिए टिकर से खोज और कीमतें उपलब्ध नहीं हैं, इसलिए मूल्य इतिहास में केवल आज सूचीबद्ध कंपनियाँ शामिल हैं।
• स्वामित्व डेटा July 1, 2026 से की गई फाइलिंग से आता है और EDGAR के दैनिक सूचकांक से हर दिन 13:00 UTC पर अपडेट होता है: कवरेज में शामिल कंपनियों के Forms 3, 4 and 5 से इनसाइडर लेनदेन, और हर Form 13F-HR, इसलिए नई तिमाही की 13F रिपोर्टें प्रबंधकों द्वारा दाखिल किए जाने पर आती हैं। किसी 13F पोज़िशन को कंपनी से तभी जोड़ा जाता है जब Schedule 13D या 13G के कवर पृष्ठ पर उसकी प्रतिभूति का नाम हो। June 30, 2026 को समाप्त तिमाही के लिए इससे रिपोर्ट किए गए मूल्य का 80 प्रतिशत जुड़ता है; अन्य पोज़िशन प्रबंधक के पोर्टफोलियो में जारीकर्ता के नाम के तहत दिखाई देती हैं, जैसा फाइलिंग में दर्ज है।
• सर्वसम्मत अनुमान और अर्निंग्स कॉल के प्रतिलेख उपलब्ध नहीं कराए जाते: दोनों लाइसेंस प्राप्त डेटा हैं। सेगमेंट रिपोर्ट किए गए रूप में उपलब्ध कराए जाते हैं, और समाचार 8-K फाइलिंग की फ़ीड है।

जब कोई कंपनी ज्ञात हो लेकिन कोई डेटासेट उपलब्ध न हो, तो API not_covered उत्तर देता है और अपने पास उपलब्ध डेटासेट की सूची देता है।

MCP सर्वर

MCP सर्वर उसी API को 50 केवल-पढ़ने वाले टूल के रूप में उपलब्ध कराता है। यह MCP Streamable HTTP का उपयोग करता है और इसके लिए खाते की ज़रूरत नहीं है।

https://mcp.financial.md/mcp

MCP गाइड में टूल की सूची है। सर्वर कार्ड रजिस्ट्रियों के लिए है।

त्रुटियाँ

त्रुटि का स्वरूप { "error": { code, message, docs, request_id, remedies } } है। remedies सूची बताती है कि आगे क्या करना है। त्रुटि संदर्भ में हर कोड का विवरण है।