Cursor APIs का अवलोकन

Cursor आपकी टीम के डेटा, AI-संचालित कोडिंग एजेंट्स और एनालिटिक्स तक प्रोग्रामेटिक पहुंच के लिए कई API उपलब्ध कराता है।

उपलब्ध APIs

Cloud Agents API और SDKs Cursor एजेंट वर्कफ़्लो (वर्कस्पेस संदर्भ, उपकरण, कमांड और संपादन) चलाते हैं। ये स्टैंडअलोन मॉडल-इन्फ़रेंस या चैट-कम्प्लीशंस API नहीं हैं। Auto / auto-smart का उपयोग करने पर Cursor Router उन एजेंट रन के लिए मॉडल चुनता है; TypeScript SDK में Router या Python SDK देखें।

प्रमाणीकरण

सभी Cursor APIs बेसिक ऑथेंटिकेशन स्वीकार करते हैं। Cloud Agents API Bearer टोकन भी स्वीकार करता है — अपने HTTP क्लाइंट के लिए जो अधिक सुविधाजनक हो, उसे चुनें।

बेसिक ऑथेंटिकेशन

बेसिक ऑथेंटिकेशन में अपना API key उपयोगकर्ता नाम के रूप में इस्तेमाल करें (पासवर्ड खाली छोड़ दें):

curl https://api.cursor.com/teams/members \  -u YOUR_API_KEY:

या Authorization हेडर सीधे सेट करें:

Authorization: Basic {base64_encode('YOUR_API_KEY:')}

Bearer प्रमाणीकरण (Cloud Agents API)

Cloud Agents API Authorization: Bearer <key> हेडर भी स्वीकार करता है। दोनों तरीके एक ही तरह काम करते हैं — आपके HTTP क्लाइंट के लिए जो आसान हो, उसका उपयोग करें:

curl https://api.cursor.com/v1/me \  -H "Authorization: Bearer YOUR_API_KEY"

API कुंजियाँ बनाना

टीम एडमिन डैशबोर्ड के API कुंजियाँ पृष्ठ से API कुंजियाँ बना और प्रबंधित कर सकते हैं।

एडमिन API & AI Code Tracking API

1. cursor.com/dashboard → API कुंजियाँ पर जाएँ
2. New API Key पर क्लिक करें
3. अपनी कुंजी को एक स्पष्ट नाम दें (उदाहरण के लिए, "उपयोग डैशबोर्ड इंटीग्रेशन")
4. जनरेट की गई कुंजी को तुरंत कॉपी करें। यह दोबारा नहीं दिखाई जाएगी

कुंजी प्रारूप: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

आवश्यक स्कोप: admin:*

Analytics API

Cursor डैशबोर्ड → API कुंजियाँ से API key बनाएँ।

Cloud Agents API

Cursor डैशबोर्ड → API कुंजियाँ से उपयोगकर्ता API key बनाएँ या टीम सेटिंग्स से सर्विस अकाउंट API key का उपयोग करें।

रेट सीमाएँ

उचित उपयोग और सिस्टम की स्थिरता सुनिश्चित करने के लिए सभी API में रेट लिमिटिंग लागू होती है। रेट सीमाएँ प्रत्येक टीम के लिए लागू होती हैं और हर मिनट रीसेट होती हैं।

API के अनुसार दर सीमाएँ

रेट लिमिट प्रतिक्रिया

रेट लिमिट से अधिक अनुरोध करने पर, आपको 429 Too Many Requests प्रतिक्रिया मिलेगी:

{  "error": "Too Many Requests",  "message": "Rate limit exceeded. Please try again later."}

कैशिंग

कई API, बैंडविड्थ उपयोग कम करने और प्रदर्शन बेहतर बनाने के लिए ETag के साथ HTTP कैशिंग का समर्थन करते हैं।

समर्थित APIs

• Analytics API: सभी एंडपॉइंट्स (टीम-स्तरीय और by-user दोनों) HTTP कैशिंग समर्थित करते हैं
• AI Code Tracking API: एंडपॉइंट्स HTTP कैशिंग समर्थित करते हैं

कैशिंग कैसे काम करती है

