Referensi API

REST API mapps.one memungkinkan Anda membuat dan memperbarui aplikasi, mengelola link store, mengimpor metadata store, membaca analitik, membuat kode QR, dan berlangganan webhook dari kode Anda sendiri, pipeline CI, atau integrasi. API tersedia di paket Studio.

URL dasar

https://mapps.one/api/v1

Semua permintaan menggunakan HTTPS. Kirim body permintaan sebagai JSON dengan Content-Type: application/json, dan selalu kirim Accept: application/json agar error juga dikembalikan sebagai JSON.

Autentikasi

Buat token di dashboard pada bagian Pengembang. Pemilik dan admin ruang kerja dapat melakukan ini. Beri token nama, seperti "GitHub Actions", dan pilih izinnya. Token hanya ditampilkan sekali, jadi segera simpan di secret manager Anda.

Token dimiliki oleh ruang kerja, bukan oleh perorangan, sehingga token tetap berfungsi saat seseorang keluar dari tim. Token tidak kedaluwarsa. Cabut token dari halaman yang sama saat Anda tidak lagi membutuhkannya, atau jika token mungkin telah bocor.

Kirim token sebagai bearer token:

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

Izin

GET /workspace dan GET /events berfungsi dengan token valid apa pun. Berikan setiap integrasi hanya izin yang dibutuhkannya.

Konvensi

• ID berupa ULID huruf kecil sepanjang 26 karakter, seperti 01j8b2k6r3xq9v7m4n5p0s1t2w. Aplikasi dirujuk berdasarkan id, bukan slug, sehingga mengganti slug tidak pernah merusak integrasi Anda.
• Timestamp menggunakan ISO 8601 dalam UTC, seperti 2026-09-14T08:12:44+00:00.
• Respons membungkus hasil dalam kunci data.
• Kunci store adalah app_store, google_play, app_gallery, microsoft_store, dan web.
• Kunci platform adalah ios, android, huawei, windows, macos, dan other. Kunci tujuan adalah kunci store ditambah landing.

Batas rate

Setiap ruang kerja dapat membuat 120 permintaan per menit, yang digunakan bersama oleh semua tokennya. Setiap respons menyertakan header X-RateLimit-Limit dan X-RateLimit-Remaining. Saat Anda melampaui batas, API merespons dengan 429 Too Many Requests dan header Retry-After yang berisi jumlah detik untuk menunggu.

Error

Error mengembalikan body JSON dengan message yang dapat dibaca manusia. Beberapa error juga menyertakan code yang dapat dibaca mesin, dan error validasi mencantumkan masalah per kolom di 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."]
  }
}

Endpoint

Objek aplikasi

Ambil aplikasi

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"
  }
}

Daftar aplikasi

Mengembalikan aplikasi di ruang kerja. Hasilnya dipaginasi: ikuti links.next, atau kirim ?page=2, sampai nilainya 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
  }
}

Objek aplikasi dipersingkat dalam contoh ini. Setiap item memiliki kumpulan kolom yang lengkap.

Buat aplikasi

Anda juga dapat mengirim kolom apa pun yang tercantum di Perbarui aplikasi.

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"
    }
  }'

Responsnya adalah 201 Created dengan objek aplikasi baru. Link store disimpan dalam bentuk kanonis dengan status unverified sampai pemeriksaan di latar belakang selesai. Untuk mengisi ikon, tangkapan layar, dan deskripsi, panggil Impor metadata store berikutnya.

Perbarui aplikasi

Kirim hanya kolom yang ingin Anda ubah.

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" }
  }'

Responsnya adalah objek aplikasi yang sudah diperbarui.

Hapus aplikasi

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

Responsnya adalah 204 No Content. Penghapusan bersifat permanen: smart link, landing page, dokumen legal, media, dan analitik aplikasi akan dihapus.

Atur link store

PUT /apps/{id}/links menerima objek links dengan kunci berupa store:

• URL menambahkan atau mengganti link untuk store tersebut,
• null atau string kosong menghapusnya,
• store yang tidak Anda sertakan tidak diubah.

Setiap URL harus berupa listing yang valid untuk store-nya: link apps.apple.com dengan ID aplikasi, link play.google.com dengan ID paket, dan seterusnya. Link web dapat berupa alamat http atau https apa pun. URL dapat berisi hingga 1024 karakter. Link disimpan dalam bentuk kanonis dan diperiksa di latar belakang.

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
    }
  }'

Responsnya adalah objek aplikasi, termasuk links. Link yang tidak valid mengembalikan 422:

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

Impor metadata store

POST /apps/{id}/metadata membaca listing App Store, atau listing Google Play jika tidak ada link App Store yang dapat dibaca, lalu mengimpor detailnya.

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 }'

Responsnya adalah objek aplikasi, termasuk links dan screenshots, dan webhook app.metadata_fetched dikirim. Jika tidak ada listing yang dapat dibaca:

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

Analitik

GET /apps/{id}/analytics menerima parameter query berikut:

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 bersifat inklusif dan to bersifat eksklusif. Keduanya merupakan titik waktu UTC.
• clamped_to_plan bernilai true jika rentang yang diminta dipersingkat sesuai riwayat paket.
• daily menghitung klik per tanggal lokal, termasuk hari tanpa klik.
• Rincian mencantumkan hingga 10 nilai, diurutkan dari yang paling sering. Kunci kosong "" berarti tidak diketahui atau tidak diatur.
• Definisi metrik tersedia di halaman Analitik.

Kode QR

GET /apps/{id}/qr mengembalikan gambar. Gunakan format=svg (default) atau format=png, ditambah opsi yang sama seperti URL QR publik: fg, bg, margin, ecc, size, logo, dan download. Lihat Kode QR dan press kit.

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

Ruang kerja

GET /workspace mengembalikan ruang kerja, batas dan fitur paketnya, penggunaan saat ini, dan token yang sedang digunakan. Ini adalah panggilan pertama yang baik untuk memeriksa apakah token berfungsi.

{
  "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"] }
  }
}

Batas null berarti tanpa batas.

Jenis event

GET /events mencantumkan jenis event webhook beserta deskripsi singkatnya. Integrasi dapat menggunakannya untuk membuat pemilih event.

{
  "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." }
  ]
}

Langganan webhook

Buat langganan webhook dari kode, misalnya saat pengguna menghubungkan integrasi Anda, dan hapus saat mereka memutuskan koneksi. POST /webhooks menerima:

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 untuk penandatanganan hanya dikembalikan saat langganan dibuat. Gunakan untuk memverifikasi signature. Ruang kerja Studio dapat memiliki hingga 10 endpoint webhook. Hapus langganan dengan DELETE /webhooks/{id}, yang mengembalikan 204 No Content.

Contoh: publikasikan beta dari CI

Skrip ini membuat aplikasi, menambahkan link Google Play-nya, mengimpor listing, dan menampilkan smart link. Skrip ini memerlukan curl, jq, dan token dengan 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'

Versi

Ini adalah API versi 1. Kami dapat menambahkan endpoint, kolom, dan jenis event kapan saja, jadi abaikan kolom yang tidak Anda kenali. Perubahan yang tidak kompatibel akan dirilis sebagai versi baru dengan pemberitahuan sebelumnya.