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 যেকোনো বৈধ টোকেন দিয়ে কাজ করে। প্রতিটি ইন্টিগ্রেশনকে শুধু তার প্রয়োজনীয় অ্যাবিলিটিগুলোই দিন।

কনভেনশন

• 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। আমরা যেকোনো সময় এন্ডপয়েন্ট, ফিল্ড ও ইভেন্ট টাইপ যোগ করতে পারি, তাই যে ফিল্ডগুলো চেনেন না সেগুলো উপেক্ষা করুন। ব্রেকিং পরিবর্তন আগাম নোটিশসহ একটি নতুন ভার্সন হিসেবে আসবে।