1. प्रारंभिक अनुरोध: किसी भी समर्थित endpoint पर अनुरोध भेजें
2. प्रतिक्रिया में ETag शामिल होता है: API प्रतिक्रिया में ETag हेडर लौटाता है
3. बाद के अनुरोध: ETag मान को If-None-Match हेडर में शामिल करें
4. 304 Not Modified: अगर डेटा नहीं बदला है, तो आपको बिना बॉडी के 304 Not Modified प्रतिक्रिया मिलेगी

उदाहरण

# प्रारंभिक अनुरोधcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -D headers.txt# प्रतिक्रिया में शामिल है: ETag: "abc123xyz"# ETag के साथ अगला अनुरोधcurl -X GET "https://api.cursor.com/analytics/team/dau" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "If-None-Match: \"abc123xyz\""# डेटा में बदलाव न होने पर 304 Not Modified लौटाता है

कैश की अवधि

• कैश की अवधि: 15 मिनट (Cache-Control: public, max-age=900)
• प्रतिक्रियाओं में ETag हेडर शामिल होता है
• डेटा में बदलाव न होने पर 304 Not Modified पाने के लिए बाद के अनुरोधों में If-None-Match हेडर शामिल करें

लाभ

• बैंडविड्थ का उपयोग कम होता है: 304 प्रतिक्रियाओं में कोई बॉडी नहीं होती
• तेज़ प्रतिक्रियाएँ: अपरिवर्तित डेटा को प्रोसेस करने से बचता है
• रेट लिमिट के अनुकूल: 304 प्रतिक्रियाएँ रेट लिमिट में नहीं गिनी जातीं
• बेहतर प्रदर्शन: खासकर बार-बार poll किए जाने वाले एंडपॉइंट्स के लिए उपयोगी

सर्वोत्तम प्रथाएँ

1. एक्सपोनेंशियल बैकऑफ लागू करें

429 प्रतिक्रिया मिलने पर, पुनः प्रयास करने से पहले हर बार बढ़ते विलंब के साथ प्रतीक्षा करें:

import timeimport requestsdef make_request_with_backoff(url, headers, max_retries=5):    for attempt in range(max_retries):        response = requests.get(url, headers=headers)                if response.status_code == 429:            # एक्सपोनेंशियल बैकऑफ: 1 सेकंड, 2 सेकंड, 4 सेकंड, 8 सेकंड, 16 सेकंड            wait_time = 2 ** attempt            print(f"Rate limited. Waiting {wait_time}s before retry...")            time.sleep(wait_time)            continue                    return response        raise Exception("Max retries exceeded")

2. अनुरोधों को समय के साथ बाँटें

एक साथ बहुत सारे अनुरोध भेजने के बजाय, अपने API कॉल को समय के साथ फैलाएँ:

• बैच जॉब्स को अलग-अलग अंतरालों पर चलाने के लिए अनुसूची बनाएँ
• बड़े डेटासेट संसाधित करते समय अनुरोधों के बीच विलंब जोड़ें
• ट्रैफ़िक में अचानक बढ़ोतरी को कम करने के लिए कतार प्रणाली का उपयोग करें

3. कैशिंग का लाभ उठाएँ

Analytics API और AI Code Tracking API के लिए:

ये API, ETags के साथ HTTP कैशिंग का समर्थन करते हैं। ETags का उपयोग करके बैंडविड्थ उपयोग कम करने और अनावश्यक अनुरोधों से बचने के तरीके के विवरण के लिए ऊपर दिया गया कैशिंग अनुभाग देखें।

मुख्य लाभ:

• बैंडविड्थ उपयोग कम होता है
• डेटा में बदलाव न होने पर तेज़ प्रतिक्रियाएँ
• रेट सीमाओं में नहीं गिना जाता (304 प्रतिक्रियाओं के लिए)

Analytics API में बेहतर कैशिंग समर्थन के लिए timestamps के बजाय date shortcuts (7d, 30d) का उपयोग करें।

4. अपने उपयोग की निगरानी करें

सीमाओं के भीतर रहने के लिए अपने अनुरोध पैटर्न ट्रैक करें:

• API कॉल के टाइमस्टैंप और प्रतिक्रिया कोड लॉग करें
• 429 प्रतिक्रियाओं के लिए अलर्ट सेट अप करें
• दैनिक/साप्ताहिक उपयोग के रुझानों की निगरानी करें
• वास्तविक आवश्यकताओं के आधार पर पोलिंग अंतराल समायोजित करें

