Vesper

个人 API ​

应用通过一套基于 HTTPS 的 JSON API 和 Vesper 通信，你的脚本也可以用个人 token 调用同一套 API，每个 token 对应一个空间。大多数脚本用命令行工具更方便；命令行覆盖不到的地方再直接调 API。

Token ​

在 设置 → 连接 → 个人 token 创建，每个请求都带上：

sh
curl -H "Authorization: Bearer vsp_…" https://noted-this.date/api/entries

token 自带解锁钥匙，不需要 passkey 就能读你的内容。它只显示一次，请像密码一样保管，不用了就在同一页吊销。写入需要 Pro。

记录 ​

请求作用
GET /api/entries返回 { entries, next }，按时间倒序，含照片。?in=all|favorites|archive、?q=、?tag=、?day=YYYY-MM-DD、?fromDate=、?toDate= 筛选，?pinned= 区分置顶，?before= 传上一页的 next
GET /api/entries/{id}一条记录：meta、Markdown body 和 photos
POST /api/entries写一条记录，见下文
PATCH /api/entries/{id}修改 body、tags、visibility、pinned、favorite、archived
DELETE /api/entries/{id}永久删除，连同没有被其他记录用到的照片
POST /api/entries/{id}/publish发到已连接的 { "provider": "x" }、"threads"、"bluesky" 或 "telegram"（Pro，实验性）

纯文字的记录用 JSON：

json
{ "body": "下了一天雨。", "tags": ["天气"], "visibility": "private" }

occurredAt（毫秒）、pinned、favorite 和 archived 可以不传，默认是当前时间和 false。visibility 是 private 或 public；公开的记录任何人都能通过 /e/{id} 访问。

带照片的记录分两步：

  1. 用 PUT /api/photos 逐张上传原图：请求体是图片，Content-Type 写图片类型，X-Content-SHA256 写十六进制的 SHA-256。支持 JPEG、PNG、WebP、GIF 和 AVIF，每张最大 200 MB；HEIC 需要先转换。
  2. 用 multipart/form-data 发送记录：先放一个 entry 字段，内容是上面的 JSON；然后每张照片按顺序放 digest、thumb 缩略图（JPEG）、mime 类型和 meta JSON（width、height、thumbHash、takenAt、geo、place、exif）。每条最多四张，单次请求不超过 8 MB。

缩略图是长边不超过 960 px 的 JPEG，thumbHash 是它的 ThumbHash，用 base64url 编码。takenAt 是毫秒时间戳或 null，geo 是 { "lat", "lng" } 或 null。

照片 ​

请求作用
GET /api/photos返回 { photos, next }：每页 24 条记录的照片，含所属记录、拍摄时间和地点；筛选和 ?before= 同记录
GET /api/photos/{id}?size=thumb缩略图；size=original 取原图

标签和空间 ​

GET /api/tags 列出所有标签及数量；PATCH /api/tags 传 { "from", "to" } 在所有记录上重命名标签，"to": null 则移除它。

GET /api/workspace 返回 token 所属的空间：handle、套餐、角色、权限范围，以及 write（套餐或 token 不能写时为 false）。

频率限制 ​

每个空间每分钟最多 120 个 API 请求，超过会返回 429 和 Retry-After。

错误 ​

错误是带 message 的 JSON：

状态码含义
400输入不合法
401没有有效的 token
403缺少权限，或当前是 Free 套餐
404找不到
423空间已锁定
429请求太频繁，等一分钟再试
502X、Threads、Bluesky 或 Telegram 拒绝发布