REST API

पोर्टल में कहाँ: https://<your-domain>/apidoc पर API संदर्भ (सार्वजनिक) और /api-keys पर API कुंजियाँ। एडमिन में कहाँ: Customers › API keys (/customers/apikeys) ग्राहकों द्वारा बनाई गई कुंजियों की सूची दिखाता है।

यह क्या करता है

पोर्टल में ग्राहक जो भी कार्रवाई कर सकता है — VM की सूची देखना और नियंत्रित करना, चालान पढ़ना, SSH कुंजियाँ, Kubernetes, स्टोरेज, सपोर्ट टिकट प्रबंधित करना — वह https://<your-domain>/v1/ के अंतर्गत एक वर्شन्ड REST API के माध्यम से उपलब्ध है। ग्राहक इसे स्कोप किए गए API key के साथ स्क्रिप्ट और CI से कॉल करते हैं। यही API cmp command-line tool और MCP server को फीड करता है, और संदर्भ चल रहे इंस्टॉलेशन से जनरेट होता है, इसलिए यह हमेशा उन सुविधाओं की सटीक सूची दिखाता है जिन्हें आपने चालू किया है।

आवश्यकताएं

आइटम	आवश्यकता
सार्वजनिक HTTPS पता	API आपके मुख्य डोमेन (और प्रत्येक रीसेलर के अपने डोमेन) पर परोसा जाता है।
एक API कुंजी	पोर्टल में ग्राहक द्वारा बनाई गई; API keys देखें।
डिपेंडेंसी	कोई नहीं। किसी ऐसे मॉड्यूल के एंडपॉइंट जिसे आपने सक्षम नहीं किया है (उदाहरण के लिए Kubernetes या Object Storage) संदर्भ से छिपाए जाते हैं और अस्वीकार कर दिए जाते हैं।

बुनियादी ढांचा तैयार करें

इंस्टॉल करने के लिए कुछ नहीं। यदि NexCMP के सामने कोई रिवर्स प्रॉक्सी है, तो /v1/, /mcp, /cli/ और /apidoc को पैनल पर अग्रेषित करें (इंस्टॉलर का nginx कॉन्फ़िगरेशन पहले से ही ऐसा करता है)।

NexCMP में कनेक्ट करें

इंटरैक्टिव संदर्भ

https://cloud.example.com/apidoc खोलें (होस्ट को अपने डोमेन से बदलें; रीसेलर के ग्राहकों को रीसेलर के नाम के साथ रीसेलर के डोमेन पर संदर्भ दिखाई देता है)। इसमें curl, cmp CLI, JavaScript, Python और Go में अनुरोध और प्रतिक्रिया उदाहरणों के साथ एंडपॉइंट दस्तावेज़ीकरण, एक खोज बॉक्स (Ctrl या Cmd + K), और एक Try it पैनल है। Try it केवल उसी साइट पर अनुरोध भेजता है, आगंतुकों द्वारा चिपकाई गई कुंजी के साथ (ब्राउज़र सत्र में रखी जाती है); यह डिफ़ॉल्ट रूप से केवल पढ़ने के लिए (read-only) है, और लिखने या सशुल्क कॉलों के लिए अतिरिक्त स्विच और पुष्टि की आवश्यकता होती है।

डाउनलोड और मशीन-पठनीय दस्तावेज़

सभी सार्वजनिक हैं, किसी कुंजी की आवश्यकता नहीं है और प्रति साइट जनरेट होते हैं:

URL	सामग्री
/apidoc	इंटरैक्टिव संदर्भ।
/v1/public/openapi.json	OpenAPI 3.1 दस्तावेज़।
/v1/public/openapi.yaml	वही, YAML।
/v1/public/postman.json	पोस्टमैन कलेक्शन।
/v1/public/insomnia.json	Insomnia निर्यात।
/v1/public/api.md	एक Markdown फ़ाइल के रूप में संदर्भ।
/v1/public/api-catalog	लाइट JSON: ब्रांड, बेस URL, की प्रीफिक्स, हर स्कोप और हर एंडपॉइंट मेथड, पाथ, स्कोप और इसके साथ कि क्या इसके लिए Idempotency-Key की आवश्यकता है।

curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

Postman में Import › Link चुनें और https://cloud.example.com/v1/public/postman.json पेस्ट करें। संदर्भ पृष्ठ JavaScript और Python के लिए वन-फाइल API क्लाइंट भी प्रदान करता है।

Authentication

की को Authorization हेडर में भेजें:

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

• ग्राहक की vk_ से शुरू होती हैं। की साइट-बाउंड हैं: cloud.example.com पर बनाई गई की रीसेलर डोमेन पर काम नहीं करती है।
• ब्राउज़र सेशन टोकन (pt_...) केवल पोर्टल के लिए हैं; ऑटोमेशन के लिए की का उपयोग करें।
• की के स्कोप तय करते हैं कि वह क्या कॉल कर सकती है; एक छूटा हुआ स्कोप HTTP 403 scope_required उत्तर देता है। API keys देखें।
• GET /v1/apikeys/self के साथ की की जाँच करें: यह कॉलिंग की का नाम, स्कोप, समाप्ति और शेष रेट-लिमिट अनुमति (हर की इसे कॉल कर सकती है) लौटाता है।

Examples

# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

/apidoc से प्रत्येक ऑपरेशन के सटीक अनुरोध फ़ील्ड लें।

Errors

