API रेफरेंस

mapps.one REST API की मदद से आप अपने कोड, CI पाइपलाइन या इंटीग्रेशन से ऐप बना और अपडेट कर सकते हैं, स्टोर लिंक मैनेज कर सकते हैं, स्टोर मेटाडेटा इम्पोर्ट कर सकते हैं, एनालिटिक्स पढ़ सकते हैं, QR कोड जनरेट कर सकते हैं और वेबहुक सब्सक्राइब कर सकते हैं। API, Studio प्लान पर उपलब्ध है।

बेस URL

https://mapps.one/api/v1

सभी रिक्वेस्ट HTTPS पर होती हैं। रिक्वेस्ट बॉडी Content-Type: application/json के साथ JSON के रूप में भेजें, और हमेशा Accept: application/json भेजें, ताकि एरर भी JSON में लौटें।

ऑथेंटिकेशन

डैशबोर्ड में डेवलपर के तहत एक टोकन बनाएं। वर्कस्पेस मालिक और एडमिन यह कर सकते हैं। टोकन को एक नाम दें, जैसे "GitHub Actions", और उसकी परमिशन चुनें। टोकन सिर्फ़ एक बार दिखाया जाता है, इसलिए उसे तुरंत अपने सीक्रेट मैनेजर में सेव करें।

टोकन किसी व्यक्ति के नहीं, बल्कि वर्कस्पेस के होते हैं, इसलिए किसी के टीम छोड़ने पर भी वे काम करते रहते हैं। वे एक्सपायर नहीं होते। जब किसी टोकन की ज़रूरत न रहे, या उसके लीक होने की आशंका हो, तो उसी पेज से उसे रद्द करें।

टोकन को बेयरर टोकन के रूप में भेजें:

curl https://mapps.one/api/v1/workspace \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

परमिशन

GET /workspace और GET /events किसी भी मान्य टोकन के साथ काम करते हैं। हर इंटीग्रेशन को सिर्फ़ उतनी ही परमिशन दें जितनी उसे चाहिए।

कन्वेंशन

• ID 26 कैरेक्टर के लोअरकेस ULID होते हैं, जैसे 01j8b2k6r3xq9v7m4n5p0s1t2w। ऐप को स्लग से नहीं, बल्कि id से पहचाना जाता है, इसलिए स्लग बदलने से आपका इंटीग्रेशन कभी नहीं टूटता।
• टाइमस्टैंप UTC में ISO 8601 फ़ॉर्मेट में होते हैं, जैसे 2026-09-14T08:12:44+00:00।
• रिस्पॉन्स में नतीजा एक data कुंजी के अंदर होता है।
• स्टोर कुंजियां app_store, google_play, app_gallery, microsoft_store और web हैं।
• प्लेटफ़ॉर्म कुंजियां ios, android, huawei, windows, macos और other हैं। डेस्टिनेशन कुंजियों में स्टोर कुंजियों के साथ landing भी शामिल है।

रेट लिमिट

हर वर्कस्पेस एक मिनट में 120 रिक्वेस्ट कर सकता है, और यह लिमिट उसके सभी टोकन के बीच साझा होती है। हर रिस्पॉन्स में X-RateLimit-Limit और X-RateLimit-Remaining हेडर होते हैं। लिमिट पार करने पर API 429 Too Many Requests और एक Retry-After हेडर लौटाता है, जिसमें लिखा होता है कि कितने सेकंड इंतज़ार करना है।

एरर

एरर एक JSON बॉडी लौटाते हैं, जिसमें इंसानों के पढ़ने लायक message होता है। कुछ एरर में मशीन के पढ़ने लायक code भी होता है, और वैलिडेशन एरर errors में हर फ़ील्ड की समस्याएं अलग-अलग बताते हैं।

HTTP/2 402
{
  "message": "API access requires the Studio plan.",
  "code": "plan_required"
}

HTTP/2 422
{
  "message": "This link is already taken.",
  "errors": {
    "slug": ["This link is already taken."]
  }
}

एंडपॉइंट

ऐप ऑब्जेक्ट

ऐप प्राप्त करें

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

