JSON API
हर Blume साइट द्वारा परोसा जाने वाला रीड-ओनली JSON API — पेज इंडेक्स, प्रति-पेज दस्तावेज़, नेविगेशन, खोज — और OpenAPI 3.1 विवरण जो फ़ंक्शन-कॉलिंग फ़्रेमवर्क को इससे टूल बनाने देता है।
हर Blume साइट अपने दस्तावेज़ों को एक छोटे रीड-ओनली JSON API के रूप में भी परोसती है — MCP सर्वर के टूल्स का REST जुड़वाँ, उसी पेज स्नैपशॉट पर, उन एजेंट्स और फ़ंक्शन-कॉलिंग फ़्रेमवर्क के लिए जो MCP के बजाय सादा HTTP बोलते हैं। यह डिफ़ॉल्ट रूप से चालू है और इसे किसी कॉन्फ़िगरेशन की आवश्यकता नहीं है:
| एंडपॉइंट | क्या लौटाता है |
|---|---|
/api/docs/pages.json |
हर पेज अपने रूट, शीर्षक, विवरण, कंटेंट टाइप, लोकेल, फ़ेसेट्स, और अपने रेंडर किए गए, Markdown तथा JSON रूपों के URL के साथ। |
/api/docs/pages/{route}.json |
एक पेज: उसकी इंडेक्स प्रविष्टि और साथ में एजेंट Markdown (वही बॉडी जो get_page लौटाता है)। {route} अग्रणी स्लैश के बिना पेज का रूट है, होम के लिए index। |
/api/docs/navigation.json |
नेविगेशन ट्री — हेडर टैब और साइडबार पदानुक्रम। |
/api/docs/search?q= |
पूर्ण-पाठ खोज, search_docs जैसी ही limit, contentTypes, locale, version, और filters[key] स्कोपिंग के साथ। केवल सर्वर आउटपुट। |
/openapi.json |
संपूर्ण मशीन-पठनीय सतह का OpenAPI 3.1 विवरण। |
पेज इंडेक्स, प्रति-पेज दस्तावेज़, और नेविगेशन प्रीरेंडर किए जाते हैं, इसलिए एक स्टैटिक साइट इन्हें किसी भी होस्ट से फ़ाइलों के रूप में परोसती है। खोज एक लाइव एंडपॉइंट है और केवल सर्वर आउटपुट के अंतर्गत मौजूद रहती है, जहाँ यह वही इंडेक्स चलाती है जो search_docs चलाता है।
त्रुटियाँ
त्रुटियाँ RFC 9457 प्रॉब्लम डिटेल्स (application/problem+json) होती हैं जिनमें एक स्थिर code, एक detail, और एक resolution संकेत होता है जो एजेंट को बताता है कि आगे कहाँ जाना है — एक अनुपस्थित पेज, एक खाली खोज क्वेरी, या सर्वर आउटपुट पर कोई भी ऐसा /api/… URL जिसका उत्तर कोई एंडपॉइंट नहीं देता:
{
"code": "API_ROUTE_NOT_FOUND",
"detail": "No API route exists at /api/nope.",
"instance": "/api/nope",
"links": [
{
"href": "https://docs.example.com/openapi.json",
"label": "OpenAPI description"
},
{
"href": "https://docs.example.com/api/docs/pages.json",
"label": "Page index"
}
],
"resolution": "Discover the available operations through the OpenAPI description at https://docs.example.com/openapi.json, or list every page at https://docs.example.com/api/docs/pages.json.",
"status": 404,
"title": "API route not found",
"type": "about:blank"
}OpenAPI विवरण
/openapi.json पर स्थित OpenAPI दस्तावेज़ आपके कॉन्फ़िग से प्रति बिल्ड जनरेट होता है, इसलिए यह केवल उसी का वर्णन करता है जो परिनियोजित साइट परोसती है: हर JSON एंडपॉइंट एक अद्वितीय operationId, टाइप किए गए पैरामीटर, और रिस्पॉन्स स्कीमा के साथ, साथ ही पाठ सतहें — .md मिरर, llms.txt और llms-full.txt, agent-readability.json — और सक्षम होने पर MCP एंडपॉइंट। जो फ़्रेमवर्क OpenAPI विवरण से टूल बनाते हैं, उन्हें वही पहुँच मिलती है जो एक MCP क्लाइंट के पास होती है। यह दस्तावेज़ API कैटलॉग, रीडेबिलिटी मेनिफ़ेस्ट, होमपेज के Link हेडर से rel="service-desc" के रूप में, और llms.txt से लिंक किया जाता है।
इसमें से कुछ भी आपके अपने API संदर्भ को नहीं छूता: एक प्रलेखित स्पेक पेजों में रेंडर किया जाता है, कभी /openapi.json पर नहीं परोसा जाता, और कैटलॉग दोनों को सूचीबद्ध करता है। आपके द्वारा स्वयं शिप किया गया public/openapi.json उस रूट को अपने अधिकार में ले लेता है (JSON एंडपॉइंट बने रहते हैं)। /api/… कैच-ऑल तब हट जाता है जब कोई दस्तावेज़ अनुभाग /api नेमस्पेस से परोसा जाता है (content/api/overview.md) या कोई कस्टम पेज /api/ के अंतर्गत किसी शेष रूट का स्वामी होता है, ताकि वे पेज जीतते रहें।
इसे बंद करना
इनमें से कुछ भी प्रकाशित न करने के लिए ai.api को false पर सेट करें:
ai: {
api: false,
}