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"، اور اس کی اجازتیں منتخب کریں۔ ٹوکن صرف ایک بار دکھایا جاتا ہے، اس لیے اسے فوراً اپنے سیکرٹ مینیجر میں محفوظ کر لیں۔

ٹوکنز کسی شخص کے نہیں بلکہ ورک اسپیس کے ہوتے ہیں، اس لیے کسی کے ٹیم چھوڑنے پر بھی وہ کام کرتے رہتے ہیں۔ ان کی میعاد ختم نہیں ہوتی۔ جب آپ کو کسی ٹوکن کی مزید ضرورت نہ رہے، یا اس کے لیک ہونے کا خدشہ ہو، تو اسی صفحے سے اسے منسوخ کر دیں۔

ٹوکن کو bearer ٹوکن کے طور پر بھیجیں:

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

اجازتیں

GET /workspace اور GET /events کسی بھی درست ٹوکن کے ساتھ کام کرتے ہیں۔ ہر انٹیگریشن کو صرف وہی اجازتیں دیں جن کی اسے ضرورت ہے۔

طے شدہ اصول

• IDs چھوٹے حروف والی 26 حروف کی ULIDs ہیں، جیسے 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 ایڈریس ہو سکتا ہے۔ URLs زیادہ سے زیادہ 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 URLs والے آپشنز بھی: 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 ہے۔ ہم کسی بھی وقت اینڈ پوائنٹس، فیلڈز اور ایونٹ کی اقسام شامل کر سکتے ہیں، اس لیے جن فیلڈز کو آپ نہیں پہچانتے انہیں نظر انداز کریں۔ بریکنگ تبدیلیاں پیشگی اطلاع کے ساتھ نئے ورژن کی شکل میں جاری کی جائیں گی۔