PainGuild Archive Room

PainGuild API

中小企業痛點蒐集與分析平台 — REST API 文件

Base URL: https://painguild.app · 認證: REST / MCP / A2A 用 x-api-key，帳號自助端點用 JWT Bearer · 分頁: ?limit=20&offset=0

取得 API Key: POST /auth/register → POST /auth/verify → response 含 api_key。POST /auth/login 只會回傳 JWT，不會重新顯示 api_key。
所有 /api/ 路徑同時支援 /api/v1/ 前綴。支援 8 語系: zh, en, ja, ko, es, id, th, hi（Accept-Language header 或 ?lang=）
如何閱讀這份文件

本頁提供每個公開端口的用途、認證方式與常見 query/body 提示；若你需要精確 request/response contract、headers、path params 與範例 payload，請直接讀 /api/agent-guide（JSON）。像 :id / :slug 是 path params，括號裡的 ?foo= 表示常用 query 參數，body: 表示最小必要 request body。

怎麼開始使用

大部分功能（REST、MCP、A2A）都使用 x-api-key；只有帳號自助端點（例如 /auth/me）使用 Authorization: Bearer <jwt>。

1. REST API：如果你要直接使用網站功能，先從 REST 開始，例如分析對話、登錄解法、查看媒合。

curl -s -X POST "https://painguild.app/api/analyze" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"industry":"food_service","text":"客人常抱怨尖峰時段等太久"}'

2. MCP：如果你要讓 LLM 自動把 PainGuild 當工具呼叫，使用 /mcp；舊 client 才用 /mcp/sse。

POST /mcp
 Headers: x-api-key, MCP-Protocol-Version: 2025-11-25, Accept: application/json, text/event-stream
 Body: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"your-client","version":"1.0.0"}}}

3. A2A：如果你要讓另一個 agent 跟 PainGuild 協作，先讀 Agent Card，再送 task，之後用 GET /a2a/tasks/:id 或 /stream 追蹤。

GET /.well-known/agent.json
POST /a2a/tasks
GET /a2a/tasks/:id
GET /a2a/tasks/:id/stream

公開（不需認證）

MethodPath說明
GET/health健康檢查
GET/health/deep深度健康檢查（DB / memory / uptime）
GET/api/templates15 產業 × 8 分類模板
GET/api/leaderboard解法者排行榜（?period=rolling_12m|all_time）
GET/api/quests公開任務看板（?grade=S&industry=food_service®ion=Taiwan）
GET/api/announcements系統公告
GET/api/agent-guideAgent 整合說明（JSON）
POST/api/payment/webhook金流 provider webhook 回調（供 Stripe 呼叫，需 stripe-signature）
GET/auth/providers可用 OAuth provider 查詢

認證

MethodPath說明
POST/auth/registerEmail 註冊（發驗證碼）· body: {email, password, consent:true}
POST/auth/verify驗證碼確認 → 回傳 token + api_key
POST/auth/loginEmail 登入 → 回傳 JWT token（不會重新顯示 api_key）
POST/auth/logout清除瀏覽器 session cookie
POST/auth/session/bootstrap用既有 JWT 換成瀏覽器 session cookie
GET/auth/me查詢目前用戶資訊（需 JWT Bearer）
POST/auth/forgot-password發送密碼重設碼
POST/auth/reset-password重設密碼
PUT/auth/me/consent同意條款 或 撤回同意 · body: {action:"accept"|"withdraw"}
GET/auth/me/export匯出所有個人資料（GDPR 資料可攜權，需 JWT）
DELETE/auth/me刪除帳號（GDPR 被遺忘權，不可逆，需 JWT）
POST/auth/me/change-email申請變更 Email（Step 1：發驗證碼到原信箱）
POST/auth/me/change-email/verify驗證原信箱碼 → 發驗證碼到新信箱
POST/auth/me/confirm-email驗證新信箱碼 → 完成 Email 變更
POST/auth/complete-emailOAuth 補填 Email（發驗證碼，需 JWT）
POST/auth/complete-email/verify確認補填 Email 驗證碼（需 JWT）

痛點分析（需 x-api-key）

MethodPath說明
POST/api/analyze分析對話萃取痛點 · body: {industry, text, tenant_grade?}
GET/api/pain-points查詢痛點（?sort=newest|oldest|severity&status=active|archived）
PUT/api/pain-points/:id/status歸檔/恢復痛點
DELETE/api/pain-points/:id刪除痛點
GET/api/report痛點排名報告 pro+
GET/api/benchmark同業匿名百分位排名（?industry=&tenant_id=）
GET/api/benchmark/status查詢 Benchmark / 媒合 opt-in 狀態
POST/api/benchmark/opt-in設定 Benchmark 參與 + 媒合 opt-in

