REST API

從您自己的指令碼儲存和刪除數百到數千頁的文件。沒有 AI 參與。

不用一份一份手動輸入 PDF、試算表、報告，整個過程交給指令碼：由您自己擷取並切分文字，把結果送過來即可。

在這裡儲存的內容和透過連接的 AI 儲存的完全一樣——進同一個知識庫，您的 AI 也用同樣的方式找回來。

讀取以 id 進行，不是搜尋。 依語意取回仍由 MCP 和您的儀表板負責。

開始使用

在 REST API 卡片裡建立金鑰——它在您的帳戶頁面上。金鑰的名稱會當成用它儲存的一切內容的來源被記錄下來，取一個日後認得出的名字，例如 Import script、pdf-importer。
金鑰在建立之後只顯示一次。請當場複製，之後無法再次顯示。
金鑰可以建立任意多把，也可以隨時個別刪除。

驗證

Base URLhttps://contextick.ai

Authorization: Bearer api_xxxxxxxx

只有以 api_ 開頭的金鑰在這裡有效。MCP 金鑰或 OAuth 權杖在這個 API 上會得到 401，REST API 金鑰在 MCP 端點上同樣是 401——兩個入口彼此分開，撤銷其中一把不會影響另一把。

端點

POST `/api/v1/notes`

儲存一筆。

Body

Field	Type	Required	Limit
title	string	✓	120 個字元——超出會被截斷
summary	string	✓	300 個字元——超出會被截斷
content	string	✓	16,000 個字元——超出會被拒絕

三個都不能留空；空值會被拒絕，而不是靠猜測填上。

Request

curl -X POST https://contextick.ai/api/v1/notes \
  -H "Authorization: Bearer api_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Q3 report","summary":"Revenue and headcount for Q3.","content":"…"}'

Response 201

{ "id": 42, "saved_items": 118, "stored_bytes": 1048576 }

saved_items 和 stored_bytes 是儲存之後的總量。如果沒能讀到，欄位會整個省略，而不是給 0。

記錄在項目上的來源就是金鑰的名稱，無法由請求指定。

GET `/api/v1/notes/{id}`

讀取一筆的全文。

Request

curl https://contextick.ai/api/v1/notes/42 \
  -H "Authorization: Bearer api_xxxxxxxx"

Response 200

{ "id": 42, "title": "Q3 report", "summary": "…", "content": "…",
  "author": "you@example.com", "origin": "Import script", "created_at": "…",
  "status": "ready", "group_id": null, "times_opened": 3 }

在這裡讀取不會改變 times_opened——這個計數記的是您開啟的次數，不是指令碼同步的次數。

status 是 ready、pending 或 failed——只有 ready 的項目能被搜尋到。

group_id 只在項目來自上傳檔案時才有，否則是 null。不存在的 id 會回傳 404。

GET `/api/v1/notes/group/{group_id}`

列出一個上傳檔案被拆成的各部分。

Request

curl https://contextick.ai/api/v1/notes/group/6f1c2a94 \
  -H "Authorization: Bearer api_xxxxxxxx"

Response 200

{ "group_id": "6f1c2a94", "title": "Q3 report",
  "part_count": 13, "ready": 11, "pending": 2, "failed": 0,
  "items": [
    { "id": 42, "title": "Q3 report (1/13)", "status": "ready" },
    { "id": 43, "title": "Q3 report (2/13)", "status": "pending" } ] }

title 是檔案自身的標題，取自第一個部分並去掉了分片編號；那四個計數省得您為此去走訪 items。

各部分按 id 順序回傳，不含內文——需要某一部分的 content 時，請呼叫上面的單筆讀取。

group_id 來自上面的單筆讀取結果。沒有對應項目的標籤會回傳 404。

DELETE `/api/v1/notes/group/{group_id}`

刪除一個上傳檔案的全部部分。

Request

curl -X DELETE https://contextick.ai/api/v1/notes/group/6f1c2a94 \
  -H "Authorization: Bearer api_xxxxxxxx"

Response 200

{ "group_id": "6f1c2a94", "deleted": [42, 43, 44],
  "saved_items": 117, "stored_bytes": 1040000 }

要麼全刪要麼不刪——帶該標籤的每個部分都在同一個交易裡消失，所以中途中斷也不會留下刪了一半的檔案。

與上面兩個刪除不同，這裡沒有 not_found 陣列：它接收的是一個標籤而不是 id 清單，所以沒有對應項目的標籤會像上面的讀取一樣回傳 404。

GET `/api/v1/notes/changes`

依從舊到新的順序，取回上次查看之後新增的項目。

