# Survey API और MCP


# Survey API और MCP

imatic Survey आपके बाकी स्टैक से जुड़ता है — प्रतिक्रियाओं को आपके अपने सिस्टम पर भेजना, फ़ॉर्म के काम को स्वचालित करना, और AI एजेंटों को आपके फ़ॉर्म के साथ काम करने देना। यह पेज डेवलपर सतह को कवर करता है: API कुंजियाँ, webhooks, REST API, MCP सर्वर, और ईमेल डिलीवरी। ये सुविधाएँ आज चालू हैं।

![इंटीग्रेशन और डेवलपर सेटिंग्स क्षेत्र](/img/screenshots/survey/integrations.png)
*डेवलपर क्षेत्र वह जगह है जहाँ आप API कुंजियाँ, webhooks, और इंटीग्रेशन प्रबंधित करते हैं।*

## API कुंजियाँ

API कुंजियाँ आपके अपने ऐप्स और स्क्रिप्ट को Survey **REST API** के विरुद्ध प्रमाणित करती हैं। इन्हें **/developers/api-keys** के अंतर्गत बनाएँ और प्रबंधित करें, जहाँ आप एक कुंजी जारी कर सकते हैं, उसे एक नाम दे सकते हैं, उसके उपयोग आँकड़े देख सकते हैं, और यदि यह कभी उजागर हो जाए तो इसे रद्द कर सकते हैं।

एक कुंजी पूरी तरह केवल एक बार, निर्माण के समय दिखाई जाती है — उसे तभी कॉपी करें और कहीं सुरक्षित संग्रहीत करें। उसके बाद आप सूची में उसके नाम, स्कोप, और अंतिम-उपयोग समय के साथ केवल उसका prefix देखेंगे।

API `https://surveyapi.imatic.ai` पर होस्ट किया गया है, और कुंजियाँ `sk_`-प्रीफ़िक्स्ड होती हैं। अपनी कुंजी को Bearer टोकन के रूप में भेजें। एंडपॉइंट कस्टम-वर्ब POST अनुरोध होते हैं — उदाहरण के लिए, अपने फ़ॉर्म की सूची देखने के लिए:

```bash
curl -X POST https://surveyapi.imatic.ai/forms/list \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

:::tip[कुंजियों को गुप्त रखें]

एक API कुंजी को पासवर्ड की तरह समझें। इसे सोर्स कंट्रोल में कमिट न करें, और यदि आपको संदेह हो कि यह लीक हो गई है तो इसे घुमाएँ।

:::

## Webhooks

Webhooks इवेंट को आपके नियंत्रण वाले किसी URL पर भेजते हैं, ताकि परिवर्तनों के लिए पोल करने के बजाय आपके सिस्टम कुछ होते ही प्रतिक्रिया दें। इन्हें **/developers/webhooks** के अंतर्गत कॉन्फ़िगर करें।

उपलब्ध इवेंट:

- **`response.created`** — जब कोई नई प्रतिक्रिया प्रस्तुत होती है तब चलता है।
- **`response.flagged`** *(नियोजित — अभी तक उत्सर्जित नहीं)* — जब कोई प्रतिक्रिया फ़्लैग की जाती है (उदाहरण के लिए, धोखाधड़ी या स्पैम जाँच द्वारा)।
- **`response.updated`** *(नियोजित — अभी तक उत्सर्जित नहीं)* — जब कोई प्रतिक्रिया अपडेट या मॉडरेट की जाती है।
- **`form.published`** *(नियोजित — अभी तक उत्सर्जित नहीं)* — जब कोई फ़ॉर्म प्रकाशित होता है।
- **`form.closed`** *(नियोजित — अभी तक उत्सर्जित नहीं)* — जब कोई फ़ॉर्म बंद होता है।

प्रत्येक डिलीवरी एक **HMAC-SHA256** हस्ताक्षर से हस्ताक्षरित होती है (`X-Signature` हेडर में भेजा जाता है, `X-Timestamp`, `X-Event-Id`, और `X-Event-Type` के साथ) ताकि आपका एंडपॉइंट पुष्टि कर सके कि अनुरोध वास्तव में imatic Survey से आया और रास्ते में उसमें छेड़छाड़ नहीं हुई। विफल डिलीवरी को विफल चिह्नित करने से पहले घातीय बैकऑफ़ के साथ **पुनः प्रयास** किया जाता है।

## REST API

**REST API** आपको फ़ॉर्म और प्रतिक्रियाओं को प्रोग्रामेटिक रूप से प्रबंधित करने देता है। एंडपॉइंट किसी संस्करणयुक्त पथ प्रीफ़िक्स के बजाय कस्टम-वर्ब POST अनुरोधों का उपयोग करते हैं — उदाहरण के लिए, `POST /forms/list` (फ़ॉर्म की सूची), `POST /forms/get-for-edit` (किसी फ़ॉर्म की स्कीमा पढ़ना), `POST /forms/generate` (AI से फ़ॉर्म बनाना), `POST /forms/duplicate`, और `POST /forms/delete`। यह `https://surveyapi.imatic.ai` पर होस्ट किया गया है और एक [API कुंजी](#api-कुंजियाँ) — एक `sk_`-प्रीफ़िक्स्ड Bearer टोकन — से प्रमाणित होता है।

