MeetROAS 客戶 API

1. 快速開始

投手：想用 AI 助手看廣告成效？

1. 到 Dashboard /account/api 的「API」分頁建立 Key
2. 完整 Key 只顯示一次；立即用安全方式存入環境變數（例如 read -rs MEETROAS_API_KEY 然後 export MEETROAS_API_KEY、密碼管理器或 CI secrets）
3. 複製以下命令，直接執行；shell 會自動展開環境變數

curl https://open.meetroas.com/v1/me \
  -H "Authorization: Bearer $MEETROAS_API_KEY"

開發者：需要整合到自己的服務或腳本？繼續閱讀下方的 REST API 參考。

2. 驗證

取得 API Key

• 在 Dashboard /account/api 的「API」分頁建立
• 完整 Key 只在建立時顯示一次，格式： mrp_<id>_<secret>
• 有效期 30／90／365 天，無永久 Key
• 每位建立者最多 5 把有效 Key，每個帳號最多 20 把

使用方式

所有 REST 請求都需要帶入 Authorization 標頭：

Authorization: Bearer mrp_<id>_<secret>

權限範圍

建立 Key 時可明確選擇的權限範圍；既有 Key 和預設選項維持唯讀：

• apps:read — 讀取 App 列表
• campaigns:read — 讀取 Campaign
• performance:read — 讀取成效資料（含版位洞察）
• apps:write — 新增與編輯 App；需同時授予 apps:read
• campaigns:write — 新增與編輯 Campaign；需同時授予 apps:read 與 campaigns:read

有效權限 = Key 的權限範圍 ∩ 建立者當下角色。建立者被停用或降權後最慢 10 秒生效，撤銷立即生效。

3. 配額與限制

配額同時強制執行 quota unit 與請求次數。每個方案同時有每分鐘與每日上限：

單位消耗

所以 Free 方案每分鐘最多 3 次版位洞察、每日最多 100 次；一般讀取則是每分鐘 30 次、每日 1,000 次。

回應標頭

• RateLimit-Limit — 每分鐘 units 上限
• RateLimit-Remaining — 滾動 60 秒剩餘 units
• RateLimit-Reset — 視窗內最舊一筆離開視窗還要幾秒
• X-MeetROAS-Daily-Remaining — 當日剩餘 units
• X-MeetROAS-Api-Version — 1

其他限制

• GET /v1/apps 不分頁（方案上限最多 30 個 App）
• 版位洞察最多回 500 個群組，其餘彙總在 other；不提供 5000 列／CSV 模式
• 不開 CORS，瀏覽器端 JavaScript 無法直接呼叫

4. REST API 參考

基礎網域： https://open.meetroas.com/v1

GET /v1/me

所需權限：任何有效 Key · 配額單位：1

取得目前 API Key 的資訊、帳號方案與配額剩餘。

curl "https://open.meetroas.com/v1/me" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"

{
  "ok": true,
  "data": {
    "key": {
      "id": "a7f3k29d1mq4x8bz",
      "label": "My API Key",
      "scopes": ["apps:read", "campaigns:read", "performance:read"],
      "expiresAt": "2027-01-01T00:00:00Z"
    },
    "account": {
      "id": "acc_9f2c4d61-8b3a-4e57-9d10-2f6b8c1e4a77",
      "plan": "pro"
    },
    "creator": {
      "role": "admin"
    },
    "quota": {
      "perMinute": {
        "limit": 120,
        "remaining": 118,
        "resetInSeconds": 42
      },
      "daily": {
        "limit": 20000,
        "remaining": 15234
      }
    }
  }
}

GET /v1/apps

所需權限：apps:read · 配額單位：1

取得帳號內所有 App 的列表。

curl "https://open.meetroas.com/v1/apps" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "brand_4a7c9e21b8d35f60a1c4e7b209d63f8a",
        "slug": "my-game",
        "name": "My Awesome Game",
        "iconUrl": "https://assets.meetroas.com/icons/my-game.png",
        "trafficSource": {
          "id": "trafficstars",
          "label": "TrafficStars"
        },
        "campaignCount": 5,
        "reportingTimezone": "Asia/Taipei"
      }
    ]
  }
}

GET /v1/apps/{appSlug}/campaigns

所需權限：apps:read + campaigns:read · 配額單位：1

取得指定 App 內所有 Campaign。

curl "https://open.meetroas.com/v1/apps/my-game/campaigns" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"

{
  "ok": true,
  "data": {
    "app": {
      "id": "brand_4a7c9e21b8d35f60a1c4e7b209d63f8a",
      "slug": "my-game",
      "name": "My Awesome Game"
    },
    "items": [
      {
        "id": "brand:brand_4a7c9e21b8d35f60a1c4e7b209d63f8a",
        "kind": "primary",
        "label": "My Awesome Game",
        "host": "my-game.meetroas.com",
        "enabled": true,
        "objective": "pwa_install",
        "trafficSource": {
          "id": "trafficstars",
          "label": "TrafficStars"
        }
      }
    ]
  }
}

GET /v1/apps/{appSlug}/campaigns/{campaignId}/placement-insights

所需權限：apps:read + campaigns:read + performance:read · 配額單位：10

取得指定 Campaign 的版位洞察報表與建議。

查詢參數：

• range: today | 7d | 30d (預設: 7d)
• dimension: placement | subPlacement | creative | upstreamCampaign | country | environment (預設: placement)

curl "https://open.meetroas.com/v1/apps/my-game/campaigns/brand:brand_9f2c41ab7d0e4c518a63b2d7e04f19c5/placement-insights?range=7d&dimension=placement" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"

回應包含 campaigns、totals、rows（最多 500 筆）、other 與 advice（block、whitelist、bids、targeting），詳見 https://open.meetroas.com/openapi.json

新增與編輯 App、Campaign

所有寫入須帶 Idempotency-Key（8–128 字元）；PATCH 也須帶對應 /editor GET 回傳的 If-Match ETag。版本過期會回 412。

• POST /v1/apps、PATCH /v1/apps/{appSlug}：JSON，支援 Dashboard App 編輯器的 content、primary、destination、objective、media。
• POST /v1/apps/{appSlug}/campaigns、PATCH /v1/apps/{appSlug}/campaigns/{campaignId}：multipart 表單，支援 Dashboard Campaign 編輯器的全部欄位。以 JSON {enabled:boolean} 可調整一般 Campaign 狀態。
• GET /v1/apps/{appSlug}/editor、GET /v1/apps/{appSlug}/campaigns/{campaignId}/editor：取得完整可編輯資料與 ETag。主要 Campaign 使用 App 編輯器欄位及 apps:write。
• POST /v1/media/staging：上傳圖示、截圖、主視覺或影片，再把回傳收據填入媒體欄位。新增時 target 為 new-app:{Idempotency-Key} 或 new-page:{appId}:{Idempotency-Key}。

請求欄位與 JSON 結構見 https://open.meetroas.com/openapi.json

5. 錯誤與重試

GET 請求可直接重試；寫入請保留相同 Idempotency-Key，編輯衝突時重新取得 /editor 與 ETag。