सार्वजनिक API र API कुञ्जी

1. सारांश

आफ्नै ड्यासबोर्ड, डेटा वेयरहाउस वा आन्तरिक उपकरणमा डेटा ल्याउन सक्नुहुन्छ। सत्रमा ग्राहक ID जोड्नेबाहेक (identify, लेख्ने स्कोप आवश्यक; कुञ्जी स्कोप हेर्नुहोस्) API पढ्न मात्र हो: डेटा बदल्न वा मेटाउन सकिँदैन।

आधार URL: https://www.mouseplayer.com/api/v1/
सबै जवाफ JSON हुन्।
हरेक अनुरोध कुञ्जीबाट प्रमाणित भएर सम्बन्धित कार्यस्थानमै सीमित हुन्छ — एउटा कार्यस्थानको कुञ्जीले गल्तीले पनि अर्कोको डेटा देख्दैन।
पूरा पुनःप्लेब्याक रेकर्डिङ (माउस चाल, 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. आवृत्ति सीमा

प्रति कुञ्जी सीमा: प्रतिमिनेट 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 र वेबहुक पठाइँदैन। दोहोरिएको अर्डरले दोस्रो lead बनाउँदैन।

स्थिति	कहिले
`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`	ब्राउजर वा API बाट सत्रले पहिलो पटक ग्राहक ID पाउँदा — एक पटक
`session_ended`	सत्र बन्द हुँदा एक पटक
`goal_reached`	अनुकूलित घटनाले लक्ष्य पूरा गर्दा प्रति सत्र एक पटक। “घटना” प्रकारका लक्ष्य मात्र — 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 फर्काउँछन्।

सीमा प्रति कुञ्जी प्रतिमिनेट 60 प्रमाणित अनुरोध नै रहन्छ। नाघ्दा 429 (Retry-After: 60) आउँछ। Redis वा सीमा सेवा नचले 503 (Retry-After: 5) आउँछ; सीमाबिना अनुरोध कहिल्यै स्वीकारिँदैन। Retry-After मान्नुहोस् र अनियमित विलम्ब थप्नुहोस्; लगातार चक्रमा पुनःप्रयास नगर्नुहोस्। घटना डेटाबेस त्रुटिले पनि 503 फर्काउँछ। कर्सरले स्थिर स्न्यापसट राख्दैन: पुराना समयचिह्नका समानान्तर नयाँ रेकर्ड हुँदा फेरि खोज्नुपर्ने हुन सक्छ।

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 का लागि read स्कोप र register/grant/delete/disable का लागि write स्कोप चाहिन्छ। नेटिभ पूर्वावलोकन उपलब्धताका थप जाँच लागू हुन्छन्। स्थायी कार्यस्थान API कुञ्जी मोबाइल एपमा कहिल्यै नराख्नुहोस्।

हामी कसरी सहयोग गर्न सक्छौँ?