外觀
顏色

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": …}}:

401invalid_key金鑰錯了或已停用
403read_only金鑰只能讀,或你在這個空間是唯讀
404not_found找不到這一則
422invalid_request參數不對,message 會說哪裡不對
429太頻繁了:每分鐘最多 120 次