API 参考

本 Rust 版本的完整 REST 接口定义：92 项操作、119 个结构、一个当前版本。

这里只提供静态参考。官网不会索取令牌或发送 API 请求。集成应使用应用地址，而不是本站地址。

认证、分页和重试请先阅读 API 访问。也可下载完整 OpenAPI JSON。

选择应用地址与凭据

请求应发送到自己的应用地址下的 /api/v1。个人访问令牌或会话访问令牌通过 Authorization: Bearer … 传递。仅有刷新 Cookie 不能认证普通 REST 请求。PAT 以所属账号的身份操作，不会增加权限或绕过空间成员资格。先通过 GET /api/v1/auth/me 验证凭据。不要把真实令牌放入 URL、示例、截图或问题报告。

curl --fail-with-body \
  -H "Authorization: Bearer $MEMOS_TOKEN" \
  "$MEMOS_URL/api/v1/auth/me"

资源名与 URL 路径片段

memos/example 这样的资源名不同于末尾标识 example。调用 GET /api/v1/memos/{memo} 时，只将 example 填入 {memo}；其他 JSON 字段要求笔记资源名时则使用完整的 memos/example。用户路径使用用户名，不是显示名称或数据库 ID。空间成员和邀请的末尾片段是目标用户名。请通过客户端库或 curl --data-urlencode 对查询参数编码。

JSON 请求体取决于操作

请使用操作页指定的请求体结构。CreateMemo 与 UpdateMemo 直接接收 Memo 对象，不使用 {memo: …} 包装；附件和引用集合替换操作接收各自的请求对象。绑定路径的资源名由 URL 提供。JSON 字节字段使用 Base64，64 位计数和偏移量使用十进制字符串，时间戳使用 RFC 3339 字符串。只读字段描述输出；共用资源结构中的必需字段列表不表示 PATCH 时必须重发所有字段。示例已对照接口定义和 Rust 绑定代码核查，没有对真实实例执行。

显式指定更新掩码

updateMask 查询值是以逗号分隔的 protobuf 字段路径，例如 content,pinned 或 display_name。这些路径可能不同于 JSON 中的 lowerCamelCase 字段名，例如 displayName。REST 可为某些 PATCH 请求体推导掩码，但嵌套设置有各自的行为，因此应显式使用支持的掩码。尤其要注意：UpdateInstanceSetting 忽略 updateMask，并替换所选设置的完整载荷；修改配置前请阅读该操作的警告。

根据实际响应翻页

实现分页的接口需要原样使用 nextPageToken，并保持筛选、状态和排序不变，直到令牌为空。将令牌视为不透明值：ListAttachments 的游标格式与大多数列表不同。通常默认 50 条、上限 1000 条，但一些小集合虽然声明 pageSize/pageToken，仍一次返回全部结果；例外会在操作说明中标明。集合结果经过权限过滤，空列表不等于对象不存在。

先理解错误，再决定重试

REST 失败会返回 HTTP 状态和 JSON Status 对象，其中包含数字型 gRPC code、message 和 details。Connect 使用自己的传输错误格式，不应按同一种方式解析。无效输入、缺少凭据、访问被拒、资源不可用以及前置条件不满足，需要不同的处理。NOT_FOUND 也可能用于隐藏无权访问或已归档的资源。限流失败可能携带 Retry-After、RateLimit、RateLimit-Policy 和结构化 RetryInfo，应按其要求等待。写入后响应丢失或存储清理失败时，数据库变更可能已经提交；重复创建、删除或替换前先读取实际状态。

空结果与文件下载

未声明请求体表示不需要构造 JSON 载荷。返回 protobuf Empty 的命令在 Rust REST 传输中返回 HTTP 200 与 JSON {}；OpenAPI 快照没有为这些命令声明响应结构。ExportMemos 则不同：成功响应是原始 ZIP 字节，媒体类型由服务端 Content-Type 指定，不是 JSON 或 Base64 包装。应保存为文件，同时检查非成功响应中的错误。