Public REST API（OpenAPI 3.1）

如果你不想用 MCP，而是想用 Make.com / n8n / Zapier / 自家後端 axios / curl 直接打 REST，這條入口就是給你的。

底下涵蓋的功能和 MCP server 一模一樣 — 兩者共用同一組 token、scope、audit log 與 rate limit，差別只在傳輸層。

	MCP	OpenAPI
傳輸	JSON-RPC over HTTP	REST + JSON
端點	單一 endpoint，方法在 body	每個 tool 對應一個 path
適合	LLM client（Claude / Cursor / Claude Desktop）	一般 HTTP client / 無代碼工具
Schema 描述	`tools/list` 取得	OpenAPI 3.1 spec

基本資訊


Base URL（production）	`https://api.hypelink.app`
OpenAPI spec	`GET /api/v1/openapi.json`
互動式文件（Swagger UI）	`GET /api/v1/docs`
認證	`Authorization: Bearer hl_pat_<your-token>`
Rate limit	60 req / min（per token）
內容協商	`Content-Type: application/json`

三步驟開始

1. 在 dashboard 產生 API Token

跟 MCP 共用同一組 token：

https://hypelink.app/dashboard/brands/<hypeId>/settings/api-tokens
「產生新 Token」→ 勾選需要的 scope（homeinfo:read / homeinfo:write / events:read / events:write）→ 命名 → 複製 plaintext token

2. 看你能用哪些 tools


curl https://api.hypelink.app/api/v1/tools \
  -H "Authorization: Bearer hl_pat_xxxxxxxxxxxx"

回傳：


{
  "tools": [
    {
      "name": "homeinfo.get_overview",
      "description": "一次取得品牌首頁全貌：profile / folders / module 計數 / socials 計數",
      "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
    },
    ...
  ]
}

3. 呼叫任何一個 tool

統一格式：POST /api/v1/tools/{name}，參數放 JSON body。


curl -X POST https://api.hypelink.app/api/v1/tools/events.list \
  -H "Authorization: Bearer hl_pat_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

成功回 200：


{
  "ok": true,
  "data": [
    { "uuid": "...", "name": "好攝影 GoodShot — 婚禮分享會", "status": "active", ... }
  ]
}

常用呼叫範例

列出活動報名者


curl -X POST https://api.hypelink.app/api/v1/tools/events.attendees.list \
  -H "Authorization: Bearer hl_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "206e879c-a0ec-4964-a43f-5c5f7903c5e5",
    "pageSize": 50,
    "status": "registered"
  }'

新增連結到首頁


curl -X POST https://api.hypelink.app/api/v1/tools/links.create \
  -H "Authorization: Bearer hl_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": 180,
    "name": "我的 Instagram",
    "url": "https://instagram.com/myhandle"
  }'

Dry-run（預覽不寫入）

任何 write tool 都支援 dry_run: true：


curl -X POST https://api.hypelink.app/api/v1/tools/events.update \
  -H "Authorization: Bearer hl_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "206e879c-...",
    "status": "ended",
    "dry_run": true
  }'

回傳 changes 陣列，描述會被寫入什麼，但沒實際執行。

兩階段確認的 destructive 操作

第一次呼叫：


curl -X POST https://api.hypelink.app/api/v1/tools/events.delete \
  -H "Authorization: Bearer hl_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"uuid": "206e879c-..."}'

回傳：


{
  "ok": false,
  "confirmToken": "YTA4MGNm…",
  "willDelete": { "eventUuid": "206e879c-..." }
}

第二次帶 confirmToken：


curl -X POST https://api.hypelink.app/api/v1/tools/events.delete \
  -H "Authorization: Bearer hl_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "206e879c-...",
    "confirmToken": "YTA4MGNm…"
  }'

回應格式

所有呼叫都會回傳同一份結構：


type ToolResult = {
  ok: boolean;
  // 成功時的回傳資料（shape 依 tool 而定）
  data?: unknown;
  // dry_run 時的變更描述
  changes?: Array<{ resource: string; action: string; after?: object; before?: object }>;
  // destructive 第一階段時的確認 token
  confirmToken?: string;
  willDelete?: Record<string, unknown>;
  // 警告（非致命）
  warnings?: string[];
};

錯誤統一回 4xx/5xx + body：


{
  "ok": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "uuid 不能為空"
  }
}

HTTP 狀態碼 ↔ 錯誤碼對照

HTTP	錯誤碼	意義
200	—	成功
400	`VALIDATION_FAILED` / `CONFIRM_REQUIRED` / `CONFIRM_INVALID`	參數有問題
401	—	沒帶 Bearer / token 無效
403	`SCOPE_DENIED`	token 缺對應 scope（自動從 `tools/list` 中隱藏該 tool）
404	`NOT_FOUND`	tool 不存在、或目標物件不存在
409	`CONFLICT`	重名 / 同時編輯衝突
429	`RATE_LIMIT`	60 req/min/token，等 30s 再試
500	`INTERNAL`	後端錯誤

完整 Tool 清單

請看：

MCP 可用 Tools — 100 個 tools 依首頁資訊 / 首頁設計 / 活動分組
Swagger UI — 互動式瀏覽 + 試打 API
openapi.json — spec 原始檔（餵給 Postman / Insomnia / OpenAPI Generator）

SDK / Codegen 建議

OpenAPI 3.1 spec 完全自動產生，相容主流 codegen 工具：


# Postman：直接 Import → URL
https://api.hypelink.app/api/v1/openapi.json
 
# TypeScript fetch client
npx openapi-typescript https://api.hypelink.app/api/v1/openapi.json -o hypelink.d.ts
 
# Python httpx + openapi-python-client
openapi-python-client generate --url https://api.hypelink.app/api/v1/openapi.json
 
# Go
oapi-codegen -package hypelink -generate types,client \
  https://api.hypelink.app/api/v1/openapi.json > hypelink.go

與 MCP 的差異 / 何時用 OpenAPI

✅ 用 OpenAPI 比較方便的情境

Make.com / n8n / Zapier 等無代碼工具直接接 REST + spec
自家後端用 axios / fetch / okhttp 呼叫
想用 Postman / Insomnia 互動測試
需要 codegen 產 SDK
想在 CI / cron job 排程 webhook 不到的批次任務

✅ 用 MCP 比較方便的情境

在 Claude Code / Cursor / Claude Desktop 內讓 AI 自動呼叫
對話式整合（LLM 自己決定要呼哪個 tool）

兩邊 token、scope、audit、rate limit 完全共用，可同一把 token 同時用。

安全提醒

跟 MCP 同一份：MCP - Getting Start