## AI एजेंटों के लिए MCP सर्वर

**MCP सर्वर** Survey को Model Context Protocol के माध्यम से AI एजेंटों के सामने उजागर करता है, ताकि कोई सहायक आपकी ओर से आपके फ़ॉर्म और प्रतिक्रियाओं के साथ काम कर सके। यह `POST /mcp` पर **JSON-RPC 2.0** बोलता है और आपके पोर्टल **JWT** (Bearer टोकन के रूप में भेजा गया) से प्रमाणित होता है, जो हर कॉल को आपके संगठन तक स्कोप करता है।

यह **10 टूल** के साथ आता है:

- **`whoami`** — प्रमाणित संगठन संदर्भ लौटाता है।
- **`list_forms`** — आपके प्रकाशित फ़ॉर्म की सूची देता है।
- **`get_form`** — किसी फ़ॉर्म की स्कीमा और फ़ील्ड पढ़ता है।
- **`submit_response`** — किसी फ़ॉर्म पर एक प्रतिक्रिया प्रस्तुत करता है।
- **`list_responses`** — प्रतिक्रियाओं की सूची देता है (पेजिनेटेड)।
- **`get_response`** — किसी एकल प्रतिक्रिया को पढ़ता है।
- **`get_response_stats`** — एकत्रित प्रतिक्रिया आँकड़े पढ़ता है।
- **`create_poll`** — एक एकल-प्रश्न पोल बनाता और प्रकाशित करता है।
- **`cast_vote`** — किसी पोल पर एक वोट डालता है।
- **`live_poll_results`** — लाइव पोल गिनती पढ़ता है।

:::info[दो अलग क्रेडेंशियल]

**MCP सर्वर और webhooks** आपके पोर्टल **JWT** (org-स्कोप्ड) का उपयोग करते हैं। **REST API** एक **API कुंजी** का उपयोग करता है जो आप /developers/api-keys के अंतर्गत बनाते हैं। आप जिस सतह को कॉल कर रहे हैं उसके लिए सही क्रेडेंशियल चुनें।

:::

## ईमेल डिलीवरी

ईमेल डिलीवरी (उदाहरण के लिए, प्रतिक्रिया सूचनाएँ) ईमेल-डिलीवरी टैब पर **/settings** के अंतर्गत कॉन्फ़िगर की जाती है। आप **छह प्रदाताओं** में से किसी को भी कनेक्ट कर सकते हैं:

- **Gmail**
- **Resend**
- **SendGrid**
- **Postmark**
- **Amazon SES**
- **Custom SMTP**

## अगले कदम

- [एक फ़ॉर्म प्रकाशित और साझा करें](./publishing-sharing)
- [प्रतिक्रियाएँ देखें](./responses)
- [एनालिटिक्स खोलें](./analytics)
- [AI के साथ एक फ़ॉर्म बनाएँ](./ai-generation)