परिचय

Bird API प्लेटफ़ॉर्म के सभी कामों के लिए एक एकीकृत REST API है। यह संदर्भ हर सार्वजनिक एंडपॉइंट का दस्तावेज़ है। इसे उसी OpenAPI स्पेसिफ़िकेशन से बनाया गया है जिससे आधिकारिक SDK बनते हैं, इसलिए यहाँ दिए गए अनुरोध और प्रतिक्रिया के ढाँचे ठीक वही हैं जो नेटवर्क पर भेजे जाते हैं।

संदर्भ साइडबार सबसे ज़्यादा इस्तेमाल होने वाले संसाधनों को प्रोडक्ट के अनुसार समूहित करता है: Email, SMS, WhatsApp, Apple Messages, Voice, eSIM, Realtime, Verify, Preferences, Numbers, Lookup, Workspace, और डेवलपर टूल (Webhooks और Documentation, यानी डॉक्स खोज API)। भेजने वाले डोमेन, आने वाले ईमेल, और संपर्क व ऑडियंस के संदर्भ पेज हैं, पर साइडबार में उनकी प्रविष्टि नहीं है। भेजने वाला डोमेन बनाएँ, इनबाउंड पता बनाएँ, संपर्क बनाएँ और ऑडियंस बनाएँ से शुरू करें, या उनकी गाइड से: भेजने वाले डोमेन, ईमेल प्राप्त करना, संपर्क और ऑडियंस। Voice सेक्शन में कॉल, लेग लॉग, ट्रंक, नंबर, कॉलर ID, गंतव्य और SIP सेशन क्रेडेंशियल शामिल हैं। Voice के आँकड़े डैशबोर्ड और CLI के ज़रिए उपलब्ध रहते हैं। वर्कस्पेस सेटिंग्स, API कुंजियाँ और समर्पित IP सार्वजनिक API के बजाय डैशबोर्ड में प्रबंधित होते हैं।

गाइड से संसाधन पेजों के सीधे लिंक दिए गए हैं: जब कोई गाइड किसी एंडपॉइंट का ज़िक्र करती है, तो लिंक यहाँ उसकी संदर्भ प्रविष्टि पर ले जाता है।

कोडिंग एजेंट के लिए

एजेंट को ये मशीन-पठनीय स्रोत दें:

OpenAPI स्पेसिफ़िकेशन: हर सार्वजनिक एंडपॉइंट, स्कीमा और त्रुटि कोड, जो YAML के रूप में भी उपलब्ध है। SDK इसी फ़ाइल से बनाए जाते हैं।
API इंडेक्स: API गाइड, हर ऑपरेशन का संदर्भ और सार्वजनिक त्रुटियाँ, प्रोडक्ट के अनुसार समूहित और उनके Markdown पेजों से लिंक की गई।
डॉक्स इंडेक्स: हर प्रकाशित अंग्रेज़ी डॉक्स पेज, सेक्शन और प्रोडक्ट के अनुसार समूहित।
साइट इंडेक्स: bird.com पर प्रोडक्ट, क्विकस्टार्ट और एजेंट टूलिंग।
MCP सर्वर: mcp.bird.com पर होस्ट किए गए टूल, जो ब्राउज़र में साइन-इन के बाद आपके वर्कस्पेस पर काम करते हैं।
Bird CLI: टर्मिनल से API का उपयोग। एजेंटों के लिए CLI इसके JSON आउटपुट और एग्ज़िट कोड बताता है।
Markdown पेज: किसी भी डॉक्स URL के अंत में .md जोड़ें, जैसे https://bird.com/docs/api.md, या Accept: text/markdown भेजें।

प्रोडक्ट मैप

हर तालिका में वे कॉल क्रम से दी गई हैं जो एक इंटीग्रेशन करता है, साथ में हर कॉल के रेफ़रेंस पेज और प्रोडक्ट की गाइड के लिंक हैं।

ईमेल

