APIリファレンス

mapps.oneのREST APIを使うと、独自のコード、CIパイプライン、連携機能から、アプリの作成と更新、ストアリンクの管理、ストアメタデータのインポート、分析の読み取り、QRコードの生成、Webhookの登録を行えます。APIはStudioプランで利用できます。

ベースURL

https://mapps.one/api/v1

すべてのリクエストでHTTPSを使用します。リクエスト本文はContent-Type: application/jsonを指定してJSONで送信し、エラーもJSONで返されるように、常にAccept: application/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を加えたものです。

レート制限

各ワークスペースは1分あたり120リクエストまで送信でき、この上限はワークスペースのすべてのトークンで共有されます。すべてのレスポンスには、X-RateLimit-LimitヘッダーとX-RateLimit-Remainingヘッダーが含まれます。上限を超えると、APIは429 Too Many Requestsと、待機する秒数を示すRetry-Afterヘッダーを返します。

エラー

エラー時には、人が読めるmessageを含むJSON本文が返されます。一部のエラーには機械で読み取れる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は、そのストアの有効な掲載ページである必要があります。たとえば、App 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 Webhookが送信されます。掲載情報を読み取れない場合は、次のようになります。

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は、Webhookのイベントタイプを短い説明とともに一覧で返します。連携機能では、これを使ってイベントの選択画面を作成できます。

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

Webhookサブスクリプション

ユーザーが連携機能を接続したときなどにコードからWebhookサブスクリプションを作成し、接続が解除されたときに削除します。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個のWebhookエンドポイントを設定できます。サブスクリプションは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です。エンドポイント、フィールド、イベントタイプは随時追加される可能性があるため、認識できないフィールドは無視してください。互換性を損なう変更は、事前に告知したうえで新しいバージョンとしてリリースします。