5. बैचिंग समझदारी से करें

पेजिनेशन वाले एंडपॉइंट्स के लिए:

• हर अनुरोध में अधिक डेटा पाने के लिए उपयुक्त पृष्ठ आकार का उपयोग करें
• Analytics API के उपयोगकर्ता-आधारित endpoints के लिए: विशिष्ट उपयोगकर्ताओं को फ़िल्टर करने के लिए users पैरामीटर का उपयोग करें
• बड़े डेटा निष्कर्षण के लिए: उपलब्ध होने पर CSV एंडपॉइंट्स का उपयोग करें (ये डेटा को कुशलता से स्ट्रीम करते हैं)

6. उचित अंतराल पर पोल करें

जो एंडपॉइंट्स कम बार अपडेट होते हैं, उन्हें जरूरत से ज़्यादा पोल न करें:

• एडमिन API /teams/daily-usage-data: अधिकतम हर घंटे एक बार पोल करें (डेटा हर घंटे एग्रीगेट किया जाता है)
• एडमिन API /teams/filtered-usage-events: अधिकतम हर घंटे एक बार पोल करें (डेटा हर घंटे एग्रीगेट किया जाता है)
• एडमिन API /organizations/pooled-usage: अधिकतम हर घंटे एक बार पोल करें (डेटा हर घंटे एग्रीगेट किया जाता है)
• एडमिन API /organizations/filtered-usage-events: अधिकतम हर घंटे एक बार पोल करें (डेटा हर घंटे एग्रीगेट किया जाता है)
• Analytics API: बेहतर कैशिंग सहायता के लिए date shortcuts (7d, 30d) का उपयोग करें
• AI Code Tracking API: डेटा लगभग रीयल-टाइम में इनजेस्ट किया जाता है, लेकिन हर कुछ मिनट में पोल करना पर्याप्त है

7. त्रुटियों को प्रभावी ढंग से संभालें

सभी API कॉल के लिए उचित त्रुटि प्रबंधन लागू करें:

async function fetchAnalytics(endpoint) {  try {    const response = await fetch(`https://api.cursor.com${endpoint}`, {      headers: {        'Authorization': `Basic ${btoa(API_KEY + ':')}`      }    });        if (response.status === 429) {      // दर-सीमित - बैकऑफ लागू करें      throw new Error('Rate limit exceeded');    }        if (response.status === 401) {      // अमान्य API key      throw new Error('Authentication failed');    }        if (response.status === 403) {      // अपर्याप्त अनुमतियाँ      throw new Error('Enterprise access required');    }        if (!response.ok) {      throw new Error(`API error: ${response.status}`);    }        return await response.json();  } catch (error) {    console.error('API request failed:', error);    throw error;  }}

सामान्य त्रुटि प्रतिक्रियाएँ

सभी API मानक HTTP स्थिति कोड का उपयोग करती हैं:

400 अमान्य अनुरोध

अनुरोध के पैरामीटर अमान्य हैं या आवश्यक फ़ील्ड मौजूद नहीं हैं।

{  "error": "Bad Request",  "message": "Some users are not in the team"}

401 अनधिकृत

API key अमान्य है या मौजूद नहीं है।

{  "error": "Unauthorized",  "message": "Invalid API key"}

403 निषिद्ध

API key मान्य है, लेकिन अनुमतियाँ अपर्याप्त हैं (उदाहरण के लिए, गैर-एंटरप्राइज़ प्लान पर एंटरप्राइज़ सुविधाएँ)।

{  "error": "Forbidden",  "message": "Enterprise access required"}

404 नहीं मिला

अनुरोधित resource मौजूद नहीं है।

{  "error": "Not Found",  "message": "Resource not found"}

429 बहुत ज़्यादा अनुरोध

रेट लिमिट पार हो गई। एक्सपोनेंशियल बैकऑफ लागू करें।

{  "error": "Too Many Requests",  "message": "Rate limit exceeded. Please try again later."}

500 आंतरिक सर्वर त्रुटि

सर्वर की ओर से त्रुटि। समस्या बनी रहने पर सहायता से संपर्क करें।

{  "error": "Internal Server Error",  "message": "An unexpected error occurred"}