सार्वजनिक API और API कुंजियाँ

1. अवलोकन

MousePlayer API से वर्कस्पेस डेटा अपने डैशबोर्ड, वेयरहाउस या आंतरिक टूल में लें। ग्राहक ID जोड़ने (identify, लिखने की कुंजी चाहिए; कुंजी दायरे देखें) के अलावा यह है: केवल पढ़ने के लिए: API से डेटा बदल या हटा नहीं सकते।

आधार URL: https://www.mouseplayer.com/api/v1/
सभी उत्तर JSON हैं।
हर अनुरोध API कुंजी से प्रमाणित और उसके वर्कस्पेस तक सीमित है — एक वर्कस्पेस की कुंजी दूसरे का डेटा गलती से भी नहीं देख सकती।
पूरी सत्र रिकॉर्डिंग (माउस गतिविधि, DOM स्नैपशॉट) API में नहीं मिलती। सत्र मेटाडेटा, पृष्ठ दृश्य, कस्टम इवेंट और सेगमेंट मिलते हैं — मूल रिकॉर्डिंग डेटा भेजे बिना रिपोर्ट बनाने को पर्याप्त।

2. प्रमाणीकरण

खाता मेनू में यहाँ API कुंजी बनाएँ और प्रबंधित करें: API कुंजी (/api-keys)। केवल वर्कस्पेस स्वामी और व्यवस्थापक बना या रद्द कर सकते हैं।

कुंजी गुप्त रखें। यह वर्कस्पेस की हर चीज़ पढ़ने देती है। पूरी कुंजी बनाने के तुरंत बाद केवल एक बार दिखती है — पासवर्ड मैनेजर या सीक्रेट वॉल्ट में रखें। खो जाए तो रद्द करके नई बनाएँ।

हर अनुरोध के इस हेडर में Bearer टोकन भेजें: Authorization :

# List projects in your workspace curl -H "Authorization: Bearer mp_live_..." \ https://www.mouseplayer.com/api/v1/projects

अनुपस्थित, ग़लत रूप या रद्द कुंजी को यह उत्तर मिलता है: 401 :

{ "error": "Invalid or missing API key. Use: Authorization: Bearer <key>" }

प्लान आवश्यकता

REST API इन प्लान में है: Business और Enterprise । प्लान वर्कस्पेस के स्वामी से लिया जाता है, इसलिए आमंत्रित सदस्य उसे पाते हैं। जाँच होती है हर अनुरोध पर, केवल कुंजी बनाते समय नहीं — डाउनग्रेड पर मौजूदा कुंजी काम रोकती और यह लौटाती है: 403।

कुंजी दायरे

हर कुंजी के उपसर्ग में दायरा है, इसलिए इसे देखकर काम समझें — इस जगह: .env, टिकट या टर्मिनल में।

उपसर्ग	अर्थ
`mp_ro_`	केवल पढ़ना। प्रोजेक्ट, सत्र, इवेंट और सेगमेंट पढ़ता है। बदलाव नहीं।
`mp_rw_`	पढ़ना और लिखना। ऊपर सब और identify एंडपॉइंट से ग्राहक ID जोड़ना।

बनाते समय दायरा चुनें; डिफ़ॉल्ट केवल पढ़ना। लिखने वाले एंडपॉइंट पर पढ़ने की कुंजी यह लौटाती है: 403 , संदेश में कुंजी का दायरा और एंडपॉइंट आवश्यकता बताती है। बाद में बदल नहीं सकते — नई बनाकर पुरानी रद्द करें।

3. अनुरोध सीमाएँ

हर API कुंजी की सीमा है प्रति मिनट 60 अनुरोध, चलती समय खिड़की में। पार होने पर खिड़की साफ़ होने तक यह मिलता है: 429 :

{ "error": "Rate limit exceeded. Max 60 requests per minute." }

अधिक सीमा चाहिए? यहाँ संपर्क करें: सहायता और उपयोग बताएँ।

4. एंडपॉइंट

GET/api/v1/projects

वर्कस्पेस के हर प्रोजेक्ट (ट्रैक प्रॉपर्टी) की सूची।

{ "data": [ { "channelid": "955a45df5ee842cb", "domain": "yourdomain.com", "status": "active", "total_traffic_bytes": 27304765, "created_at": "2026-07-19 22:06:39", "last_used": "2026-08-05 01:12:55" } ] }

GET/api/v1/projects/{channelid}/sessions

प्रोजेक्ट के रिकॉर्ड आगंतुक सत्र, सबसे नए पहले। पृष्ठों में।