चरण	कॉल
सेटअप	`POST /v1/email/domains`, फिर डोमेन के DNS रिकॉर्ड प्रकाशित करने के बाद `POST /v1/email/domains/{domain_id}/verify`। Bird के साझा ऑनबोर्डिंग डोमेन से टेस्ट भेजने के लिए इनमें से किसी की ज़रूरत नहीं है।
भेजें	`POST /v1/email/messages`
परिणाम	`GET /v1/email/messages/{message_id}`, या आपके webhook एंडपॉइंट पर भेजे गए ईमेल इवेंट
गाइड	ईमेल का अवलोकन और अपना पहला ईमेल भेजें

SMS

चरण	कॉल
सेटअप	गंतव्य देश को SMS > Destinations में, CLI में `bird sms destinations update` से, या `sms_destinations_update` MCP टूल से सक्षम करें। सार्वजनिक API में गंतव्य या सेंडर से जुड़े कोई ऑपरेशन नहीं हैं।
भेजें	`POST /v1/sms/messages`। बिल्ट-इन टेम्पलेट अपना सेंडर खुद चुनता है। फ़्री-फ़ॉर्म टेक्स्ट के लिए ऐसा सेंडर चाहिए जिसे आपका वर्कस्पेस इस्तेमाल कर सके।
परिणाम	`GET /v1/sms/messages/{message_id}`, या आपके webhook endpoint पर भेजे जाने वाले `sms.*` SMS इवेंट
गाइड	SMS का अवलोकन और अपना पहला SMS भेजें

Verify

चरण	कॉल
सेटअप	कुछ नहीं। Bird के साझा sender sender पंजीकरण के बिना ही कोड पहुँचाते हैं।
भेजें	`POST /v1/verify/verifications`
परिणाम	`POST /v1/verify/verifications/check` उपयोगकर्ता द्वारा दर्ज किए गए कोड की जाँच करता है। `POST /v1/verify/verifications/next-channel` अगले चैनल पर नया कोड भेजता है।
गाइड	Verify का अवलोकन और अपने पहले ग्राहक का सत्यापन करें

अन्य उत्पाद

उत्पाद	गाइड	पहली कॉल
WhatsApp	WhatsApp का अवलोकन	`POST /v1/whatsapp/messages`
Apple Messages	Apple Messages for Business गाइड	`POST /v1/amb/messages`
Voice	Voice का अवलोकन	`POST /v1/voice/calls`
eSIM	eSIM कनेक्टिविटी गाइड	`POST /v1/esim/orders`
Realtime	Realtime का अवलोकन	`POST /v1/realtime/apps/{realtime_app_id}/events`
Numbers	Numbers का अवलोकन	`GET /v1/numbers/available`
Lookup	Lookup का अवलोकन	`POST /v1/lookup/phone-number`
Webhooks	Webhooks और इवेंट	`POST /v1/webhooks`

नियम

हर एंडपॉइंट एक जैसे नियमों का पालन करता है। इन्हें हर पेज पर दोहराने के बजाय यहाँ एक बार बताया गया है।

