開放 API v1：用個人令牌調用組件世界

MCP 能做的事，開放 API 都能做，適合腳本、iOS 快捷指令、自動化工具。先在設定 → API 與 AI 連線新建一個個人 API 令牌。

基本用法

• 地址前綴：https://widgetstore.net/widget/api/v1
• 認證：請求頭 Authorization: Bearer wsp_…
• 請求體：JSON（Content-Type: application/json）
• 時間：日期用 YYYY-MM-DD，按北京時間算「今天」

更新狀態的例子：

curl -X PUT https://widgetstore.net/widget/api/v1/me/status \
  -H "Authorization: Bearer wsp_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"在京都度假，下週回來","emoji":"🏖"}'

成功時返回：

{
  "code": 0,
  "data": { … },
  "summary": "Status set to \"🏖 在京都度假，下週回來\" on personal page …",
  "links": { "page": "…" },
  "operationId": "…"
}

summary 是一句人能看懂的說明；修改類介面帶 operationId，可以用來撤銷。

介面

方法和路徑	做什麼	權限
GET /me	你的空間概覽：組件、主頁、起始頁、待辦、資料表	讀取
PUT /me/status	更新狀態：text（≤140 字）、emoji，clear: true 清空	狀態
GET /me/widgets?limit=	你的組件列表（帶嵌入連結）	讀取
POST /me/widgets	新建組件：widget（組件 ID 或 slug）、values、title、lang	組件
PATCH /me/widgets/{id}	修改組件：values（只改給出的欄位）、title	組件
POST /me/countdowns	新建倒數計時：title、date、mode（countdown / anniversary / countup）、repeat	組件
GET /widget-types?category=&type=&lang=	組件庫裡的組件類型	—
GET /widget-types/search?q=&lang=	按描述搜尋組件，返回可填的欄位	—
POST /me/startpages/links	往起始頁加網站：url、name，可選 startPage、page	起始頁
POST /me/page/cards	往個人主頁加卡片：type（link / text / title / widget）、url、title、text、size、position	個人主頁
POST /me/focus/todos	加待辦：title、due、estimateMinutes、priority	專注
POST /me/focus/habits/{習慣名}/check-in	習慣打卡：date、count、note	專注
POST /me/focus/sessions	記專注：minutes、task、date、mode	專注
GET /me/tables	我的資料：表列表	讀取
GET /me/tables/{表名或 ID}/records?from=&to=&limit=	查記錄	讀取
POST /me/tables/{表名或 ID}/records	加記錄：values、date	我的資料
POST /me/operations/{operationId}/undo	撤銷一次修改	—

搜尋和類型列表不需要額外權限，但仍然要帶令牌、計入調用次數。沒有刪除介面。

錯誤

出錯時 HTTP 狀態碼不是 200，返回 { "code": 狀態碼, "msg": "錯誤碼", … }：

狀態碼	錯誤碼	說明
400	invalid_json / invalid_params	請求體不是 JSON，或欄位不對（errors 裡有具體欄位）
400	blocked_words	公開內容沒通過內容安全檢查
401	unauthorized / token_invalid / token_expired / token_revoked	沒帶令牌、令牌不對、過期或已撤銷
403	insufficient_scope	令牌沒有這個權限（required 是需要的權限）
403	pro_required	這個組件需要 Pro
404	not_found / widget_not_found / table_not_found / start_page_not_found …	找不到對象
409	undo_not_allowed	不能撤銷（reason：already_undone / too_old / newer_change / not_undoable）
429	rate_limited / api_daily_limit	每分鐘或每天的次數用完了（retryAfter 秒後再試）
503	api_paused	API 臨時暫停（維護或站點負載過高）

額度

免費版每天 100 次調用、其中 30 次修改、每分鐘 20 次；Pro 每天 300 次、100 次、每分鐘 60 次。和 MCP 共用帳號額度，詳見令牌與操作記錄。

相容的老介面

/api/v1/widgets/instances（建立、修改、讀取組件實例）也接受個人令牌：POST 需要「組件」權限、GET 需要「讀取」，同樣記操作記錄、計入額度。新程式碼建議用上面的 /me/widgets。