જાહેર 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 headerમાં:

# 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. વેબહૂક: સહી ચકાસવી

પ્રોજેક્ટદીઠ વેબહૂક અહીં સેટ થાય છે: એકીકરણ; સહીનું સિક્રેટ પણ ત્યાં મળે. દરેક મોકલવામાં આ header છે:

Header	અર્થ
`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');

આના પર સહી કરો મૂળ body પર; 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 કે મર્યાદક ઉપલબ્ધ ન હોય તો 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 માટે વાંચન અને register/grant/delete/disable માટે લખાણ સ્કોપ જોઈએ. વધારાની native-preview ઉપલબ્ધતા તપાસ લાગુ પડે છે. કાયમી કાર્યસ્થળ API કી મોબાઇલ ઍપમાં ક્યારેય ન મૂકો.

અમે કેવી રીતે મદદ કરી શકીએ?