# Survey API اور MCP


# Survey API اور MCP

imatic Survey آپ کے باقی اسٹیک سے جڑتا ہے — جوابات کو آپ کے اپنے سسٹمز پر بھیجتا ہے، فارم کے کام کو خودکار بناتا ہے، اور AI ایجنٹس کو آپ کے فارمز کے ساتھ کام کرنے دیتا ہے۔ یہ صفحہ ڈویلپر سطح کا احاطہ کرتا ہے: API کیز، ویب ہکس، REST API، MCP سرور، اور ای میل ترسیل۔ یہ خصوصیات آج فعال ہیں۔

![انٹیگریشنز اور ڈویلپر ترتیبات کا علاقہ](/img/screenshots/survey/integrations.png)
*ڈویلپر علاقہ وہ جگہ ہے جہاں آپ API کیز، ویب ہکس، اور انٹیگریشنز منظم کرتے ہیں۔*

## 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 کلید کو پاس ورڈ کی طرح سمجھیں۔ اسے سورس کنٹرول میں کمٹ نہ کریں، اور اگر آپ کو شک ہو کہ یہ لیک ہو گئی ہے تو اسے تبدیل کریں۔

:::

## ویب ہکس

ویب ہکس ایونٹس کو آپ کے کنٹرول والے ایک 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 سرور اور ویب ہکس** آپ کے پورٹل **JWT** (org تک محدود) کا استعمال کرتے ہیں۔ **REST API** ایک **API کلید** کا استعمال کرتا ہے جو آپ /developers/api-keys کے تحت بناتے ہیں۔ جس سطح کو آپ کال کر رہے ہیں اس کے لیے درست کریڈینشل چنیں۔

:::

## ای میل ترسیل

ای میل ترسیل (مثال کے طور پر، جواب کی اطلاعات) **/settings** کے تحت ای میل ترسیل ٹیب پر ترتیب دی جاتی ہے۔ آپ **چھ فراہم کنندگان** میں سے کسی کو بھی جوڑ سکتے ہیں:

- **Gmail**
- **Resend**
- **SendGrid**
- **Postmark**
- **Amazon SES**
- **حسب ضرورت SMTP**

## اگلے اقدامات

- [ایک فارم شائع اور شیئر کریں](./publishing-sharing)
- [جوابات دیکھیں](./responses)
- [تجزیات کھولیں](./analytics)
- [AI سے ایک فارم بنائیں](./ai-generation)