API-first शेड्यूलिंग: तुम्हारा कैलेंडर एक डेटाबेस है, ऐप नहीं

ज़्यादातर शेड्यूलिंग टूल UI को ही प्रोडक्ट मानते हैं। कैलेंडर ऐप के अंदर रहता है, और उस तक पहुँचने का एकमात्र तरीका लॉगिन करके क्लिक करना है। अगर तुम कुछ ऐसा करना चाहते हो जिसकी डिज़ाइनर ने कल्पना नहीं की — अगले हफ़्ते की मीटिंग्स को अपनी वीकली रिव्यू में खींचना, CSV से ऑफ़िस आवर्स अपने-आप बनाना, किसी साथी के Raycast एक्सटेंशन को अपनी तरफ़ से बुकिंग करने देना — तो तुम फँस जाते हो।

WhenToMeet दूसरा नज़रिया अपनाता है। कैलेंडर एक डेटाबेस है। UI उसका एक व्यू है। अगर तुम्हें कोई और व्यू चाहिए, तो लिख लो।

इसी के लिए v1 REST API है।

API में क्या है

/api/v1/ पर v1 सरफ़ेस जानबूझकर छोटा है। यह वही चीज़ें कवर करता है जिन्हें लोग सच में ऑटोमेट करते हैं:

• Events — शेड्यूलिंग पोल्स और डायरेक्ट इवेंट्स लिस्ट करना, पढ़ना, बनाना। /api/v1/polls
• Bookings — तुम्हारे बुकिंग पेजेस से आई अपॉइंटमेंट्स पढ़ना। /api/v1/bookings
• Calendar events — सभी जुड़े कैलेंडर्स का एकीकृत व्यू, साथ में तुम्हारे अपने शेड्यूलिंग इवेंट्स और बुकिंग्स। /api/v1/calendar/events
• Conflict checks — पूछना कि कोई प्रस्तावित समय तुम्हारे मौजूदा शेड्यूल से टकराता है या नहीं
• Profile — अपना यूज़र प्रोफ़ाइल, टाइमज़ोन, टियर और सेटिंग्स लाना

Authentication Bearer टोकन से होती है। तुम अपनी अकाउंट सेटिंग्स में sk_… की जेनरेट करते हो, उसे Authorization: Bearer sk_… में भेजते हो, और अंदर आ जाते हो। हर एंडपॉइंट स्कोप्ड है, तो एक की सिर्फ़ वही देख सकती है जो उसे देखने की अनुमति है।

एक OpenAPI spec है। docs.whentomeet.io पर डॉक्स में हर एंडपॉइंट के रिक्वेस्ट/रिस्पॉन्स शेप के साथ लिस्ट है, तो तुम उस पर कोड जेनरेटर चलाकर अपनी पसंद की भाषा में typed client पा सकते हो।

Pro-gated क्यों

API एक्सेस Pro फ़ीचर है। ईमानदार वजह यह है कि API एक सपोर्ट सरफ़ेस है — keys लीक होती हैं, स्क्रिप्ट्स लूप में फँसती हैं, रेट लिमिट्स टकराती हैं — और हम इसे ध्यान से उन लोगों के लिए सपोर्ट करना चाहते हैं जिन्हें वाक़ई ज़रूरत है, बजाय इसे सारे फ़्री अकाउंट्स में पतला फैलाने के। रेट लिमिट्स per-key हैं और आम ऑटोमेशन के लिए जानबूझकर ढीली हैं। वीकली डाइजेस्ट से तुम वहाँ नहीं पहुँचोगे।

इससे क्या बदलता है

जब कैलेंडर एक असली एंडपॉइंट बन जाता है, तो जो काम वह पैदा करता था वह स्क्रिप्ट्स में गायब हो जाता है:

• इंटर्न अब अगले हफ़्ते की मीटिंग्स टीम विकी में कॉपी नहीं करता। एक cron job करता है।
• तुम बुकिंग नोटिफ़िकेशंस को अपने CRM में फ़ॉरवर्ड नहीं करते। एक webhook-जैसा poll उन्हें लिख देता है।
• इंजीनियरिंग लीड अब शेड्यूलिंग PM नहीं है। एक शेयर की हुई स्क्रिप्ट एक कमांड में वीकली स्टैंडअप बना देती है।

भावना में इनमें से कुछ नया नहीं है — डेवलपर्स पंद्रह साल से APIs के ज़रिए SaaS को जोड़ते आ रहे हैं। नया हिस्सा यह है कि शेड्यूलिंग टूल्स ऐतिहासिक रूप से उस ढेर में आने से इनकार करते रहे हैं। Calendly एक प्रोडक्ट था और उसके आगे कुछ नहीं। असली API के साथ, प्रोडक्ट कई क्लाइंट्स में से एक बन जाता है।

अगर तुम कुछ बना रहे हो

docs.whentomeet.io से शुरू करो, एक key जेनरेट करो, उससे GET /api/v1/polls कॉल करो, और तुम्हें अपने ख़ुद के शेड्यूलिंग पोल्स JSON में वापस आते दिखेंगे। इसके आगे सब कुछ composition है।

अगर स्क्रिप्ट ख़ुद लिखने के बजाय तुम चाबियाँ किसी एजेंट को देना चाहते हो — Claude, ChatGPT, Cursor — तो /api/mcp पर MCP सर्वर उन्हीं एंडपॉइंट्स को उस प्रोटोकॉल में लपेटता है जिसे ये क्लाइंट्स पहले से बोलते हैं। वही auth, वही रेट लिमिट्स। इसे हम अगली पोस्ट में कवर करेंगे।