API 說明
讓你自己的程式、腳本或自動化工具讀寫一個空間的紀錄。API 和「連接 AI 助理(MCP)」用同一把金鑰,回傳的資料也一樣。
用 n8n、Make、Zapier 的話,可以直接從自動化範本開始。
1. 取得金鑰
到「設定 → 連接 AI 助理(MCP)」建立一個連接網址。網址最後 okm_ 開頭的那一段就是金鑰。一把金鑰只能用在一個空間;要寫入的話,建立時勾「允許新增紀錄」。
金鑰等於這個空間的鑰匙,不要放進公開的程式碼。不用了就在同一個地方按「停用」。
2. 帶著金鑰呼叫
網址開頭是下面這個,金鑰放在 Authorization 標頭:
https://octokeep.app/api/v1
curl https://octokeep.app/api/v1/records?q=%E5%A0%B1%E5%83%B9 \
-H "Authorization: Bearer okm_…"
curl -X POST https://octokeep.app/api/v1/records \
-H "Authorization: Bearer okm_…" \
-H "Content-Type: application/json" \
-d '{"text": "客戶回覆了 #報價", "parent_ids": ["abc123def456"]}'
成功時回傳 {"data": …};新增成功是 201。日期時間都用金鑰主人的時區。用 API 新增的紀錄,來源會標成「API:金鑰名稱」。
3. 可以呼叫的網址
-
GET/records搜尋紀錄,新的在前。參數:q(關鍵字,空白分隔,全部都要出現)、tag(標籤,不含 #)、date(某一天 YYYY-MM-DD)、limit(預設 20,上限 50)
-
GET/records/{id}讀一則:完整內容、標籤、接在哪幾則後面(parents)、後面接了哪幾則(children)
-
GET/records/{id}/chain整串:前因與後續。每則的 step 是隔幾層(負的是前因、正的是後續)。預設上下各 7 則,參數 up、down(上限 30)、up_skip、down_skip 可以再載入
-
GET/days/{YYYY-MM-DD}某一天寫的所有紀錄,依時間排序
-
GET/recent最近幾天的紀錄。參數:days(預設 7,上限 31)、limit(預設 50,上限 100)、since(只要這個時間之後新寫進來的,每則附寫入時間 created,適合定時檢查)
-
GET/pending超過幾天還沒有下文的紀錄,最久的在前,每則附放了幾天(days_waiting)。參數:days(預設 7)、limit(預設 50,上限 100)
-
GET/brief早安卡的內容:昨天沒接完的、放很久的、以前的今天、夥伴接在你後面的
-
GET/space空間概況:名稱、紀錄數、常用標籤、常提到的人
-
POST/records新增一則(金鑰要勾「允許新增紀錄」)。JSON:text(必填,可用 #標籤、@人名)、parent_ids(接在哪幾則後面)、occurred_at(YYYY-MM-DD HH:MM,預設現在)
4. 出錯時
會回傳 {"error": {"code": …, "message": …}}:
| 401 | invalid_key | 金鑰錯了或已停用 |
| 403 | read_only | 金鑰只能讀,或你在這個空間是唯讀 |
| 404 | not_found | 找不到這一則 |
| 422 | invalid_request | 參數不對,message 會說哪裡不對 |
| 429 | 太頻繁了:每分鐘最多 120 次 |