Query

參數	型別	說明
cursor	整數	上次停下的位置 —— 上一次回應裡的游標。
since	RFC 3339	起始時間點，例如 `2026-09-01T13:00:00+09:00`。必須帶時區偏移。僅用於第一次呼叫。
limit	整數	1–100，預設 50。

先用 since（或什麼都不帶）開始，之後跟著游標走。兩個一起給會出錯。

請求

curl "https://contextick.ai/api/v1/notes/changes?since=2026-09-01T04:00:00Z&limit=50" \
  -H "Authorization: Bearer api_xxxxxxxx"

回應 200

{ "data": [
    { "id": 41, "title": "Q3 report", "summary": "…", "created_at": "2026-09-01T04:00:12Z",
      "origin": "Import script", "status": "ready", "group_id": null } ],
  "pagination": { "limit": 50, "poll_cursor": "41" } }

next_cursor 表示還有積壓，立刻請求下一頁。poll_cursor 表示已經追平，存起來稍後再查。兩者只會出現一個。

項目依從舊到新回傳，所以游標只會前進，就算停了很久也不會漏掉任何一筆。內文不包含在內 —— 需要時再單筆讀取。

since 是起點而不是過濾條件，可能會順帶多出幾筆稍早的項目。status 可能是 pending —— 已存下、可讀取，但還搜尋不到。刪除以及之後的狀態變化不會出現在這裡。

DELETE `/api/v1/notes/{id}`

刪除一筆。

Request

curl -X DELETE https://contextick.ai/api/v1/notes/42 \
  -H "Authorization: Bearer api_xxxxxxxx"

POST `/api/v1/notes/delete`

一次刪除多筆。

Body

Field	Type	Required	Limit
ids	number[]	✓	每次 50 個——超出會被拒絕

批次匯入之後要收回，靠的就是這個。

Request

curl -X POST https://contextick.ai/api/v1/notes/delete \
  -H "Authorization: Bearer api_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"ids":[42,43]}'

Delete response 200

{ "deleted": [42], "not_found": [43], "saved_items": 117, "stored_bytes": 1040000 }

兩個刪除回傳的形狀相同。不存在的 id 不算錯誤，會列在 not_found 裡。 刪除是永久的，無法復原。

錯誤

所有失敗都用同一種形狀：

{ "error": { "code": "quota_exceeded", "message": "…" } }

請依 code 分支。message 是給人讀的文字，可能隨時改動。

400 改好請求再重試 empty_titleempty_summaryempty_contentcontent_too_longtoo_many_idsinvalid_bodyinvalid_idinvalid_query

401 檢查 api_ 金鑰 unauthorized

402 處理付款狀態——期間取回仍可使用 payment_past_duesubscription_pausedsubscription_canceledrefund_pending

404 該 id、分組或路徑不存在 not_foundendpoint_not_found

405 改用 Allow 標頭裡的方法 method_not_allowed

415 請加上 Content-Type: application/json unsupported_media_type

429 稍後重試同一個請求 rate_limitedembedding_rate_limited

507 騰出空間或換更大的方案——不要原樣重試 quota_exceeded

503 500 暫時性問題或伺服器端問題——稍後重試

接收 Webhook

把儲存、刪除和項目變為可搜尋推送到您自己的網址，現在有了獨立的頁面——請求標頭、四種事件類型、簽章驗證和重試都在 Webhook 文件裡。

需要知道的

能存多少取決於您的方案——見價格。
呼叫有每小時和每天的上限，429 會帶上 Retry-After。上限遠高於一般腳本的用量；要一次匯入一份長文件，請改從儀表板上傳——那是按檔案計數，不是按分段。
有不清楚或用不了的地方嗎？聯絡我們——每一封來信都由真人閱讀。

REST API

開始使用

驗證

端點

POST /api/v1/notes

Body

Request

Response 201

GET /api/v1/notes/{id}

Request

Response 200

GET /api/v1/notes/group/{group_id}

Request

Response 200

DELETE /api/v1/notes/group/{group_id}

Request

Response 200

GET /api/v1/notes/changes

Query

請求

回應 200

DELETE /api/v1/notes/{id}

Request

POST /api/v1/notes/delete

Body

Request

Delete response 200

錯誤

接收 Webhook

需要知道的

POST `/api/v1/notes`

GET `/api/v1/notes/{id}`

GET `/api/v1/notes/group/{group_id}`

DELETE `/api/v1/notes/group/{group_id}`

GET `/api/v1/notes/changes`

DELETE `/api/v1/notes/{id}`

POST `/api/v1/notes/delete`