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`