---
title: हाथ से लिखे API पेज
description: >-
  बिना spec के MDX में किसी endpoint का दस्तावेज़ लिखें, और फिर भी method और path, Try it पैनल, अनुरोध के नमूने और पिन किए गए उदाहरण पाएँ।
---

हर API के पास OpenAPI spec नहीं होता, और कुछ endpoints हाथ से लिखे जाने पर अधिक पठनीय होते हैं। `api` frontmatter वाला पेज एक endpoint का दस्तावेज़ होता है। इसके [फ़ील्ड](/hi/docs/content/components#api-fields) अनुरोध और प्रतिक्रिया का वर्णन करते हैं। Blume इन्हीं से [OpenAPI संदर्भ](/hi/docs/references/openapi) पेज का बाकी हिस्सा बनाता है: सबसे ऊपर method और path, सामग्री के बगल वाले कॉलम में Try it पैनल और अनुरोध के नमूने, और उनके नीचे पिन किए गए [अनुरोध और प्रतिक्रिया के उदाहरण](/hi/docs/content/components#request-and-response-examples)।

````mdx docs/users/create.mdx lineNumbers
---
title: Create a user
api: POST /workspaces/{workspaceId}/users
---

Creates a user and sends them an invite.

<ParamField path="workspaceId" type="string" required>
  The workspace to add the user to.
</ParamField>

<ParamField body="email" type="string" required placeholder="ada@example.com">
  The user's email address.
</ParamField>

<ParamField body="role" type="string" default="member">
  One of `owner`, `admin`, or `member`.
</ParamField>

<ResponseField name="id" type="string" required>
  The new user's ID.
</ResponseField>

<ResponseExample>

```json 201
{ "id": "usr_8f2k", "status": "invited" }
```

</ResponseExample>
````

`api` में एक HTTP method के साथ path या पूरा URL दिया जाता है। Path पैरामीटर braces में लिखे जाते हैं, जैसे `{workspaceId}`, और इनका मान उसी नाम वाले `path` फ़ील्ड से भरा जाता है। पूरा URL, जैसे `GET https://api.acme.com/v1/users`, दिया गया हो तो अनुरोध ठीक उसी पर भेजा जाता है जैसा वह लिखा गया है। Path दिया गया हो तो वह साइट के [`api.server`](#site-defaults) के साथ जोड़ा जाता है।

## Playground और नमूने [#the-playground-and-samples]

Spec में जैसे किसी operation के पैरामीटर Try it पैनल के इनपुट बनते हैं, वैसे ही यहाँ पेज के `ParamField` बनते हैं। `path`, `query` और `header` फ़ील्ड पैरामीटर होते हैं। `body` फ़ील्ड मिलकर JSON body बनाते हैं। किसी फ़ील्ड के भीतर नेस्ट किए गए फ़ील्ड (उसके [`Expandable`](/hi/docs/content/components#expandable) के अंदर) एक object की properties बनते हैं। `string[]` वाला `type` एक array होता है। जो type JSON type नहीं है, जैसे `enum<string>`, वह string के रूप में भेजा जाता है। किसी फ़ील्ड का `default` मान body में भरा जाता है, और उसका `placeholder` वह उदाहरण मान है जो नमूनों में दिखता है।

पैनल के बगल में पेज पर cURL, JavaScript और Python में अनुरोध के नमूने दिखते हैं। अगर पेज का अपना `RequestExample` हो, तो इन नमूनों की जगह वही दिखता है।

दो और frontmatter keys से आप पेज को अपनी ज़रूरत के अनुसार ढाल सकते हैं:

- `authMethod` तय करता है कि endpoint प्रमाणीकरण कैसे करता है: `bearer`, `basic`, `key` (header में भेजी गई API key) या `none`। यह साइट के [`api.auth`](#site-defaults) पर प्राथमिकता लेता है।
- `playground` तय करता है कि पेज पर क्या दिखे: Try it पैनल और नमूनों के लिए `interactive` (डिफ़ॉल्ट), केवल नमूनों के लिए `simple`, या इनमें से कुछ भी न दिखाने के लिए `none`। Method, path और उदाहरण हर हाल में दिखते रहते हैं।

## साइट डिफ़ॉल्ट [#site-defaults]

`blume.config.ts` में `api` वे सेटिंग्स तय करता है जो सभी endpoint पेजों पर एक जैसी लागू होती हैं:

```ts blume.config.ts lineNumbers
export default defineConfig({
  api: {
    server: "https://api.acme.com/v1",
    auth: { method: "key", name: "x-api-key" },
    playground: { proxy: true },
  },
});
```

- `server` वह base URL है जिसके साथ `api` का path जोड़ा जाता है।
- `auth` तय करता है कि अनुरोधों का प्रमाणीकरण कैसे हो। जिस पेज पर `authMethod` सेट हो, वहाँ `authMethod` ही लागू होता है। `method` का मान `bearer`, `basic`, `key` या `none` होता है। `name` उस header का नाम है जिसमें API key भेजी जाती है (डिफ़ॉल्ट रूप से `x-api-key`)। `auth` सेट न हो तो पेज कोई क्रेडेंशियल नहीं भेजते।
- `playground` के मान वही हैं जो OpenAPI संदर्भ के [playground विकल्प](/hi/docs/references/openapi#try-it-playground) के हैं। `false` हर पेज से Try it पैनल हटा देता है। `proxy` पैनल के अनुरोधों को CORS proxy से भेजता है। इसके लिए आप अपने proxy का URL दे सकते हैं, या Blume का बिल्ट-इन proxy इस्तेमाल करने के लिए `true` दे सकते हैं। बिल्ट-इन proxy के लिए [सर्वर आउटपुट](/hi/docs/deployment#server-rendering) ज़रूरी है। यह अनुरोध केवल `server` के origin पर और `api` frontmatter में दिए गए पूरे URLs के origins पर ही आगे भेजता है।

पेज का लेआउट, फ़ील्ड और उदाहरण वही कंपोनेंट हैं जो बाकी जगहों पर इस्तेमाल होते हैं। इसलिए पेज की [Markdown कॉपी](/hi/docs/discoverability/llms-txt) में हर फ़ील्ड सूचीबद्ध होता है, और सर्च इस पेज को बाकी पेजों की तरह ही इंडेक्स करता है।

Frontmatter keys और कंपोनेंट props वही हैं जो Mintlify में हैं, इसलिए Mintlify के लिए लिखे गए पेज बिना किसी बदलाव के काम करते रहते हैं।