बेस पाथ: सभी एंडपॉइंट https://us1.platform.bird.com जैसे किसी क्षेत्रीय होस्ट पर /v1 के अंतर्गत होते हैं। बेस URL और क्षेत्र देखें।
ऑथेंटिकेशन: अनुरोधों में API कुंजी bearer टोकन के रूप में भेजी जाती है: Authorization: Bearer bk_us1_...। ऑथेंटिकेशन देखें।
JSON, snake_case: अनुरोध और प्रतिक्रिया की बॉडी JSON में होती है और फ़ील्ड के नाम snake_case में होते हैं (created_at, workspace_id)। अनुरोधों में Content-Type: application/json सेट करना ज़रूरी है।
टाइमस्टैम्प: सभी टाइमस्टैम्प UTC में RFC 3339 स्ट्रिंग होते हैं और उन फ़ील्ड में आते हैं जिनके नाम के अंत में _at होता है (created_at, delivered_at)। created_at जैसे रिसोर्स टाइमस्टैम्प सर्वर तय करता है और ये केवल पढ़े जा सकते हैं। scheduled_at जैसे कुछ अनुरोध फ़ील्ड ऐसे टाइमस्टैम्प हैं जो आप खुद देते हैं।
टाइप वाले रिसोर्स ID: हर ID में एक टाइप प्रीफ़िक्स होता है: ईमेल संदेशों के लिए em_, भेजने वाले डोमेन के लिए dom_, webhook एंडपॉइंट के लिए whk_, सप्रेशन के लिए sup_, इत्यादि। प्रीफ़िक्स से लॉग में हर ID अपना प्रकार खुद बताती है, और एक रिसोर्स की ID को वहाँ भेजने से रोका जाता है जहाँ किसी दूसरे रिसोर्स की ID अपेक्षित है।
आंशिक अपडेट PATCH से होते हैं: PATCH अनुरोध सिर्फ़ उन्हीं फ़ील्ड को बदलता है जिन्हें आप शामिल करते हैं, और छोड़े गए फ़ील्ड जैसे हैं वैसे रहते हैं। कुछ सबरिसोर्स, जिन्हें आप URL में नाम से पहचानते हैं, PUT से लिखे जाते हैं, जो उस सबरिसोर्स को पूरी तरह बदल देता है।
क्वेरी पैरामीटर सख़्त हैं: अगर किसी अनुरोध में ऐसा क्वेरी पैरामीटर है जिसे एंडपॉइंट दस्तावेज़ में नहीं बताता, तो उसे अनदेखा करने के बजाय 422 (E01029) के साथ अस्वीकार किया जाता है। एंडपॉइंट की पैरामीटर सूची से वर्तनी मिलाएँ।
त्रुटियाँ: हर त्रुटि प्रतिक्रिया का ढाँचा एक जैसा होता है: मोटे तौर पर शाखा तय करने के लिए type, एक स्थिर code, पढ़ने योग्य message, और सपोर्ट से संपर्क करते समय बताने के लिए request_id। देखें त्रुटि प्रतिक्रियाएँ।
पेजिनेशन: सूची वाले एंडपॉइंट पैरामीटर के साझा सेट के साथ कर्सर-आधारित पेजिनेशन इस्तेमाल करते हैं। देखें पेजिनेशन।
Idempotency: डेटा बदलने वाले एंडपॉइंट Idempotency-Key हेडर स्वीकार करते हैं, ताकि फिर से प्रयास करना सुरक्षित रहे। देखें Idempotency-Key हेडर।
Deprecation: नाम बदला गया फ़ील्ड अपने पुराने नाम से भी काम करता रहता है, और प्रतिक्रिया Deprecation हेडर से यह बताती है। देखें Deprecation।

सुझाए गए क्लाइंट

आप किसी भी HTTP क्लाइंट से API को कॉल कर सकते हैं, लेकिन आधिकारिक क्लाइंट ऑथेंटिकेशन, क्षेत्र का चयन, फिर से प्रयास और पेजिनेशन आपके लिए संभालते हैं:

TypeScript, Go और Python के आधिकारिक SDK: चुनी गई सार्वजनिक सतह पर टाइप किए गए मेथड
Bird CLI: आपके टर्मिनल से API, जो स्क्रिप्ट और एजेंट के लिए भी उपयुक्त है

इसे Postman में चलाएँ

पूरा API एक Postman collection के रूप में भी उपलब्ध है, जिसे इसी specification से बदला गया है और जिसमें हर endpoint पर एक उदाहरण अनुरोध और प्रतिक्रिया है। अपने region का environment import करें, apiKey को वर्कस्पेस की API कुंजी पर सेट करें, और कोई भी अनुरोध भेजें।

आप collection और us1 या eu1 के लिए environment सीधे डाउनलोड भी कर सकते हैं।

आगे पढ़ें

Authentication: wire स्तर पर अनुरोध कैसे authenticate होते हैं
Base URL और region: regional host और region मॉडल
Pagination: cursor, page का आकार और sorting
Idempotency-Key हेडर: डेटा बदलने वाले अनुरोधों के लिए सुरक्षित रूप से फिर से प्रयास करना
त्रुटि प्रतिक्रियाएँ: त्रुटि प्रतिक्रिया का ढाँचा और त्रुटियों की पूरी सूची
Deprecations: बदले जा चुके field नाम का अब भी क्या असर होता है, और उससे कैसे migrate करें

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

इम्प्लीमेंटेशन ब्रीफ़ पाएँ

संबंधित संसाधन