क्वेरी पैरामीटर	विवरण
`page`	पृष्ठ नंबर, डिफ़ॉल्ट `1`।
`per_page`	प्रति पृष्ठ परिणाम, डिफ़ॉल्ट `25`, अधिकतम `100`।
`since`	केवल इस तारीख़ से/बाद शुरू सत्र (`YYYY-MM-DD`)।
`until`	केवल इस तारीख़ तक/पहले शुरू सत्र।

{ "data": [ { "session_id": "s_kfmist058_1785795295504", "visitor_id": "v_sv90jdpzo_1785795296042", "custom_user_id": null, "country": "DE", "device_type": "desktop", "is_bot": 0, "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105 } ], "pagination": { "page": 1, "per_page": 25, "total": 142, "total_pages": 6 } }

GET/api/v1/sessions/{session_id}

एक सत्र का मेटाडेटा और पृष्ठ दृश्य। पूरा रिकॉर्डिंग डेटा जानबूझकर बाहर — उसके लिए डैशबोर्ड प्लेयर लें।

{ "data": { "session_id": "s_kfmist058_1785795295504", "channelid": "955a45df5ee842cb", "visitor_id": "v_sv90jdpzo_1785795296042", "country": "DE", "asn_org": "Deutsche Telekom AG", "referrer": "https://duckduckgo.com/", "device_type": "desktop", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105, "pageviews": [ { "pageview_id": 1199, "url": "https://yourdomain.com/pricing", "page_title": "Pricing", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41" } ] } }

GET/api/v1/sessions/{session_id}/events

सत्र के कस्टम इवेंट (वही जो इससे भेजते हैं: mp('event', ...)), पैरामीटर सहित।

{ "data": [ { "event_id": 61, "pageview_id": 1199, "event_name": "add_to_cart", "created_at": "2026-08-04 00:14:59", "params": { "item_id": "SKU_98765", "price": 299.99 } } ] }

GET/api/v1/projects/{channelid}/segments

प्रोजेक्ट के आगंतुक सेगमेंट, प्रोजेक्ट और पूरे वर्कस्पेस दोनों।

{ "data": [ { "segment_id": 4, "name": "High Intent Visitors", "description": "Pageviews > 5", "badge_color": "cyan", "is_global": 0, "created_at": "2026-08-03 00:00:43" } ] }

5. बैकएंड से ग्राहक ID जोड़ना

ब्राउज़र अक्सर व्यक्ति नहीं जानता। B2B में लॉगिन के बाद बैकएंड में पहचान तय है — स्टोर में ऑर्डर पुष्टि पर। यह एंडपॉइंट उसी क्षण के लिए है।

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

ID सत्र सूची में आती और खोजी जाती है; यह वेबहुक चलता है: session_identified — जिससे CRM तक पहुँचती है।

समान ID से दो बार बुलाना सुरक्षित। उत्तर में यह आता है: "changed": false और वेबहुक नहीं जाता। दोहराया ऑर्डर दूसरी लीड नहीं बनाता।

स्थिति	कब
`400`	फ़ील्ड नहीं, `user_id` 128 अक्षर से अधिक या नियंत्रण चिह्न। काटने के बजाय अस्वीकारते हैं — छोटी हुई ID CRM में नहीं मिलेगी पर सफलता लगेगी।
`404`	सत्र नहीं है या आपके वर्कस्पेस का नहीं। जानबूझकर दोनों का समान उत्तर।
`403`	वर्कस्पेस प्लान में API नहीं।

6. वेबहुक: सिग्नेचर जाँच

हर प्रोजेक्ट में यहाँ वेबहुक कॉन्फ़िगर होते हैं: इंटीग्रेशन, वहीं साइनिंग सीक्रेट है। हर डिलीवरी में ये हेडर:

हेडर	अर्थ
`X-MousePlayer-Event`	इवेंट नाम, जैसे `session_identified`
`X-MousePlayer-Timestamp`	Unix सेकंड — हस्ताक्षर पाठ का हिस्सा
`X-MousePlayer-Attempt`	पहली कोशिश में 1, दोबारा में अधिक
`X-MousePlayer-Signature`	`sha256=<hex>`

सिग्नेचर इस पर HMAC-SHA256 है: timestamp + "." + raw body, कुंजी आपके प्रोजेक्ट की साइनिंग सीक्रेट है।

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

हस्ताक्षर इस बॉडी पर करें: मूल , JSON पार्सिंग से पहले। फिर सीरियलाइज़ करने पर कुंजी क्रम और रिक्त स्थान बदलते हैं, सिग्नेचर नहीं मिलेगा। कुछ मिनट से पुराने टाइमस्टैम्प भी अस्वीकारें — उसी के लिए है।

डिलीवरी और दोबारा कोशिश

विफल डिलीवरी के बाद प्रयास: 1 मिनट, 5 मिनट, 15 मिनट, 1 घंटा और 6 घंटे, फिर छोड़ते हैं। 4xx इन उत्तरों में इसके अलावा: 408 और 429 , नहीं दोहराते — अर्थ "ऐसे नहीं" है, "अभी नहीं" नहीं। यह जल्दी लौटाएँ: 2xx और बाद में काम करें; 10 सेकंड में डिलीवरी टाइमआउट होती है।

उपलब्ध इवेंट

इवेंट	कब चलता है
`session_identified`	सत्र को पहली ग्राहक ID मिलने पर — ब्राउज़र या API से
`session_ended`	सत्र बंद होने पर एक बार
`goal_reached`	कस्टम इवेंट लक्ष्य पूरा करे तो प्रति सत्र एक बार। केवल "event" प्रकार के लक्ष्य — URL, अवधि, पृष्ठ दृश्य और फ़नल नहीं जाँचे जाते। इसमें है: `goal_id`, `goal_name`, `goal_value` और `currency`।
`high_value_session`	आगंतुक किसी दिन इस प्रोजेक्ट की मूल्य सीमा पहली बार पार करे। सीमा आपके स्कोर वितरण से बनती है (पिछले 90 दिनों का 90वाँ प्रतिशतक), तय संख्या नहीं और कम से कम 20 स्कोर वाले आगंतुक तक बनती नहीं। इसमें है: `visitor_id`, `value_score`, `threshold` और उस दिन का सबसे देखने योग्य सत्र।
`funnel_dropoff`	फ़नल में आया पर पूरा न करने वाला सत्र समाप्त होने पर। रुकने वाला चरण बताता है (`dropped_at`)। छोड़ना इवेंट की अनुपस्थिति है, इसलिए सत्र समाप्त होने पर ही पता चलता है। फ़नल में न आए सत्र छोड़ना नहीं हैं और नहीं चलते।
`high_friction_session`	बाधा स्कोर पहली बार सीमा (डिफ़ॉल्ट 60 / 100) पाए तो प्रति सत्र एक बार। इसमें है: `friction_score`, उसके संकेत (`reasons`) और सीमा पार कराने वाला संकेत (`trigger`)।
`element_broken`	ट्रैक एलिमेंट कई दिन तक किसी जाँचे पृष्ठ दृश्य में न मिले तो एक बार — आम तौर पर रीलॉन्च के बाद। फिर तभी चलता है जब चिह्न मिला और दोबारा टूटा। यह इवेंट किसी सत्र का नहीं: `session_id` और `session_url` हैं `null`, `link_url` इसके बजाय चिह्न खोलता है और `subject_id` चिह्न नाम देता है — हर संस्करण में समान, ताकि नया टूटा चयनकर्ता खुले मामले से जुड़े। इसमें है: `rule_id`, `rule_name`, `selector`, `page`, `checked_page_views`, `window_days` और `last_matched`। आगंतुक डेटा नहीं।
`element_recovered`	इसका समाधान संकेत: `element_broken`: चिह्न वास्तव में एलिमेंट फिर पाए तभी — कम पृष्ठ दृश्य पर्याप्त नहीं। केवल तब भेजता है जब `element_broken` वेबहुक से गया हो; अपना स्विच नहीं: इसकी सदस्यता में `element_broken` यह शामिल है। समान `subject_id`, इसलिए PagerDuty मामला हल और Opsgenie अलर्ट बंद करता है। अतिरिक्त: `matched_page_views` और `checked_page_views` ।
`anomaly_detected`	पिछले दिन का उससे पहले के 28 दिनों से स्पष्ट अंतर हो तो रोज़ एक बार: बहुत कम या अधिक सत्र, घटी लक्ष्य दर, अधिक बाधा या JS त्रुटि वाले सत्र। समान मेट्रिक और दिशा एक सप्ताह शांत (बदलने योग्य)। यह इवेंट किसी सत्र का नहीं: `session_id` और `session_url` हैं `null`, `link_url` प्रोजेक्ट अवलोकन खोलता है और `subject_id` मेट्रिक, दिशा और दिन बताता है। इसमें है: `metric` (`sessions`, `goal_rate`, `friction_rate`, `js_error_rate`, `lcp_p75`, `inp_p75`, `cls_p75`), `direction`, `day`, `value`, `expected`, `sessions`, `robust_z`, `z_score` और पढ़ने योग्य `summary` और `hint`। आगंतुक डेटा नहीं। Web Vitals के लिए, `measurements` इसकी जगह है: `sessions`, और `page` (पूरी साइट के लिए खाली) तथा `device` (`desktop` या `mobil`) जगह बताते हैं; `link_url` तब Web Vitals टैब खोलता है।
`rage_click`	गुस्से में बार-बार क्लिक मिलने पर
`error_detected`	फ़्रंटएंड अपवाद पर
`ce`	अपने कस्टम इवेंट की सामूहिक सदस्यता। इसमें नहीं आते ऊपर के इवेंट — उनके अपने स्विच हैं।

7. त्रुटियाँ & स्थिति कोड

स्थिति	अर्थ
`200`	सफलता।
`401`	अनुपस्थित, गलत रूप या रद्द API कुंजी।
`404`	माँगा प्रोजेक्ट या सत्र मौजूद नहीं या आपके वर्कस्पेस का नहीं।
`429`	अनुरोध सीमा पार — इस कुंजी से प्रति मिनट 60 से अधिक भेज रहे हैं।
`403`	वर्कस्पेस प्लान में REST API नहीं। संदेश आवश्यक और वर्तमान प्लान बताता है।

8. सुरक्षा नोट

पढ़ने की कुंजी (mp_ro_) कुछ नहीं बदल सकती। लिखने की कुंजी (mp_rw_) केवल ग्राहक ID जोड़ सकती है; कोई कुंजी डेटा हटा या मूल रिकॉर्डिंग एक्सपोर्ट नहीं कर सकती।
हर अनुरोध कुंजी के वर्कस्पेस तक सीमित — दूसरी वर्कस्पेस ID देकर किसी का डेटा नहीं देख सकते।
कभी भी यहाँ से रद्द करें: /api-keys; तुरंत लागू।
API कुंजी पासवर्ड जैसी रखें। गलती से सार्वजनिक रिपॉज़िटरी में कमिट हो तो तुरंत रद्द करके नई बनाएँ।

सीमित इवेंट पृष्ठ (API v1, 14 अक्टूबर 2026)

GET /api/v1/sessions/{session_id}/events डिफ़ॉल्ट अधिकतम 100 इवेंट देता है। per_page को 1 से 100 पूर्णांक रखें। अगले अनुरोध में cursor अपरिवर्तित भेजकर pagination.next_cursor का पालन करें; समान सत्र और वर्कस्पेस रखें। क्रम created_at और event_id से है। कर्सर हस्ताक्षरित और सत्र/वर्कस्पेस से बँधे हैं। कुल संख्या या संख्यात्मक पृष्ठ नहीं मिलता।

मौजूदा data ऐरे और params मैप रहते हैं। pagination.returned वास्तविक लौटाई संख्या है; pagination.has_more अगले पृष्ठ का संकेत। पूरा होने पर next_cursor null है। उत्तर अधिकतम 524288 बाइट, इसलिए per_page से कम इवेंट हो सकते हैं। प्रति इवेंट अधिकतम 128 पैरामीटर पंक्तियाँ; अधिक हों तो params_truncated true है। अलग स्ट्रिंग की डेटाबेस सीमा 255 अक्षर है। कटे पैरामीटर इस एंडपॉइंट में नहीं मिलते। per_page घटाने से पैरामीटर सीमा नहीं बढ़ती।

अमान्य पृष्ठ आकार, बदले या दूसरे सत्र/वर्कस्पेस के कर्सर पर 400। बड़ा व्यक्तिगत इवेंट डेटा 413 देता है। मौजूदा पहुँच जाँच 401, 403, 404 या 409 लागू अनुसार देती हैं।

सीमा प्रति API कुंजी प्रति मिनट 60 प्रमाणित अनुरोध। समाप्ति पर 429 और Retry-After: 60। Redis या limiter अनुपलब्ध हो तो 503 और Retry-After: 5; सीमा बिना कभी स्वीकार नहीं। Retry-After मानें और यादृच्छिक विलंब जोड़ें; तेज़ चक्र में न दोहराएँ। इवेंट डेटाबेस विफलता भी 503। कर्सर स्नैपशॉट स्थिर नहीं करते: पुराने टाइमस्टैम्प वाले साथ के insert के लिए नया स्कैन चाहिए हो सकता है।

GET /api/v1/sessions/s_example/events?per_page=25
GET /api/v1/sessions/s_example/events?per_page=25&cursor=SIGNED_CURSOR

/api/v1/native नेटिव SDK पूर्वावलोकन का केवल Dev बैकएंड नियंत्रण रास्ता है। प्रोडक्शन में अक्षम। बैकएंड Bearer कुंजी को list/replay के लिए पढ़ना और register/grant/delete/disable के लिए लिखना चाहिए। अतिरिक्त नेटिव पूर्वावलोकन उपलब्धता जाँच लागू हैं। मोबाइल ऐप में स्थायी वर्कस्पेस API कुंजी कभी एम्बेड न करें।

हम कैसे मदद कर सकते हैं?