媒合（需 x-api-key）

MethodPath說明
POST/api/solutions登錄解決方案 · body: {industry, category, title, description, url?, region?}
GET/api/solutions查詢自己的方案
PUT/api/solutions/:id更新方案（修改後需重新審核）
DELETE/api/solutions/:id下架方案
GET/api/solutions/market匿名痛點需求統計
GET/api/matches查詢推薦的解決方案 有月度次數限制
POST/api/matches/:id/respond回應推薦（interested/dismissed）
GET/api/matches/:id/detail媒合詳情（雙方同意後揭露聯絡資訊）
GET/api/matches/inbound方案方查看收到的媒合請求
PUT/api/contact設定聯絡資訊（媒合揭露用）
GET/api/contact查詢聯絡資訊

回饋（需 x-api-key）

MethodPath說明
POST/api/feedback提交回饋（upsert）· body: {type, target_id, rating, comment?}
GET/api/feedback查詢自己的回饋
GET/api/solutions/:id/reviews方案匿名評價摘要

訂閱 + 排行榜（需 x-api-key）

MethodPath說明
GET/api/subscription查詢目前方案 + 用量限制
GET/api/subscription/plans列出所有可用方案與限制
GET/api/subscription/contribution貢獻換額度進度（free 用戶）
POST/api/payment/checkout建立 Stripe 付款 session · body: {plan, success_url, cancel_url} · redirect URL 需為允許 origin
POST/api/payment/portal建立 Stripe 帳務 portal session · body: {return_url} · return_url 需為允許 origin
POST/api/payment/linepay/confirmLINE Pay 確認端點（尚未啟用）· body: {transaction_id}
POST/api/subscription/upgrade直接升級方案（legacy admin-only；一般用戶請走 checkout）
POST/api/subscription/cancel取消訂閱
POST/api/subscription/reactivate恢復訂閱
GET/api/leaderboard/me我的排名 + 位階
PUT/api/display-name設定排行榜顯示名稱

進階功能 pro / max

MethodPath說明
GET/api/notifications查詢通知設定
PUT/api/notifications更新通知（開關、webhook URL、嚴重度門檻）
GET/api/notifications/log通知發送紀錄
GET/api/export匯出 CSV（?type=pain-points|report&min_severity=4）
GET/api/export/quota本月匯出額度
GET/api/trend趨勢分析（?granularity=week|month&days=90&category=）
GET/api/pro-docsPro 文件目錄
GET/api/pro-docs/:slug取得文件內容（?lang=zh）
GET/api/max-docsMax 專屬文件目錄
GET/api/max-docs/:slug取得 Max 文件內容（?lang=zh）

專案管理（需 x-api-key）

MethodPath說明
POST/api/projects從媒合建立專案（帶里程碑）
GET/api/projects列出我的專案
GET/api/projects/:id專案詳情（含里程碑 + 留言）
PUT/api/projects/:id更新專案狀態
POST/api/projects/:id/milestones新增里程碑
PUT/api/projects/:id/milestones/:mid更新里程碑狀態
POST/api/projects/:id/milestones/:mid/extend申請里程碑延期
PUT/api/projects/:id/milestones/:mid/extend審批里程碑延期
POST/api/projects/:id/messages專案留言

其他（需 x-api-key）

MethodPath說明
GET/api/my-keys列出自己的 API Key
POST/api/my-keys建立新 API Key（方案上限）
DELETE/api/my-keys/:prefix刪除 API Key
POST/api/support客服對話 · body: {message, locale?}
POST/api/contact-admin聯絡管理員 · body: {subject, content}
GET/api/timezone查詢租戶時區
GET/api/security-tier查詢安全等級
POST/api/matches/:id/accept方案方接受媒合

Agent 整合協定

協定端點說明
MCP/mcp · /mcp/sse · /mcp/messagesModel Context Protocol — Streamable HTTP（建議）+ legacy SSE 相容
A2A/.well-known/agent.json · POST /a2a/tasks · GET /a2a/tasks · GET /a2a/tasks/:id · GET /a2a/tasks/:id/stream · POST /a2a/tasks/:id/cancelGoogle A2A — 委派任務、查詢狀態、接收任務事件

方案比較

FreePro $17/moMax $168/mo
Analyze quota15/mo50/day500/day
Benchmark—✅✅
Solution slots1620
Match views/mo130Unlimited
History7 days90 days365 days
API Keys1520
Reports/Trends/Export—✅✅
Webhook notifications—✅✅
Active projects15Unlimited
API rate60/min120/min200/min