परिचय

Conventions

• Base path: सभी endpoints https://us1.platform.bird.com जैसे regional host पर /v1 के अंतर्गत होते हैं। देखें Base URLs और regions।
• Authentication: requests एक API key को bearer token के रूप में ले जाते हैं: Authorization: Bearer bk_us1_...। देखें Authentication।
• JSON, snake_case: request और response bodies snake_case field names (created_at, workspace_id) के साथ JSON होती हैं, और requests को Content-Type: application/json सेट करना ज़रूरी है।
• Timestamps: सभी timestamps RFC 3339 strings हैं UTC में, _at प्रत्यय वाले fields में (created_at, delivered_at)। created_at जैसे resource timestamps सर्वर द्वारा असाइन किए जाते हैं और read-only होते हैं; कुछ request fields, जैसे scheduled_at, ऐसे timestamps हैं जो आप देते हैं।
• Typed resource IDs: हर ID एक type prefix रखता है: email messages के लिए em_, sending domains के लिए dom_, webhook endpoints के लिए whk_, suppressions के लिए sup_, आदि। यह prefix ID को logs में स्व-वर्णनात्मक बनाता है और एक resource की ID को दूसरे की जगह पास करने से रोकता है।
• आंशिक अपडेट PATCH से होते हैं: PATCH रिक्वेस्ट केवल उन फ़ील्ड्स को बदलती है जो आप शामिल करते हैं; छोड़ी गई फ़ील्ड्स अपरिवर्तित रहती हैं। कुछ सब-रिसोर्स जिन्हें आप URL में नाम से संबोधित करते हैं, PUT से लिखे जाते हैं, जो उस सब-रिसोर्स को पूरी तरह बदल देता है।
• Query parameters सख़्त हैं: यदि कोई request ऐसा query parameter ले जाता है जो endpoint में दस्तावेज़ित नहीं है, तो उसे अनदेखा करने के बजाय 422 (E01029) के साथ अस्वीकार कर दिया जाता है। endpoint की parameter सूची से स्पेलिंग जाँचें।
• Errors: हर error response एक ही envelope रखता है, जिसमें मोटे वर्गीकरण के लिए type, एक स्थिर code, मानव-पठनीय message, और सहायता से संपर्क करते समय उद्धृत करने के लिए request_id होता है। देखें त्रुटि प्रतिक्रियाएँ।
• Pagination: list endpoints cursor-based pagination का उपयोग करते हैं एक साझा parameter set के साथ। देखें Pagination।
• Idempotency: mutating endpoints एक Idempotency-Key हेडर स्वीकार करते हैं ताकि फिर से प्रयास करना सुरक्षित रहे। देखें Idempotency-Key हेडर।
• Deprecations: नाम बदला गया field अपने पुराने नाम से काम करता रहता है, और response Deprecation हेडर के ज़रिए यह बताता है। देखें Deprecations।

अनुशंसित clients

• TypeScript, Go, और Python के लिए आधिकारिक SDKs: क्यूरेटेड सार्वजनिक surface पर typed methods
• Bird CLI: आपके टर्मिनल से API, scripts और agents के लिए भी उपयुक्त

Postman में चलाएँ

आगे पढ़ें

• Authentication: requests वायर स्तर पर कैसे authenticate होते हैं
• Base URLs और regions: regional hosts और region मॉडल
• Pagination: cursors, page sizes, और sorting
• Idempotency-Key हेडर: mutating requests के लिए सुरक्षित फिर से प्रयास
• त्रुटि प्रतिक्रियाएँ: त्रुटि envelope और संपूर्ण त्रुटि कैटलॉग
• Deprecations: एक हटाया गया field name अभी भी क्या करता है, और उससे कैसे migrate करें