可用 Tools 一覽

這頁列出所有可呼叫的 tool，依 scope 與功能分組。

同一組 tool 同時供兩種傳輸層使用，能力完全一致：

MCP（JSON-RPC）— Claude / Cursor 等 client，詳見 MCP 入門
Public REST API — POST /api/v1/tools/{name}，詳見 OpenAPI（REST 鏡像）

每個 tool 的完整 JSON schema 可在 client 端打 tools/list（MCP）或 GET /api/v1/openapi.json（REST）取得；本頁聚焦在「有哪些、怎麼分組、個資與計費注意點」。標 🆕 為近期新增。

Scope 對照

Scope	能做的事
`homeinfo:read` / `homeinfo:write`	首頁資訊、首頁設計、Webhook 管理
`events:read` / `events:write`	活動本體、報名名單、加值與互動模組
`leads:read` / `leads:write` 🆕	名單神器：投廣 Landing Page、A/B 變體、名單匣
`mall:read` / `mall:write` 🆕	Mini 商城：商品、庫存、訂單出貨
`courses:read` / `courses:write` 🆕	Mini 課程：課程/章節/單元、學員名單、數據
`affiliates:read` / `affiliates:write` 🆕	聯盟行銷：夥伴、分潤、歸因訂單、出金查詢

Token 若缺少對應 scope，呼叫會回 SCOPE_DENIED，且該工具不會出現在 tools/list / GET /api/v1/tools。

一、首頁（`homeinfo:*`）

1.1 首頁資訊

分組	Tools	Scope
Overview	`homeinfo.get_overview`	read
Profile	`profile.get / update / set_image`	read / write
Folders	`folders.list / create / update / reorder / delete`	read / write
Links	`links.list / create / update / set_image / reorder / delete`	read / write
Modules	`modules.list / add / update / reorder / delete`	read / write
Socials	`socials.list / set / update / reorder / delete`	read / write

