JSON API

हर Blume साइट द्वारा परोसा जाने वाला रीड-ओनली JSON API — पेज इंडेक्स, प्रति-पेज दस्तावेज़, नेविगेशन, खोज — और OpenAPI 3.1 विवरण जो फ़ंक्शन-कॉलिंग फ़्रेमवर्क को इससे टूल बनाने देता है।

हर Blume साइट अपने दस्तावेज़ों को एक छोटे रीड-ओनली JSON API के रूप में भी परोसती है — MCP सर्वर के टूल्स का REST जुड़वाँ, उसी पेज स्नैपशॉट पर, उन एजेंट्स और फ़ंक्शन-कॉलिंग फ़्रेमवर्क के लिए जो MCP के बजाय सादा HTTP बोलते हैं। यह डिफ़ॉल्ट रूप से चालू है और इसे किसी कॉन्फ़िगरेशन की आवश्यकता नहीं है:

एंडपॉइंट	क्या लौटाता है
`/api/docs/pages.json`	हर पेज अपने रूट, शीर्षक, विवरण, कंटेंट टाइप, लोकेल, फ़ेसेट्स, और अपने रेंडर किए गए, Markdown तथा JSON रूपों के URL के साथ। अनूदित न किए गए पेजों की i18n फ़ॉलबैक प्रतियाँ शामिल नहीं की जातीं; सर्वर आउटपुट पर, किसी अनुपस्थित पेज का JSON `PAGE_NOT_FOUND` के साथ `404` उत्तर देता है।
`/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 विवरण।

पेज इंडेक्स छिपे हुए पेजों को शामिल नहीं करता, और उन्हें कोई प्रति-पेज दस्तावेज़ भी नहीं मिलता; फिर भी get_page और पेज का .md मिरर उन्हें परोसते हैं, क्योंकि छिपा हुआ होने का अर्थ निजी होना नहीं है। seo.noindex, ai.exclude, या search.exclude वाले पेज किसी भी अन्य पेज की तरह सूचीबद्ध किए जाते हैं। किसी पेज दस्तावेज़ का markdown पेज का वह स्रोत है जिसे एजेंट पढ़ते हैं, जिसमें उसका फ़्रंटमैटर ब्लॉक शीर्ष पर बना रहता है।

पेज इंडेक्स, प्रति-पेज दस्तावेज़, और नेविगेशन प्रीरेंडर किए जाते हैं, इसलिए एक स्टैटिक साइट इन्हें किसी भी होस्ट से फ़ाइलों के रूप में परोसती है। खोज एक लाइव एंडपॉइंट है और केवल सर्वर आउटपुट के अंतर्गत मौजूद रहती है, जहाँ यह वही इंडेक्स चलाती है जो 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 एंडपॉइंट बने रहते हैं), और साथ में एक BLUME_PUBLIC_OPENAPI_JSON चेतावनी दी जाती है: कैटलॉग फिर भी /openapi.json को दस्तावेज़ API के विवरण के रूप में सूचीबद्ध करता है, इसलिए एजेंट आपकी फ़ाइल को वही विवरण समझकर पढ़ेंगे। अपनी स्वयं की स्पेक फ़ाइल प्रकाशित करने के लिए, उसे किसी अन्य पथ पर रखें, जैसे public/specs/openapi.json। /api/… कैच-ऑल तब हट जाता है जब कोई दस्तावेज़ अनुभाग /api नेमस्पेस से परोसा जाता है (content/api/overview.md) या कोई कस्टम पेज /api/ के अंतर्गत किसी शेष रूट का स्वामी होता है, ताकि वे पेज जीतते रहें।

इसे बंद करना

इनमें से कुछ भी प्रकाशित न करने के लिए agents.api को false पर सेट करें:

agents: {
  api: false,
}