{
  "data": {
    "id": "01j8b2k6r3xq9v7m4n5p0s1t2w",
    "name": "Habitly",
    "slug": "habitly",
    "status": "live",
    "tagline": "Build habits that stick",
    "description": "Habitly helps you build small daily habits with gentle reminders and streaks.",
    "category": "health-fitness",
    "page_theme": "clean",
    "accent_color": "#16a34a",
    "developer": {
      "name": "Habitly Labs",
      "website": "https://habitly.app",
      "email": "hello@habitly.app"
    },
    "social_links": {
      "instagram": "https://instagram.com/habitly.app"
    },
    "features": [
      { "icon": "bell", "title": "Gentle reminders", "description": "Nudges at the time you choose." }
    ],
    "listed_in_explore": true,
    "utm_passthrough": true,
    "redirect_rules": {
      "ios": "app_store",
      "android": "google_play",
      "huawei": "app_gallery",
      "windows": "microsoft_store",
      "macos": "landing",
      "other": "landing"
    },
    "icon_url": "https://mapps.one/storage/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/icon/icon.png",
    "rating": { "value": 4.8, "count": 12450 },
    "urls": {
      "smart_link": "https://mapps.one/habitly",
      "landing_page": "https://mapps.one/habitly/page",
      "qr_svg": "https://mapps.one/habitly/qr.svg",
      "qr_png": "https://mapps.one/habitly/qr.png",
      "privacy_policy": "https://mapps.one/habitly/privacy",
      "terms": "https://mapps.one/habitly/terms"
    },
    "links": {
      "app_store": {
        "url": "https://apps.apple.com/app/id1612345678",
        "status": "verified",
        "verified_at": "2026-09-14T08:12:44+00:00"
      },
      "google_play": {
        "url": "https://play.google.com/store/apps/details?id=com.habitly.app",
        "status": "verified",
        "verified_at": "2026-09-14T08:12:46+00:00"
      }
    },
    "created_at": "2026-09-01T11:20:03+00:00",
    "updated_at": "2026-09-14T08:12:46+00:00"
  }
}

ऐप की सूची

वर्कस्पेस के ऐप लौटाता है। नतीजे पेजों में बंटे होते हैं: links.next को फ़ॉलो करें, या ?page=2 भेजें, जब तक वह null न हो जाए।

curl "https://mapps.one/api/v1/apps?page=1" \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

{
  "data": [
    { "id": "01j8b2k6r3xq9v7m4n5p0s1t2w", "name": "Habitly", "slug": "habitly", "status": "live" },
    { "id": "01j8d5r2w9y6a3c0e7g4j1m8p5", "name": "Habitly Focus", "slug": "habitly-focus", "status": "paused" }
  ],
  "links": {
    "first": "https://mapps.one/api/v1/apps?page=1",
    "last": "https://mapps.one/api/v1/apps?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 2
  }
}

इस उदाहरण में ऐप ऑब्जेक्ट छोटे करके दिखाए गए हैं। हर आइटम में सभी फ़ील्ड होते हैं।

ऐप बनाएं

आप ऐप अपडेट करें में दिए गए फ़ील्ड में से कोई भी फ़ील्ड भी भेज सकते हैं।

curl https://mapps.one/api/v1/apps \
  -X POST \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Habitly",
    "slug": "habitly",
    "links": {
      "app_store": "https://apps.apple.com/us/app/habitly/id1612345678",
      "google_play": "https://play.google.com/store/apps/details?id=com.habitly.app"
    }
  }'

रिस्पॉन्स नए ऐप ऑब्जेक्ट के साथ 201 Created होता है। स्टोर लिंक कैनोनिकल रूप में सेव किए जाते हैं, और बैकग्राउंड जांच पूरी होने तक उनका स्टेटस unverified रहता है। आइकन, स्क्रीनशॉट और विवरण भरने के लिए, इसके बाद स्टोर मेटाडेटा इम्पोर्ट करें कॉल करें।

ऐप अपडेट करें

सिर्फ़ वे फ़ील्ड भेजें जिन्हें आप बदलना चाहते हैं।

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w \
  -X PATCH \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tagline": "Tiny habits, big changes",
    "redirect_rules": { "macos": "landing" }
  }'

रिस्पॉन्स अपडेट किया गया ऐप ऑब्जेक्ट होता है।

ऐप हटाएं

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w \
  -X DELETE \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

रिस्पॉन्स 204 No Content होता है। हटाना स्थायी है: ऐप का स्मार्ट लिंक, लैंडिंग पेज, कानूनी डॉक्यूमेंट, मीडिया और एनालिटिक्स हटा दिए जाते हैं।

स्टोर लिंक सेट करें

PUT /apps/{id}/links स्टोर के नाम वाली कुंजियों के साथ एक links ऑब्जेक्ट लेता है:

• कोई URL उस स्टोर का लिंक जोड़ता है या बदलता है,
• null या खाली स्ट्रिंग उसे हटा देती है,
• जिन स्टोर को आप छोड़ देते हैं, वे नहीं बदलते।

