---
title: REST API
description: अपने NexCMP इंस्टॉलेशन की कस्टमर API को कॉल करें: प्रमाणीकरण, इंटरैक्टिव संदर्भ, OpenAPI और पोस्टमैन डाउनलोड, त्रुटियाँ, दर सीमाएँ, इडपोटेंसी और कर्ल उदाहरण।
url: https://nexcmp.com/hi/docs/developers/api/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# REST API

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

## यह क्या करता है {#what-it-does}

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

## आवश्यकताएं {#requirements}

| आइटम | आवश्यकता |
|---|---|
| सार्वजनिक HTTPS पता | API आपके मुख्य डोमेन (और प्रत्येक रीसेलर के अपने डोमेन) पर परोसा जाता है। |
| एक API कुंजी | पोर्टल में ग्राहक द्वारा बनाई गई; [API keys](https://nexcmp.com/hi/docs/developers/api-keys/) देखें। |
| डिपेंडेंसी | कोई नहीं। किसी ऐसे मॉड्यूल के एंडपॉइंट जिसे आपने सक्षम नहीं किया है (उदाहरण के लिए Kubernetes या Object Storage) संदर्भ से छिपाए जाते हैं और अस्वीकार कर दिए जाते हैं। |

## बुनियादी ढांचा तैयार करें {#prepare-the-infrastructure}

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

## NexCMP में कनेक्ट करें {#connect-in-nexcmp}

### इंटरैक्टिव संदर्भ {#the-interactive-reference}

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


### डाउनलोड और मशीन-पठनीय दस्तावेज़ {#downloads-and-machine-readable-documents}

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

| 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` की आवश्यकता है। |

```bash
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 {#authentication}

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

```bash
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](https://nexcmp.com/hi/docs/developers/api-keys/) देखें।
- `GET /v1/apikeys/self` के साथ की की जाँच करें: यह कॉलिंग की का नाम, स्कोप, समाप्ति और शेष रेट-लिमिट अनुमति (हर की इसे कॉल कर सकती है) लौटाता है।

### Examples {#examples}

```bash
# 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 {#errors}

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

```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](https://nexcmp.com/hi/docs/billing/quotas/) तक पहुँच गया है; प्ररूपित सत्र में कार्रवाई की अनुमति नहीं है। |
| 404 | `not_found` | नहीं मिला — किसी अन्य के स्वामित्व वाले संसाधनों के लिए भी लौटाया जाता है। |
| 422 | `invalid_argument` | सत्यापन त्रुटि (प्रतिक्रिया में नामित फ़ील्ड)। |
| 429 | `rate_limited` | बहुत सारे अनुरोध; `Retry-After` की प्रतीक्षा करें। |
| 503 | `maintenance` | रखरखाव मोड चालू है: रीड काम करते हैं, राइट अस्वीकार कर दिए जाते हैं। |

### Rate limits {#rate-limits}

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

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

### Idempotency {#idempotency}

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

## सत्यापित करें {#verify}

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

   ```bash
   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 {#limits-notes}

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

## ट्रबलशूटिंग {#troubleshooting}

| लक्षण | कारण | सुधार |
|---|---|---|
| नई कुंजी पर 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 में मॉड्यूल सक्षम करें। |