profile.set_image / links.set_image 從公開 URL 下載圖片並 re-host 到 R2，支援 avatar、socialOgImage、brandLogo、footerLogo、連結封面（限 image/*、單檔 10MB）。

1.2 首頁設計

分組	Tools	Scope
Design Settings	`design.get / put`	read / write
Theme	`design.set_theme`、`themes.list`	read / write

design.get 回傳 { designSettings, prefer3dFirst, themeId }
design.put 用 JSON 物件整包覆寫 designSettings（不是 merge）；建議先 design.get 拿目前內容、改完再 put
design.set_theme 只改 themeId，其他欄位保留
themes.list 列出 catalog 中啟用的主題（含 builtin 與上架主題）
prefer3dFirst（3D 落地頁優先）已在 profile.update 中，無需另外呼叫

1.3 Webhook 管理（🪄 Max 方案）

分組	Tools	Scope
Endpoints	`webhooks.list / create / update / delete / rotate_secret`	read / write
Delivery	`webhooks.test / list_deliveries / redeliver / event_types`	read / write

非 Max 方案呼叫 create / update(enable) / test 會回 403 SCOPE_DENIED；list / list_deliveries / event_types 仍可呼叫（只是不會收到任何 fire 出去的事件）。詳細 outbound 事件規格與簽名格式 → Webhook 文件

二、活動本體與設定（`events:*`）

活動以 uuid 為主鍵；票種、公告、投票、Q&A、投稿同樣以 uuid 識別。

分組	Tools
Events	`events.list / get / create / update / duplicate / delete / set_cover / cancel / check_slug / slug_history`
Ticket Types	`events.tickets.list / create / update / delete`
Form	`events.form.get / put`
Notifications	`events.notifications.get / put`
Feature data	`events.feature_data.get / put`（全模組統一 JSON）

events.set_cover 與 links.set_image 共用「公開 URL → R2」流程。

三、報名與名單（`events:*`）

取得參與人員的資料：批次用 events.attendees.list、單筆用 events.attendees.get 🆕。兩者皆為 owner view，回應含 email、票券、狀態、付款，以及報名表單填寫資料（answers label→value 與原始 customValues），頂層 customFields 為表單欄位定義。

分組	Tools	說明
Attendees	`events.attendees.list`	分頁列出報名者，支援 `status` / `search` 篩選
	`events.attendees.get` 🆕	取單一報名者完整資料（以 `attendeeUuid` 優先，否則 `email`）
	`events.attendees.patch_status`	改報名狀態（核准 / 取消 / 退款…）
	`events.attendees.export_csv`	匯出 CSV（含自訂欄位）
	`events.attendees.bulk_import`	批次匯入報名者（含自訂欄位值）
	`events.attendees.invite_by_email`	寄送邀請信
	`events.attendees.gift_ticket`	贈票（建立免費票券）
Check-in	`events.checkin.summary / list_attendees / manual / recent`	報到統計與操作
Report	`events.report.summary / attendees`	活動成效報表

四、活動加值與互動模組（`events:*`）

4.1 徵稿（Submissions）

「徵稿」分兩層：徵稿活動（campaign） 是一檔徵件設定（允許檔案類型、投票規則、收件上限、開放狀態）；投稿（submission） 是參加者上傳的作品。

分組	Tools	說明
總設定	`events.submissions.update_settings`	活動層級的徵稿開關與允許類型
徵稿活動 CRUD 🆕	`events.submissions.campaigns.list`	列出所有徵稿活動（含件數）
	`events.submissions.campaigns.create`	新增徵稿活動
	`events.submissions.campaigns.update`	更新徵稿活動（含 `status: open/closed`）
	`events.submissions.campaigns.delete`	刪除徵稿活動（連同投稿，兩階段確認）
投稿管理	`events.submissions.create` 🆕	以公開檔案 URL 新增一筆投稿（避開 multipart）
	`events.submissions.list`	列出投稿（`includeAll` 連 pending/rejected）
	`events.submissions.set_status`	改投稿狀態 pending / approved / rejected
	`events.submissions.delete`	刪除投稿（兩階段確認）

events.submissions.create：傳 fileUrl（公開可下載 URL）+ fileName（決定副檔名/型別：png/jpg/mp4/glb/pdf/zip → image/video/model3d/pdf/archive）+ title / submitterName / submitterEmail；未帶 campaignUuid 則歸入預設徵稿活動。後端會 SSRF 驗證、依型別套大小上限後存入 R2。參加者端的網頁上傳（multipart）仍照舊。

4.2 分組（Pairing）

支援自動分組、手動增刪，以及批次上傳。

分組	Tools	說明
讀取	`events.pairing.get_current`	取得目前分組結果（未產生回 null）
產生 / 上傳	`events.pairing.generate`	自動分組（`random` / `by_field`）
	`events.pairing.import` 🆕	批次上傳分組：`rows: [{ group, email, name? }]`，依 email 對應報名者、單次上限 5000 筆，取代目前分組
人員與分組編輯	`events.pairing.add_group`	新增一組（可帶成員）
	`events.pairing.add_members`	加成員到指定組
	`events.pairing.remove_member`	從某組移除一位成員
	`events.pairing.delete_group`	刪除一組（兩階段確認）
清除	`events.pairing.reset`	清除全部分組（兩階段確認）

4.3 其他加值模組

分組	Tools
Announcements	`events.announcements.list / create / update / delete`
Broadcasts	`events.broadcasts.preview_audience / send_email / list_history`
Feature Records	`events.feature_records.list / create / delete`（抽獎 / 點名）
Identity	`events.identity.get_config / put_config / list_cards`（活動身分卡）
Polls	`events.polls.list / create / update / delete`
Q&A	`events.qa.list / patch / delete`
Surveys	`events.surveys.get_config / put_config / list_responses / summary`
Outcomes	`events.outcomes.list / delete / quota`（成果紀錄資產）
Collaborators	`events.collaborators.list / invite / resend / change_role / remove`

五、名單神器（`leads:*`）🆕

投廣 Landing Page 的建立、發布、A/B 測試與名單回收。頁面內容為結構化 sections JSON（hero／賣點／見證／FAQ／比較表格／好評輪播／LINE 按鈕／倒數／表單…16 種區塊，任一區塊可設 bg 背景圖）。

分組	Tools	Scope
Templates	`lead_pages.templates`（9 種模板）	read
Pages	`lead_pages.list / get / create / update / delete`	read / write
A/B 測試	`lead_pages.create_variant`（複製為變體、權重分流）	write
名單匣	`leads.list / update`（狀態管線＋標籤）	read / write

lead_pages.update 的 status: "published" 即發布；sections 建議先 get 取回現況、修改後整組回寫
公開頁網址：https://hypelink.app/{hypeId}/lp/{slug}
AI 生成／AI 調整需扣 SP，不開放於 API，請走 dashboard
leads.list 回傳含個資（Email／電話／表單答案）——比照名單匯出處理

六、Mini 商城（`mall:*`）🆕

分組	Tools	Scope
商品	`mall.products.list / get / create / update / set_status / restock`	read / write
訂單	`mall.orders.list / get / update_fulfillment`	read / write

mall.orders.update_fulfillment 更新出貨狀態（可帶物流單號），買家會收到通知信
結帳、金流與退款不開放於 API（金錢敏感操作），請走 dashboard「收款管理」

七、Mini 課程（`courses:*`）🆕

分組	Tools	Scope
課程	`courses.list / get / create / update / delete`	read / write
章節	`courses.chapters.add / update / delete`	write
單元	`courses.lessons.add / update / delete`	write
學員與數據	`courses.students`、`courses.analytics`	read

影片檔上傳（multipart）不開放於 API，請走 dashboard；外部影片連結可經 courses.lessons.update 設定
courses.students 回傳學員個資——比照名單匯出處理

八、聯盟行銷（`affiliates:*`）🆕

分組	Tools	Scope
夥伴（KOL）	`affiliates.list / get / create / update`	read / write
歸因訂單	`affiliates.orders`	read
出金	`affiliates.payouts.pending / list / get`	read

affiliates.create 可同時建立專屬優惠碼與折扣；sendInvite: true 會寄邀請信
出金單的建立、標記已付與作廢不開放於 API（金錢敏感操作），請走 dashboard「聯盟行銷 > 出金」

九、個資 / 計費小提醒

events.attendees.*、events.identity.list_cards、events.qa.list、events.surveys.list_responses、events.submissions.*、leads.list、mall.orders.*、courses.students 都會回傳含個資的資料 — 比照名單匯出處理，不要把回應貼到公開地方。
events.broadcasts.send_email 會扣 SP（每封 1 SP），建議先 preview_audience 確認；採兩階段 confirmToken 防誤觸發。
events.outcomes.* 僅提供 list / delete / quota，上傳不開放透過 API（涉及多媒體 multipart 與配額），請走 dashboard「活動成效 > 成果紀錄」。
events.pairing.import 會取代目前分組（建立新的 manual session），上傳前請確認 rows 內容。

十、共通約定

所有 write tool 都支援 dry_run: true → 回傳將被執行的 changes 但不寫入。
delete_* 等破壞性操作預設兩階段：第一次呼叫拿到 confirmToken + 摘要，第二次帶 confirmToken 才真正執行。
Token 缺少對應 scope → 回 SCOPE_DENIED，且該工具從清單中隱藏。

十一、看完整 Schema

傳輸	取得 schema
MCP	client 連線後執行 `tools/list`
REST	`GET /api/v1/openapi.json`（OpenAPI 3.1）或互動式 `GET /api/v1/docs`

回應含每個 tool 的 inputSchema 與描述。Claude / Cursor 會自動讀取，使用者通常不需手動展開；只有在你想用其他 client（例如自寫 inspector）時才會用到。