हर URL अपने स्टोर की मान्य लिस्टिंग होना चाहिए: ऐप ID वाला apps.apple.com लिंक, पैकेज ID वाला play.google.com लिंक, वगैरह। web लिंक कोई भी http या https पता हो सकता है। URL 1024 कैरेक्टर तक लंबे हो सकते हैं। लिंक कैनोनिकल रूप में सेव किए जाते हैं और बैकग्राउंड में जांचे जाते हैं।

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/links \
  -X PUT \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "links": {
      "app_gallery": "https://appgallery.huawei.com/app/C109876543",
      "web": null
    }
  }'

रिस्पॉन्स links सहित ऐप ऑब्जेक्ट होता है। अमान्य लिंक होने पर 422 लौटता है:

{
  "message": "This is not a valid Google Play link.",
  "errors": {
    "links.google_play": ["This is not a valid Google Play link."]
  }
}

स्टोर मेटाडेटा इम्पोर्ट करें

POST /apps/{id}/metadata App Store लिस्टिंग पढ़ता है, या पढ़ने लायक App Store लिंक न होने पर Google Play लिस्टिंग, और उसकी जानकारी इम्पोर्ट करता है।

curl https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/metadata \
  -X POST \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "overwrite": true }'

रिस्पॉन्स links और screenshots सहित ऐप ऑब्जेक्ट होता है, और एक app.metadata_fetched वेबहुक भेजा जाता है। अगर कोई लिस्टिंग पढ़ी न जा सके:

HTTP/2 422
{
  "message": "The store listing could not be read. Add a valid App Store or Google Play link first.",
  "code": "metadata_unavailable"
}

एनालिटिक्स

GET /apps/{id}/analytics ये क्वेरी पैरामीटर स्वीकार करता है:

curl "https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/analytics?range=7d&timezone=Europe/Istanbul" \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json"

{
  "data": {
    "app": { "id": "01j8b2k6r3xq9v7m4n5p0s1t2w", "slug": "habitly" },
    "range": {
      "key": "7d",
      "from": "2026-09-07T21:00:00+00:00",
      "to": "2026-09-14T21:00:00+00:00",
      "timezone": "Europe/Istanbul",
      "clamped_to_plan": false
    },
    "summary": {
      "clicks": 1284,
      "visitors": 902,
      "page_views": 356,
      "store_clicks": 141
    },
    "daily": {
      "2026-09-08": 152,
      "2026-09-09": 171,
      "2026-09-10": 168,
      "2026-09-11": 205,
      "2026-09-12": 214,
      "2026-09-13": 190,
      "2026-09-14": 184
    },
    "breakdowns": {
      "os": { "iOS": 702, "Android": 431, "Windows": 88, "macOS": 63 },
      "country": { "TR": 512, "US": 298, "": 236, "DE": 141, "GB": 97 },
      "source": { "instagram": 488, "direct": 402, "qr": 190, "google": 121, "x": 83 },
      "destination": { "app_store": 640, "google_play": 399, "landing": 214, "deep_link": 31 },
      "utm_campaign": { "": 796, "launch": 402, "newsletter-sep": 86 }
    }
  }
}

• from शामिल होता है और to शामिल नहीं होता। दोनों UTC समय-बिंदु हैं।
• clamped_to_plan तब true होता है जब मांगी गई रेंज को प्लान की हिस्ट्री के मुताबिक छोटा किया गया हो।
• daily हर लोकल तारीख के क्लिक गिनता है, जिनमें बिना क्लिक वाले दिन भी शामिल हैं।
• ब्रेकडाउन में 10 तक वैल्यू होती हैं, सबसे ज़्यादा बार आने वाली सबसे पहले। खाली कुंजी "" का मतलब है अज्ञात या सेट नहीं।
• मेट्रिक की परिभाषाएं एनालिटिक्स पेज पर हैं।

QR कोड

GET /apps/{id}/qr एक इमेज लौटाता है। format=svg (डिफ़ॉल्ट) या format=png इस्तेमाल करें, साथ में पब्लिक QR URL वाले विकल्प भी: fg, bg, margin, ecc, size, logo और download। QR कोड और प्रेस किट देखें।

curl "https://mapps.one/api/v1/apps/01j8b2k6r3xq9v7m4n5p0s1t2w/qr?format=png&size=2048&ecc=Q" \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -o habitly-qr.png

वर्कस्पेस

GET /workspace वर्कस्पेस, उसके प्लान की लिमिट और फ़ीचर, मौजूदा इस्तेमाल और इस्तेमाल हो रहा टोकन लौटाता है। टोकन काम करता है या नहीं, यह जांचने के लिए यह एक अच्छी पहली कॉल है।

