LinkHarbor API एक नज़र में

REST API से आप अपने प्रोग्राम से LinkHarbor को नियंत्रित करते हैं: पेज और लिंक बनाना, ड्राफ़्ट बदलना और पब्लिश करना, शॉर्ट लिंक बनाना या आँकड़े अपनी रिपोर्टिंग में लाना। यह लेख डेवलपरों के लिए है और उन बुनियादी नियमों को बताता है जो हर एंडपॉइंट पर लागू होते हैं।

#कौन-सा रास्ता सही है?

#Base URL और वर्ज़निंग

Base URL

https://dock.at-harbor.com – सभी प्रोडक्ट एंडपॉइंट /v1 के तहत हैं, जैसे https://dock.at-harbor.com/v1/pages।

वर्ज़न

अभी सिर्फ़ v1 वर्ज़न है। वर्ज़न नंबर पाथ का हिस्सा है।

प्रोटोकॉल

सिर्फ़ HTTPS।

OpenAPI

मशीन से पढ़ा जा सकने वाला विवरण (OpenAPI 3.1) https://dock.at-harbor.com/openapi.yaml पर है। आप इसे Postman, Insomnia या किसी कोड जनरेटर में लोड कर सकते हैं।

#Sandbox में टेस्टिंग

डेवलपमेंट और टेस्टिंग के लिए एक अलग sandbox है। यह असली API की तरह काम करता है, लेकिन उससे पूरी तरह अलग है: अपने अकाउंट, अपना डेटा, और इसमें से कुछ भी आपके असली वर्कस्पेस में नहीं पहुँचता।

API

https://drydock.at-harbor.com, ऊपर वाले ही पाथ के साथ, जैसे https://drydock.at-harbor.com/v1/pages।

डैशबोर्ड

https://sandbox-deck.linkharbor.com, जैसे API keys बनाने के लिए।

पेज

पब्लिश किए पेज https://<handle>.sandbox.linkharbor.com पर दिखते हैं।

अकाउंट

आपका असली LinkHarbor अकाउंट वहाँ काम नहीं करता। एक अलग sandbox अकाउंट बनाएँ।

Sandbox ईमेल नहीं भेजता। अगर आप API से रजिस्टर करते हैं (POST /v1/auth/register), तो सत्यापन कोड सीधे जवाब में _dev_verification फ़ील्ड में आता है। पासवर्ड रीसेट और ईमेल बदलने पर भी यही लागू होता है। यह फ़ील्ड सिर्फ़ sandbox में होता है, इसलिए अपने कोड में इस पर निर्भर न रहें।

• पुश नोटिफ़िकेशन बंद हैं
• भुगतान Stripe के टेस्ट मोड से होते हैं, कोई असली पैसा नहीं जाता
• रेट लिमिट असली वैल्यू की लगभग एक तिहाई हैं, और नए अकाउंट हर IP पते से प्रति घंटे 5 तक सीमित हैं
• हर महीने की 1 तारीख़ को 3:00 UTC पर sandbox पूरी तरह साफ़ किया जाता है, और उसके बाद सभी अकाउंट और डेटा चले जाते हैं
• हर जवाब में X-Environment: sandbox हेडर होता है

#संक्षेप में ऑथेंटिकेशन

1. मालिक या एडमिन के रूप में डैशबोर्ड में “Callback और API” के तहत ज़रूरी स्कोप वाली एक API key बनाएँ (Creator Pro से)
2. POST /v1/token से key ID और key secret के बदले एक access token लें
3. हर अनुरोध में टोकन Authorization: Bearer … हेडर में भेजें
4. 15 मिनट बाद नया टोकन लें

सारी जानकारी API keys और एक्सेस टोकन में है, अनुमतियाँ स्कोप में।

#अनुरोध और जवाब

फ़ॉर्मैट

अनुरोध और जवाब UTF-8 में JSON होते हैं। फ़ाइल अपलोड के लिए multipart/form-data भी।

Content-Type

बॉडी वाले हर अनुरोध के साथ Content-Type: application/json हेडर भेजें। कोई भी दूसरा प्रकार 400 bad_request के साथ अस्वीकार होता है – वह भी, जो यह हेडर न होने पर curl -d के लिए अपने आप सेट करता है।

अज्ञात फ़ील्ड

जिन फ़ील्ड को कोई एंडपॉइंट नहीं जानता, उनसे 422 validation_failed होता है। जवाब अज्ञात फ़ील्ड के नाम बताता है।

ख़राब JSON

इससे 400 invalid_json होता है।

साइज़

एंडपॉइंट के हिसाब से बॉडी ज़्यादा से ज़्यादा 64 KB, 1 MB या 2 MB, और फ़ाइल अपलोड 10 MB तक हो सकता है। इससे बड़ा होने पर API 413 request_too_large के साथ जवाब देता है। सभी सीमाएँ रेट लिमिट में दी गई हैं।

सूचियाँ

items फ़ील्ड वाले एक ऑब्जेक्ट के रूप में आती हैं, जैसे {"items":[…]}।

बनाना

HTTP 201 और नई ID के साथ जवाब देता है, जैसे {"id":123}।

बिना रिटर्न वैल्यू वाले काम

{"ok":true} के साथ जवाब देते हैं।

त्रुटियाँ

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

#पेजिनेशन

पेजिनेशन का कोई एक तरीका नहीं है। ज़्यादातर सूचियाँ छोटी होती हैं और पूरी आती हैं; सिर्फ़ कुछ एंडपॉइंट में पैरामीटर हैं:

शॉर्ट लिंक के sort के लिए created_desc, created_asc, redirects_desc और redirects_asc हैं; q स्लग, शीर्षक और लक्ष्य URL में खोजता है (100 अक्षर तक, बड़े-छोटे अक्षरों से फ़र्क नहीं पड़ता)। आँकड़ों के लिए period 24h, 7d, 30d, 90d, this_month, last_month, last_30d और custom स्वीकार करता है; इसकी जगह आप from और to भेज सकते हैं। granularity hour या day होती है।

#Request ID और भाषा

• हर जवाब में X-Request-Id हेडर होता है – सपोर्ट से संपर्क करते समय इसे शामिल करें
• अगर आप ख़ुद X-Request-Id हेडर भेजते हैं, तो API उसे इस्तेमाल करता है
• message में त्रुटि टेक्स्ट वर्कस्पेस के मालिक के अकाउंट की भाषा में होता है, नहीं तो Accept-Language के हिसाब से; error का कोड हमेशा वही रहता है

#ब्राउज़र से कॉल करना?

तकनीकी रूप से API ब्राउज़र से कॉल की अनुमति देता है (CORS)। लेकिन key secret कभी भी ऐसे कोड में नहीं होना चाहिए जो विज़िटर की तरफ़ चलता है – न किसी वेबसाइट में, न किसी ऐप में। API को हमेशा अपने सर्वर से कॉल करें।

#प्लान

हर प्लान पर API कॉल का कोई कोटा नहीं है। सिर्फ़ प्रति मिनट की रेट लिमिट लागू होती हैं। आपके प्लान की कंटेंट सीमाएँ – जैसे पेज, लिंक या हर पेज पर ब्लॉक – API से भी वैसे ही लागू होती हैं जैसे डैशबोर्ड में। देखें प्लान की तुलना।

#आपकी पहली कॉल

# key के बदले टोकन लें
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# पेजों की सूची (स्कोप read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

लिंक जोड़ने, डिज़ाइन बदलने और पब्लिश करने वाला पूरा उदाहरण API से पेज अपडेट करें में है।