हर त्रुटि एक स्थिर code और एक पठनीय message के साथ JSON होती है:

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	Typical code	अर्थ
401	unauthenticated, key_invalid, key_revoked, key_expired, key_ip_denied, site_mismatch, api_keys_disabled	गायब या अज्ञात की, निरस्त, समाप्त, की की अनुमति सूची के बाहर कॉलर IP, किसी अन्य साइट की की, या API की बंद।
403	scope_required, endpoint_not_public, account_blocked, quota_exceeded, impersonate_forbidden	की में स्कोप नहीं है; एंडपॉइंट की के लिए उपलब्ध नहीं है; खाता लॉक है; quota तक पहुँच गया है; प्ररूपित सत्र में कार्रवाई की अनुमति नहीं है।
404	not_found	नहीं मिला — किसी अन्य के स्वामित्व वाले संसाधनों के लिए भी लौटाया जाता है।
422	invalid_argument	सत्यापन त्रुटि (प्रतिक्रिया में नामित फ़ील्ड)।
429	rate_limited	बहुत सारे अनुरोध; Retry-After की प्रतीक्षा करें।
503	maintenance	रखरखाव मोड चालू है: रीड काम करते हैं, राइट अस्वीकार कर दिए जाते हैं।

Rate limits

Limit	डिफ़ॉल्ट
Per key	प्रति मिनट 120 अनुरोध
प्रति खाता (सभी की एक साथ)	प्रति मिनट 300 अनुरोध

प्रत्येक प्रतिक्रिया में X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset होते हैं; 429 में Retry-After जुड़ जाता है।

Idempotency

ऐसे कमांड जिनकी कीमत चुकानी पड़ती है या जिन्हें दोहराया नहीं जा सकता (बनाना, प्लान बदलना, खरीदना, हटाना...) के लिए एक Idempotency-Key हेडर आवश्यक है (200 वर्णों तक की कोई भी स्ट्रिंग; UUID अच्छा काम करता है)। टाइमआउट के बाद वही की दोबारा भेजें और सर्वर ऑपरेशन को दोहराने के बजाय मूल परिणाम (Idempotency-Replayed: 1 के साथ) लौटाता है। किसी भिन्न कमांड के लिए की का पुन: उपयोग करने पर 422 उत्तर मिलता है; अभी भी प्रगति पर अनुरोध 409/Retry-After का उत्तर देता है। हेडर के बिना भुगतान कॉल अस्वीकार कर दी जाती है।

सत्यापित करें

1. पोर्टल में स्कोप vm:read के साथ एक की बनाएँ (API keys › Create key)।

2. Run:

   curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"

   आपको HTTP 200 और रेट-लिमिट हेडर मिलते हैं।

3. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" खाते के VM की सूची देता है। पोर्टल में की का Last used कॉलम और Key usage log कॉल दिखाते हैं।

Limits & notes

• की के लिए कभी भी उपलब्ध नहीं: टॉप-अप, निकासी, कार्ड बदलना या ऑटो टॉप-अप, पासवर्ड, ईमेल या 2FA बदलना, खाता हटाना, अन्य की बनाना, संपादित करना या निरस्त करना। इनके लिए साइन-इन ब्राउज़र सेशन की आवश्यकता होती है।
• छिपे हुए मॉड्यूल: संदर्भ और OpenAPI दस्तावेज़ केवल उस साइट पर सक्षम सुविधाओं को सूचीबद्ध करते हैं।
• प्रतिक्रिया आकार और पेजिंग: सूची एंडपॉइंट पेजेड होते हैं (page, per_page); प्रत्येक एंडपॉइंट के लिए OpenAPI दस्तावेज़ पढ़ें।
• समय और पैसा: जब तक फ़ील्ड का नाम अन्यथा न कहे, राशि USD सेंट में है।
• Admin API: एडमिन कंसोल का अपना System › Admin › API पृष्ठ और प्रशासन के लिए एडमिनिस्ट्रेटर की (ofw_...) हैं; वे यहाँ वर्णित ग्राहक API से अलग हैं।
• संस्करण: पथ उपসর্গ /v1 स्थिर है; प्रतिक्रियाओं में नए फ़ील्ड जोड़े जा सकते हैं।

ट्रबलशूटिंग

लक्षण	कारण	सुधार
नई कुंजी पर 401	অন্য डोमेन की कुंजी, समाप्त हो चुकी है, या स्पेस के साथ टाइप की गई है	उस डोमेन पर कुंजी बनाएँ जिसे आप कॉल करते हैं; Authorization: Bearer vk_... हेडर जाँचें।
403 scope_required	गायब स्कोप	पोर्टल में कुंजी संपादित करें और स्कोप जोड़ें।
401 key_ip_denied या site_mismatch	अन्य IP तक सीमित कुंजी ("allowed IPs") या अन्य डोमेन पर बनाई गई	कुंजी के स्वीकृत IP में अपने सर्वर का IP जोड़ें, या उस डोमेन पर कॉल करें जहाँ कुंजी बनाई गई थी।
मौजूदा VM पर 404	VM किसी अन्य खाते की है	मालिक की कुंजी का उपयोग करें।
Idempotency-Key माँगने वाला 400/422	हेडर के बिना भुगतान वाली कार्रवाई	Idempotency-Key: <uuid> जोड़ें।
429	सीमा से अधिक	पीछे हटें; Retry-After का उपयोग करें।
/apidoc अपेक्षा से कम दिखाता है	मॉड्यूल बंद है	License & updates में मॉड्यूल सक्षम करें।