{
  "data": {
    "id": "01j8a0f4c7d2e9h6k3m5n8q1r4",
    "name": "Habitly Labs",
    "plan": {
      "key": "studio",
      "name": "Studio",
      "limits": {
        "apps": null,
        "analytics_days": 730,
        "members": 10,
        "custom_domains": 25,
        "legal_locales": null,
        "screenshots": 10,
        "webhooks": 10
      },
      "features": ["remove_badge", "all_themes", "accent_color", "qr_logo", "legal_full", "deep_links", "press_kit", "analytics_export", "custom_domains", "team", "folders", "ab_testing", "api", "webhooks", "white_label"]
    },
    "usage": { "apps": 12, "custom_domains": 3, "members": 4 },
    "token": { "name": "GitHub Actions", "abilities": ["apps:read", "apps:write"] }
  }
}

null लिमिट का मतलब अनलिमिटेड है।

इवेंट टाइप

GET /events वेबहुक इवेंट टाइप को एक छोटे विवरण के साथ सूचीबद्ध करता है। इंटीग्रेशन इससे इवेंट पिकर बना सकते हैं।

{
  "data": [
    { "type": "app.created", "description": "An app was added to the workspace." },
    { "type": "app.updated", "description": "App details, links or page settings changed." },
    { "type": "app.deleted", "description": "An app was deleted." },
    { "type": "app.status_changed", "description": "An app went live, was paused or was suspended." },
    { "type": "app.metadata_fetched", "description": "Store metadata was imported for an app." },
    { "type": "legal.published", "description": "A privacy policy or terms document was published." },
    { "type": "domain.verified", "description": "A custom domain was verified." },
    { "type": "link.clicked", "description": "Every smart link click. High volume." },
    { "type": "analytics.daily_summary", "description": "Yesterday's click totals for each app, sent once a day." }
  ]
}

वेबहुक सब्सक्रिप्शन

कोड से वेबहुक सब्सक्रिप्शन बनाएं, जैसे जब कोई यूज़र आपका इंटीग्रेशन कनेक्ट करे, और डिस्कनेक्ट करने पर उन्हें हटा दें। POST /webhooks ये फ़ील्ड लेता है:

curl https://mapps.one/api/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer $MAPPS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.zapier.com/hooks/catch/1234567/abcde12/",
    "events": ["link.clicked"],
    "description": "Zapier: clicks to Google Sheets"
  }'

HTTP/2 201
{
  "data": {
    "id": "01j8c1p4s7v0y3b6e9h2k5n8q1",
    "url": "https://hooks.zapier.com/hooks/catch/1234567/abcde12/",
    "events": ["link.clicked"],
    "description": "Zapier: clicks to Google Sheets",
    "is_active": true,
    "secret": "9f2c4e7a1b8d3f6e0a5c2b9d7e4f1a3c6b8d0e2f4a6c8e0b2d4f6a8c0e2b4d61",
    "created_at": "2026-09-14T10:05:12+00:00"
  }
}

साइनिंग secret सिर्फ़ सब्सक्रिप्शन बनाते समय लौटाया जाता है। इससे सिग्नेचर वेरिफ़ाई करें। एक Studio वर्कस्पेस में 10 वेबहुक एंडपॉइंट तक हो सकते हैं। DELETE /webhooks/{id} से सब्सक्रिप्शन हटाएं, जो 204 No Content लौटाता है।

उदाहरण: CI से बीटा प्रकाशित करें

यह स्क्रिप्ट एक ऐप बनाती है, उसका Google Play लिंक जोड़ती है, लिस्टिंग इम्पोर्ट करती है और स्मार्ट लिंक प्रिंट करती है। इसके लिए curl, jq और apps:write वाला टोकन चाहिए।

#!/usr/bin/env bash
set -euo pipefail

API="https://mapps.one/api/v1"
HEADERS=(-H "Authorization: Bearer $MAPPS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json")

APP_ID=$(curl -sf "${HEADERS[@]}" -X POST "$API/apps" \
  -d '{"name": "Habitly Beta", "slug": "habitly-beta"}' | jq -r '.data.id')

curl -sf "${HEADERS[@]}" -X PUT "$API/apps/$APP_ID/links" \
  -d '{"links": {"google_play": "https://play.google.com/store/apps/details?id=com.habitly.beta"}}' > /dev/null

curl -sf "${HEADERS[@]}" -X POST "$API/apps/$APP_ID/metadata" \
  -d '{"overwrite": true}' | jq -r '.data.urls.smart_link'

वर्शनिंग

यह API का वर्शन 1 है। हम कभी भी नए एंडपॉइंट, फ़ील्ड और इवेंट टाइप जोड़ सकते हैं, इसलिए जिन फ़ील्ड को आप नहीं पहचानते उन्हें नज़रअंदाज़ करें। ब्रेकिंग बदलाव पहले से सूचना देकर नए वर्शन के रूप में आएंगे।