跳到主要内容

Older HTTP API

v1OpenAPI 3.1.0

Older 服务端对外 HTTP 接口。除特别说明外，响应为 JSON。
鉴权采用「短寿命访问令牌 older_auth + 长寿命刷新令牌 older_refresh_token」双 Cookie 模型；访问令牌过期后由 POST /api/v1/user/refresh 凭刷新令牌续期（设计见 resources/50-http-api/spec.md）。
账号角色只有 admin 与 user 两种，管理接口仅 admin。登录保护接口各自属于一项功能（见 Feature）：普通用户缺省都能用，管理员可以把某个普通用户限定为只能用其中几项，受限的账号访问其余功能得到 HTTP 403，会话本身仍然有效；管理员始终不受限。角色与功能限定在每次请求时复核，变更立即生效。记账接口里的 HTTP 403 还表示已是账本成员，但该操作只有账本所有者能做。
处理器未捕获的异常由会话层统一兜底：请求体 JSON 语法/类型错误与参数解析错误返回 400，其他内部错误返回 500，正文均为 Error 信封，连接保持可用。

  • 132 个接口
  • 17 个标签
  • 65 个数据模型
  • 2 个服务器

服务器

https://amass.fun生产环境（amass.fun）
http://localhost:8080本地开发（端口以 settings.toml 的 HttpServer 配置为准）

鉴权方式

cookieAuthapiKey · cookie · older_auth
登录后下发的 HTTP-only 短寿命访问令牌（Max-Age=900s）；过期后须经 /api/v1/user/refresh 续期。会话有效而账号没能从存储里读出来时，受保护的入口回复 500 而不是 401，会话不受影响。
refreshCookieAuthapiKey · cookie · older_refresh_token
登录后下发的 HTTP-only 长寿命刷新令牌（Path=/api/v1/user; Max-Age=2592000s），仅用于 /api/v1/user/refresh 换取新访问令牌。
bearerAuthhttp · bearer
服务密钥，将 Authorization 头中的密钥与服务端配置做常量时间比较：/api/v1/search/reindex 比对 [Search] ApiKey，/api/v1/notebook/update 比对 [Gitea] AccessToken。

分析

5 个接口

访问统计与站点信息

用户

10 个接口

注册、登录、邮箱验证与会话

设备

6 个接口

设备列表、信息与控制

笔记本

3 个接口

笔记本文件读取与同步

搜索

3 个接口

站内搜索：匿名检索笔记与博客与上报看过结果的查询，记录由站点部署流水线整体替换

设置

2 个接口

运行时设置

访问记录

2 个接口

VisitRecord 查询与删除

便签

17 个接口

TickNote 便签与便签的分享链接，以及待办树与待办的周期提醒。便签与待办都按登录账号各自隔离，只对本人可见，别人的一律按不存在处理（HTTP 404）；分享链接不必登录，交出便签的纯文本原文；提醒只归已批准的管理员，到点经企业微信推送给站长；响应禁止缓存

图床

12 个接口

登录用户的公开/私密图片与合集管理，匿名公开图库

记账

39 个接口

账本与其中的收支账目。每条账目属于一个账本，账本的成员共同记账、互相可见；不是成员的账本一律按不存在处理（HTTP 404）。金额一律以分为单位的整数，响应禁止缓存

聊天室

3 个接口

聊天室消息与实时 WebSocket

评论

4 个接口

挂在页面路径下的评论与回复。访客凭自报的昵称发表，登录用户以账号身份发表；仅登录可见的评论流只对登录用户开放；删除只归管理员。响应禁止缓存

信令

1 个接口

WebRTC 信令 WebSocket 端点（按客户端 ID 转发 SDP/ICE）

管理

11 个接口

管理员接口（要求 role=admin 且 status=approved；鉴权失败统一返回 HTTP 403）

系统

5 个接口

Live2D 静态资源、设备探测、通知回调与企业微信回调

发布网关

4 个接口

Vessel 更新客户端匿名读取白名单仓库发布的 Gitea 发布接口子集；站点地址即客户端的 Gitea 实例地址，只接受 GET，正文是 Gitea 形状而非业务信封

测速

5 个接口

仿 LibreSpeed 的网速测试：自包含测速页面及其调用的延迟、访客 IP 与 WebSocket 下载、上传入口；匿名访问，服务端不保存结果，HTTP 响应一律不缓存

数据模型

Envelope

通用业务信封。注意 message 非必有（部分成功响应仅含 code 与 data）。

object通用业务信封。注意 message 非必有（部分成功响应仅含 code 与 data）。
code*integer业务状态码，多数情况下与 HTTP 状态一致（例外见 spec.md「已知偏差」）。
messagestring
dataany业务负载，结构因接口而异。

Error

object
codeinteger
message*string

Device

设备对象。设备记录持久化于 SQLite，在线状态随 MQTT 上线/下线/心跳与心跳超时更新，服务重启后仍可查询。

object设备对象。设备记录持久化于 SQLite，在线状态随 MQTT 上线/下线/心跳与心跳超时更新，服务重启后仍可查询。
device_idstring
namestring
ip_addressarray<string>
mac_addressstring
osstring
versionstring
last_seen_timeintegerUnix 秒
is_onlineboolean
propertiesobject

Feature

需要登录才能使用的功能。ledger 记账；ticknote 备忘与待办；albums 图床；notebook 记事本；devices 设备的删除、关机与唤醒；statistics 访问记录与 URL 过滤规则；comments 以账号身份评论、查看仅登录可见的评论；chatroom 以账号身份进入聊天室、删除聊天消息

string枚举: ledger, ticknote, albums, notebook, devices, statistics, comments, chatroom需要登录才能使用的功能。ledger 记账；ticknote 备忘与待办；albums 图床；notebook 记事本；devices 设备的删除、关机与唤醒；statistics 访问记录与 URL 过滤规则；comments 以账号身份评论、查看仅登录可见的评论；chatroom 以账号身份进入聊天室、删除聊天消息

Gender

账号的性别。unknown 未知，是没有填写时的取值；male 男；female 女

string枚举: unknown, male, female账号的性别。unknown 未知，是没有填写时的取值；male 男；female 女

Birthday

账号的生日，按填写时的历法原样保存，服务端不换算。年在 1900 至今年之间；公历须是真实存在且不晚于今天的日期。农历的 year 是这个农历年开始时所在的公历年，month 是月序，闰月与它所跟的月同序；服务端没有农历历表，农历只核对范围，闰月是否存在、这个月有没有三十由客户端把关

object账号的生日，按填写时的历法原样保存，服务端不换算。年在 1900 至今年之间；公历须是真实存在且不晚于今天的日期。农历的 year 是这个农历年开始时所在的公历年，month 是月序，闰月与它所跟的月同序；服务端没有农历历表，农历只核对范围，闰月是否存在、这个月有没有三十由客户端把关
calendar*stringsolar 公历；lunar 农历
year*integer
month*integer
day*integer农历至多 30
leap_monthboolean是否农历的闰月；公历恒为 false，请求里可以不给

AccountNickname

账号的昵称，按字符计数，首尾空白会被去掉，不能含控制字符；空串表示没有昵称，此时客户端以用户名示人。不能与别的账号的用户名、邮箱或昵称相同（不区分 ASCII 大小写）

string账号的昵称，按字符计数，首尾空白会被去掉，不能含控制字符；空串表示没有昵称，此时客户端以用户名示人。不能与别的账号的用户名、邮箱或昵称相同（不区分 ASCII 大小写）

AccountSummary

object
idinteger
usernamestring
emailstring
statusstringunverified | pending | approved | rejected
rolestring账号角色，含义见本契约开头的说明
created_atintegerUnix 秒
reviewed_atinteger
reviewed_byinteger
reject_reasonstring
featuresarray<Feature>管理员给它限定的可用功能；为 null 表示不受限，管理员恒为 null
nicknameAccountNickname账号的昵称，按字符计数，首尾空白会被去掉，不能含控制字符；空串表示没有昵称，此时客户端以用户名示人。不能与别的账号的用户名、邮箱或昵称相同（不区分 ASCII 大小写）
genderGender账号的性别。unknown 未知，是没有填写时的取值；male 男；female 女
birthdayBirthday账号的生日，按填写时的历法原样保存，服务端不换算。年在 1900 至今年之间；公历须是真实存在且不晚于今天的日期。农历的 year 是这个农历年开始时所在的公历年，month 是月序，闰月与它所跟的月同序；服务端没有农历历表，农历只核对范围，闰月是否存在、这个月有没有三十由客户端把关

VisitRecord

object
idinteger
urlstring
visitorUuidstring
lastUserAgentstring
lastViewTimeintegerUnix 秒
pageViewCountinteger

FilterRule

object
typestring
patternstring

ChatMessage

object
idinteger
nicknamestring账号用户的消息为发送时账号的昵称，没有昵称时为用户名；访客的为自报的昵称
avatar_hashstring头像标识。发言者邮箱去掉首尾空白并转成小写后的 SHA-256（十六进制小写），供客户端向与 Gravatar 接口兼容的头像服务查找头像。邮箱本身不对外给出
websitestring
contentstring
created_atintegerUnix 秒

TickNote

当前账号的一条便签；便签按账号隔离，别的账号看不到

object当前账号的一条便签；便签按账号隔离，别的账号看不到
id*integer
content*string
created_at*integerUnix 秒
share*TickNoteShare便签的分享。持有链接的人不必登录就能读这条便签、正文里引用的便签所有者自己的图片，以及这条便签的附件
attachments*array<TickNoteAttachment>这条便签的附件，按上传的先后排列；没有附件时为空数组

TickNoteAttachment

便签的一个附件。文件存放在 Nextcloud 的便签附件目录下，归它所在便签的所有者

object便签的一个附件。文件存放在 Nextcloud 的便签附件目录下，归它所在便签的所有者
id*integer (int64)
file_name*string上传时的原文件名，下载时原样交还
byte_size*integer (int64)字节数，1 至 20 MiB
content_type*string交出文件时的类型，由服务端在上传时判定：合法 UTF-8 且不含 NUL 的是文本，其余是二进制
created_at*integer上传的 Unix 秒

TickNoteShare

便签的分享。持有链接的人不必登录就能读这条便签、正文里引用的便签所有者自己的图片，以及这条便签的附件

object便签的分享。持有链接的人不必登录就能读这条便签、正文里引用的便签所有者自己的图片，以及这条便签的附件
url*string (uri)分享链接，站点对外地址之下的 /api/v1/ticknote/shared/{token}；令牌只出现在链接里
created_at*integer开启分享的 Unix 秒

TickNoteTodo

一项待办。同一账号的待办经 parent_id 组成若干棵树；已完成的待办其各级子项也都已完成

object一项待办。同一账号的待办经 parent_id 组成若干棵树；已完成的待办其各级子项也都已完成
id*integer (int64)
parent_id*integer (int64)父项 ID，顶层待办为 0
title*string去掉首尾空白后 1 至 500 个字符，不含控制字符；可含 Markdown 行内语法，服务端原样保存
done*boolean
created_at*integerUnix 秒
reminder*TickNoteTodoReminder待办的周期提醒。总是包含全部键，与 frequency 无关的键取中性值（weekdays 为空数组，month_day 与 interval_days 为 0，start_date 为空字符串）

TickNoteTodoReminderInput

待办的周期提醒规则。时刻与日期按服务器本地时区解释；周期用不到的字段可以省略，给了也被忽略

object待办的周期提醒规则。时刻与日期按服务器本地时区解释；周期用不到的字段可以省略，给了也被忽略
frequency*string
time*string到点的时刻，24 小时制 HH:MM
weekdaysarray<integer>每周提醒的 ISO 星期，1 为周一，7 为周日；frequency=weekly 时必填，重复的只算一次
month_dayinteger每月提醒的日子，大于当月天数时取当月最后一天；frequency=monthly 时必填
interval_daysinteger每隔几天提醒一次；frequency=interval 时必填
start_datestring (date)每隔几天提醒的起始日 YYYY-MM-DD，首次就在这一天的该时刻；frequency=interval 时必填
action*string到点行为。notify 在待办未完成时推送一条提醒，已完成则这一次不推送；reopen 把待办连同各级子项改为未完成，各级祖先随之改为未完成，然后推送

TickNoteTodoReminder

待办的周期提醒。总是包含全部键，与 frequency 无关的键取中性值（weekdays 为空数组，month_day 与 interval_days 为 0，start_date 为空字符串）

object待办的周期提醒。总是包含全部键，与 frequency 无关的键取中性值（weekdays 为空数组，month_day 与 interval_days 为 0，start_date 为空字符串）
frequency*string
time*string到点的时刻，24 小时制 HH:MM
weekdays*array<integer>ISO 星期，去重升序
month_day*integer
interval_days*integer
start_date*stringYYYY-MM-DD，或空字符串
action*string
next_at*integer下一次到点的 Unix 秒，总是晚于设置或上一次到点的时刻

AlbumImage

object
id*string (uuid)
url*string (uri-reference)同源本站图片路径；私密图片仅所有者登录后可读取
thumbnail_url*string (uri-reference)最长边 256 px 的同源缩略图路径
medium_url*string (uri-reference)最长边 1024 px 的同源中等图路径
original_file_name*string
content_type*string
byte_size*integer (int64)
width*integer
height*integer
created_at*integer (int64)Unix 秒
is_public*booleantrue 表示允许匿名浏览与读取
collection_id*integer (int64)所在的合集，0 表示未归入合集

AlbumImagePage

object
items*array<AlbumImage>
page*integer
page_size*integer
total*integer (int64)

AlbumCollection

图床的合集，归一位用户所有；一张图片至多属于一个合集。不给出所有者与存储目录。

object图床的合集，归一位用户所有；一张图片至多属于一个合集。不给出所有者与存储目录。
id*integer (int64)
name*string
listed*boolean其中的公开图片是否出现在公开图库的总列表里
is_comment_collection*boolean是否为所有者的评论图片合集，每位用户至多一个
image_count*integer (int64)其中的图片数；scope=public 时只计公开图片
created_at*integer (int64)Unix 秒

AlbumCollectionInput

新建合集时 name 必填；改写时至少给出一项。

object新建合集时 name 必填；改写时至少给出一项。
namestring按字符计数，首尾空白会被去掉，不能含控制字符与 / \ < > 冒号 " | ? *，同时用作 Nextcloud 上的目录名
listedboolean其中的公开图片是否出现在公开图库的总列表里

LedgerEntryInput

新增或修改账目时由客户端提交的字段；修改是整体替换，其余字段一律忽略。转账是账本两个成员之间的资金往来，不计入收入与支出。收支与转账归入一个或多个分类，各带这笔账里属于它的金额，合计必须恰好等于 amount。余额调整把记录人自己的资金余额（全部账本、自开始记账至今）校准到 balance，差额记进这个账本、算在记录人名下，没有分类、账户、交易对象与扣减，不计入收入与支出。借贷往来是一笔借贷里经过资金的一次进出（借出、收款、借入、还款），以 debt_id 与 flow 给出，双方由借贷决定，没有分类、账户、交易对象与扣减，不计入收入与支出，只有借贷的当事人能新增、修改与删除。

object新增或修改账目时由客户端提交的字段；修改是整体替换，其余字段一律忽略。转账是账本两个成员之间的资金往来，不计入收入与支出。收支与转账归入一个或多个分类，各带这笔账里属于它的金额，合计必须恰好等于 amount。余额调整把记录人自己的资金余额（全部账本、自开始记账至今）校准到 balance，差额记进这个账本、算在记录人名下，没有分类、账户、交易对象与扣减，不计入收入与支出。借贷往来是一笔借贷里经过资金的一次进出（借出、收款、借入、还款），以 debt_id 与 flow 给出，双方由借贷决定，没有分类、账户、交易对象与扣减，不计入收入与支出，只有借贷的当事人能新增、修改与删除。
type*string账目类型，transfer 为成员之间的转账，adjustment 为余额调整，loan 为借贷往来
account_user_idinteger (int64)收支记在哪个成员名下，必须是账本当前的成员，修改时也可以是原来的账户；省略或为 null 时新增记在记录人名下、修改保持原来的账户；转账与余额调整须省略或为 null
amountinteger (int64)金额，单位为分，收支与转账必填，带扣减的支出填实付；余额调整须省略或为 null
balanceinteger (int64)余额调整必填，调整之后记录人的资金余额，单位为分，可以为零或负数；其余类型忽略
deductioninteger (int64)支出上的一笔优惠或退款，单位为分，原价等于 amount 加上它且不能超过金额上限；其余类型须省略、为 null 或为 0
deduction_typestring扣减的来源，discount 为优惠、refund 为退款；deduction 为正时必填，否则须省略或为 null
categoriesarray<LedgerEntryCategoryInput>归入的分类及各自的金额。收支与转账必填，至少一项，同一分类不重复，各项金额为正且合计恰好等于 amount（带扣减的支出对着实付）；每个分类都必须是该账本里类型与账目一致的一级或二级分类，且不能同时含一个一级分类与其下的二级分类。余额调整须省略、为 null 或为空数组。
counterparty_idinteger (int64)交易对象，收支可选，给出时必须是该账本里类型与账目一致的交易对象；省略或为 null 即没有交易对象，修改时同样替换掉原来的；转账与余额调整须省略或为 null
titlestring标题，按字符计数，首尾空白会被去掉，不能含控制字符；为空时客户端以分类名代替
notestring备注，按字符计数，首尾空白会被去掉
occurred_at*integer (int64)这笔收支实际发生的时间，Unix 秒；余额调整是校准的时刻，一个人在全部账本里的账目按它与 ID 排出先后
from_user_idinteger (int64)转出的成员，转账必填且须与转入方不同；其余类型须省略或为 null
to_user_idinteger (int64)转入的成员，转账必填；其余类型须省略或为 null
debt_idinteger (int64)借贷往来必填，是钱经过借入方的借贷，修改时不能换成别的借贷；账本外的借贷可以在别的账本里，往来记在请求路径的这个账本，新记时当事人须是这个账本的成员；成员之间的借贷的往来只能记在它所在的账本。支出可选，关联一笔向账本外借入的借贷，必须是支出账户名下的、所在账本里账户仍是成员（与原来相同的关联不再核对成员）；钱经过借入方的借贷（如花呗）表示这笔支出由它代付，计入支出、增加待还、不动账户的资金余额；钱没经过借入方的借贷（如房贷）表示这笔支出是还款，分到还款分类及其二级分类上的金额冲抵待还，至少要有一笔这样的分账。省略或为 null 即不关联；收入、转账与余额调整须省略或为 null。
flowstring借贷往来必填。principal 是钱从出借方到借入方（借出、借入与追加），repayment 是钱从借入方回到出借方（收款、还款）；其余类型须省略或为 null

LedgerEntryCategoryInput

账目在一个分类上的分账，由客户端提交。

object账目在一个分类上的分账，由客户端提交。
category_id*integer (int64)一级分类或二级分类
amount*integer (int64)这笔账里属于该分类的金额，单位为分

LedgerEntryCategory

账目在一个分类上的分账，连同分类的名称；二级分类另带其一级分类。

object账目在一个分类上的分账，连同分类的名称；二级分类另带其一级分类。
category_id*integer (int64)一级分类或二级分类
category_name*string分类的名称，随分类改名而变
parent_category_id*integer (int64)二级分类所属的一级分类；归入的是一级分类时为 null
parent_category_name*string一级分类的名称，随分类改名而变；parent_category_id 为 null 时同为 null
amount*integer (int64)这笔账里属于该分类的金额，单位为分

LedgerCategory

账本里的分类。一级分类限定它能用于哪种账目，二级分类挂在一级分类之下并沿用其类型；账目可以归入一级分类，也可以归入其下的二级分类。类型与上级在建立后不可改变。

object账本里的分类。一级分类限定它能用于哪种账目，二级分类挂在一级分类之下并沿用其类型；账目可以归入一级分类，也可以归入其下的二级分类。类型与上级在建立后不可改变。
id*integer (int64)
parent_id*integer (int64)所属的一级分类，一级分类为 null
type*string能归入它的账目类型
name*string
role*string系统分类的用途。repayment 是每个账本都有的一级支出分类「还款」，关联钱没经过借入方的借贷的支出靠它冲抵待还，不能改名与删除，其下的二级分类照常增删改；其余分类为 null

LedgerCategoryGroup

any

LedgerCategoryInput

新建分类时由客户端提交的字段。给出 parent_id 时是挂在它之下的二级分类，此时不能再给 type；否则必须给出 type，是该类型的一级分类。

object新建分类时由客户端提交的字段。给出 parent_id 时是挂在它之下的二级分类，此时不能再给 type；否则必须给出 type，是该类型的一级分类。
name*string分类名称，按字符计数，首尾空白会被去掉，不能含控制字符；同一账本里同类型的一级分类不能重名，同一一级分类下的二级分类不能重名
typestring一级分类的类型
parent_idinteger (int64)二级分类所属的一级分类

LedgerCounterparty

账本里的交易对象，即收支账目的另一方，例如商户或雇主。类型限定它能用于哪种账目，在建立后不可改变；转账的另一方是账本成员，没有交易对象。

object账本里的交易对象，即收支账目的另一方，例如商户或雇主。类型限定它能用于哪种账目，在建立后不可改变；转账的另一方是账本成员，没有交易对象。
id*integer (int64)
type*string能以它为交易对象的账目类型
name*string

LedgerCounterpartyInput

新建交易对象时由客户端提交的字段。

object新建交易对象时由客户端提交的字段。
name*string交易对象名称，按字符计数，首尾空白会被去掉，不能含控制字符；同一账本里同类型的交易对象不能重名
type*string能以它为交易对象的账目类型

LedgerBook

账本，按查看它的成员给出其身份。

object账本，按查看它的成员给出其身份。
id*integer (int64)
name*string
owner_id*integer (int64)所有者的用户 ID
role*string当前用户在该账本里的身份
member_count*integer (int64)成员数，含所有者
created_at*integer (int64)Unix 秒

LedgerBookInput

object
name*string账本名称，按字符计数，首尾空白会被去掉，不能含控制字符

LedgerBookMember

object
user_id*integer (int64)
username*string账号已被删除时为空串
nickname*string在这个账本里示人的昵称。本人在这个账本里设置过昵称时就是它，否则是账号的昵称；都没有时为空串，客户端此时以用户名示人。记账接口里人的昵称都按这一条给出
book_nickname*string本人在这个账本里设置的昵称，没有设置时为空串
role*string
joined_at*integer (int64)Unix 秒

LedgerMemberNicknameInput

object
nickname*string在这个账本里的昵称，规则与账号的昵称相同，按字符计数，首尾空白会被去掉，不能含控制字符；空串表示清除，此后以账号的昵称示人

LedgerInvitation

object
code*string邀请码，凭它加入账本
expires_at*integer (int64)过期时刻，Unix 秒

LedgerEntry

object
id*integer (int64)
book_id*integer (int64)所属账本
user_id*integer (int64)记录人的用户 ID
username*string记录人的用户名，账号已被删除时为空串
nickname*string记录人在这个账本里示人的昵称，规则见 LedgerBookMember；都没有时为空串
account_user_id*integer (int64)收支记在哪个成员名下，可以不是记录人；余额调整恒为记录人；转账为 null
account_username*string账户成员的用户名，账号已被删除时为空串，转账为 null
account_nickname*string账户成员在这个账本里示人的昵称；都没有时为空串，转账为 null
type*stringadjustment 为余额调整，loan 为借贷往来，都不计入收入、支出、汇总与收支趋势
amount*integer (int64)金额，单位为分；收支与转账为正，带扣减的支出是实付，汇总按它合计；余额调整是差额，即 balance 减去调整之前记录人的资金余额，可以为负，随这笔调整之前他在全部账本里的账目增删改而变
balanceinteger (int64)余额调整校准到的资金余额，单位为分，只给记录人本人，别人与其余类型为 null
deduction*integer (int64)支出上的优惠或退款，单位为分，原价等于 amount 加上它；没有扣减与其余类型为 0
deduction_type*string扣减的来源；deduction 为 0 时为 null
categories*array<LedgerEntryCategory>归入的分类及各自的金额，按分类的 ID 排列，合计等于 amount；收支与转账至少一项，余额调整为空数组。
counterparty_id*integer (int64)交易对象；没有交易对象的收支、转账与余额调整为 null
counterparty_name*string交易对象的名称，随交易对象改名而变；counterparty_id 为 null 时同为 null
title*string标题，没有设置时为空串
note*string
occurred_at*integer (int64)这笔收支实际发生的时间，Unix 秒
created_at*integer (int64)Unix 秒
updated_at*integer (int64)Unix 秒
from_user_id*integer (int64)转账的转出成员，借贷往来里付出钱的成员（账本外的对方为 null），其余类型为 null；记录人不必是转出方
from_username*string转出成员的用户名，账号已被删除时为空串，from_user_id 为 null 时同为 null
from_nickname*string转出成员在这个账本里示人的昵称；都没有时为空串，from_user_id 为 null 时同为 null
to_user_id*integer (int64)转账的转入成员，借贷往来里收到钱的成员（账本外的对方为 null），其余类型为 null
to_username*string转入成员的用户名，账号已被删除时为空串，to_user_id 为 null 时同为 null
to_nickname*string转入成员在这个账本里示人的昵称；都没有时为空串，to_user_id 为 null 时同为 null
debt_id*integer (int64)借贷往来所属的借贷，或支出关联的借贷；其余为 null
debt_name*string借贷的名称，随借贷改名而变；成员之间的借贷可以为空串；debt_id 为 null 时同为 null
debt_book_id*integer (int64)借贷所在的账本，可以不是这条账目所在的账本：代付与还款的支出、账本外借贷的往来都可以记在别的账本；debt_id 为 null 时同为 null
debt_role*string这笔账对借贷的作用。principal 为借出、借入与追加，repayment 为收款、还款与冲抵待还的支出，credit 为借贷代付的支出；debt_id 为 null 时同为 null
debt_amount*integer (int64)这笔账使待还增减的金额，单位为分，恒为正；借贷往来与代付是 amount，还款的支出是分到还款分类及其二级分类上的金额；debt_id 为 null 时同为 null

LedgerEntryPage

object
items*array<LedgerEntry>
page*integer
page_size*integer
total*integer (int64)符合条件的账目总数，含余额调整与借贷往来，与分页无关
income*integer (int64)符合条件的收入合计，单位为分，与分页无关；给出 category_ids 时只计分到所选分类及其二级分类上的金额；余额调整与借贷往来不计入任何一项合计
expense*integer (int64)符合条件的支出合计，口径同 income
transfer*integer (int64)符合条件的转账合计，口径同 income

LedgerSummary

object
income*integer (int64)时间区间内的收入合计，单位为分
expense*integer (int64)时间区间内的支出合计，单位为分
transfer*integer (int64)时间区间内成员之间的转账合计，单位为分，不计入收入与支出
categories*array<object>按分类分组的合计，按分账累计，金额从大到小排列；二级分类带着其一级分类，直接归入一级分类的合计单独成一项、没有上级。

LedgerPeriodTotal

收支趋势里的一段，转账不计入。

object收支趋势里的一段，转账不计入。
from*integer (int64)这一段的起点（含），Unix 秒
to*integer (int64)这一段的终点（不含），Unix 秒
income*integer (int64)这一段的收入合计，单位为分
expense*integer (int64)这一段的支出合计，按实付，单位为分

LedgerMemberNet

object
user_id*integer (int64)
username*string账号已被删除时为空串
nickname*string在这个账本里示人的昵称，规则见 LedgerBookMember；离开或账号删除之后，在这个账本里设置过的昵称照样给出
is_member*boolean是否仍是账本的成员；为 false 的是已离开、名下还有账目的人
income*integer (int64)本账本里记在名下的收入合计，单位为分
expense*integer (int64)本账本里记在名下的支出合计，按实付，单位为分
transfer_in*integer (int64)本账本里转入的合计，单位为分
transfer_out*integer (int64)本账本里转出的合计，单位为分
adjustment*integer (int64)他记在本账本里的余额调整的差额之和，单位为分，可以为负
loan_in*integer (int64)本账本里借贷流入的合计，单位为分，即他收到的借入与收款，加上本账本里他名下的借贷代付的支出（支出可以记在别的账本）
loan_out*integer (int64)本账本里借贷流出的合计，单位为分，即他付出的借出与还款
net*integer (int64)本账本里的净额，单位为分，等于 income 减 expense 加 transfer_in 减 transfer_out 加 adjustment 加 loan_in 减 loan_out，可以为负

LedgerFundBookNet

资金余额里一个仍在的账本，给出当前用户在其中的合计与净额，口径同 LedgerMemberNet。

object资金余额里一个仍在的账本，给出当前用户在其中的合计与净额，口径同 LedgerMemberNet。
book_id*integer (int64)
name*string账本名称
income*integer (int64)单位为分
expense*integer (int64)按实付，单位为分
transfer_in*integer (int64)单位为分
transfer_out*integer (int64)单位为分
adjustment*integer (int64)记在这个账本里的余额调整的差额之和，单位为分，可以为负
loan_in*integer (int64)借贷流入，单位为分，口径同 LedgerMemberNet
loan_out*integer (int64)借贷流出，单位为分
net*integer (int64)当前用户在这个账本里的净额，单位为分，可以为负

LedgerFundBalance

当前用户的资金余额，跨他的全部账本、从开始记账至今：收支计在账户名下，转账从转出方计到转入方，余额调整计入差额，借贷往来计给收到与付出钱的一方，借贷代付的支出在支出所在的账本计入支出、在借贷所在的账本计入借贷流入，合起来不动余额。余额等于全部账本里他的净额之和，也就是最后一笔余额调整校准到的余额加上其后他名下的收支、转账与借贷往来；已删除的账本连同其中的账目不再计入。

object当前用户的资金余额，跨他的全部账本、从开始记账至今：收支计在账户名下，转账从转出方计到转入方，余额调整计入差额，借贷往来计给收到与付出钱的一方，借贷代付的支出在支出所在的账本计入支出、在借贷所在的账本计入借贷流入，合起来不动余额。余额等于全部账本里他的净额之和，也就是最后一笔余额调整校准到的余额加上其后他名下的收支、转账与借贷往来；已删除的账本连同其中的账目不再计入。
income*integer (int64)全部账本里记在名下的收入合计，单位为分
expense*integer (int64)全部账本里记在名下的支出合计，按实付，单位为分
transfer_in*integer (int64)全部账本里转入的合计，单位为分
transfer_out*integer (int64)全部账本里转出的合计，单位为分
adjustment*integer (int64)全部余额调整的差额之和，单位为分，可以为负
loan_in*integer (int64)全部账本里借贷流入的合计，单位为分
loan_out*integer (int64)全部账本里借贷流出的合计，单位为分
balance*integer (int64)资金余额，单位为分，等于 income 减 expense 加 transfer_in 减 transfer_out 加 adjustment 加 loan_in 减 loan_out，也等于 books 与 departed_books 的 net 之和，可以为负
books*array<LedgerFundBookNet>当前用户所在的每个账本各一项，没有账目的各项为 0，排列同账本列表。
departed_books*object当前用户已退出、名下还有账目的账本，只给出个数与合计，不给出名称；没有时 count 与各项都为 0。

LedgerDebt

一笔借贷，属于一个账本，账本的成员都能查看，只有当事人（出借方与借入方里的成员）能修改。一方是账本外的人或机构时那一方为 null；两方都是成员的借贷由其中一方建立，双方都能操作。待还（出借方看来是待收）等于 principal 减 repaid 加 interest 减 written_off，各项都由服务端按借贷的全部记录算出。

object一笔借贷，属于一个账本，账本的成员都能查看，只有当事人（出借方与借入方里的成员）能修改。一方是账本外的人或机构时那一方为 null；两方都是成员的借贷由其中一方建立，双方都能操作。待还（出借方看来是待收）等于 principal 减 repaid 加 interest 减 written_off，各项都由服务端按借贷的全部记录算出。
id*integer (int64)
book_id*integer (int64)所在账本
book_name*string所在账本的名称
user_id*integer (int64)建立它的成员
username*string账号已被删除时为空串
nickname*string在借贷所在账本里示人的昵称，规则见 LedgerBookMember；借贷的事件与记录里的人同样如此
lender_user_id*integer (int64)出借方成员；出借方在账本外时为 null
lender_username*stringlender_user_id 为 null 时同为 null，账号已被删除时为空串
lender_nickname*stringlender_user_id 为 null 时同为 null
borrower_user_id*integer (int64)借入方成员；借入方在账本外时为 null
borrower_username*stringborrower_user_id 为 null 时同为 null，账号已被删除时为空串
borrower_nickname*stringborrower_user_id 为 null 时同为 null
direct*boolean钱没经过借入方，例如房贷、车贷；只有向账本外借入的借贷可以为 true，它的还款是关联它的支出，没有借贷往来
name*string名称，例如对方的称呼或贷款的名字；一方在账本外时不为空，成员之间的借贷可以为空串
note*string
opening*integer (int64)不经过资金登记的起始待还，单位为分，即钱没经过借入方的本金，或开始记账之前就有的借贷
opened_at*integer (int64)借贷开始的时刻，Unix 秒；起始待还记在这一刻
created_at*integer (int64)
updated_at*integer (int64)
principal*integer (int64)本金，单位为分，等于 opening 加上借出或借入的借贷往来，再加上它代付的支出
repaid*integer (int64)已还（已收），单位为分，即收款或还款的借贷往来，加上冲抵它的支出分到还款分类上的金额
interest*integer (int64)利息，单位为分，等于逐笔记下的利息加上各次校准的差额，可以为负
written_off*integer (int64)核销（减免）的合计，单位为分
outstanding*integer (int64)待还（待收），单位为分，可以为负，即多还了
last_occurred_at*integer (int64)最近一笔记录的发生时刻，没有记录时为 opened_at

LedgerDebtInput

新建借贷时由客户端提交的字段。建立的人一定是当事人之一，direction 从他的角度说。

object新建借贷时由客户端提交的字段。建立的人一定是当事人之一，direction 从他的角度说。
direction*stringlend 为借出，borrow 为借入
member_idinteger (int64)对方是本账本的成员时给出，须是当前成员且不是自己；省略或为 null 即对方在账本外
directboolean钱没经过借入方，例如房贷、车贷；只有向账本外借入时可以为 true
namestring名称，按字符计数，首尾空白会被去掉，不能含控制字符；对方在账本外时必填
amount*integer (int64)起始金额，单位为分，可以为 0（例如额度从零用起的花呗）。钱经过借入方、又不是开始记账前就有的，记成一笔发生在 opened_at 的借贷往来；否则记成起始待还
existingboolean开始记账之前就有的借贷，只登记起始待还，不记那笔钱的进出
notestring按字符计数，首尾空白会被去掉
opened_at*integer (int64)借贷开始的时刻，Unix 秒

LedgerDebtUpdate

修改借贷时由客户端提交的字段，整体替换；双方、方向与钱是否经过借入方在建立后不能改变。

object修改借贷时由客户端提交的字段，整体替换；双方、方向与钱是否经过借入方在建立后不能改变。
name*string规则同新建
notestring
opening*integer (int64)起始待还，单位为分
opened_at*integer (int64)

LedgerDebtRecord

借贷的一笔记录。先后按发生时间，同一时刻起始待还在前、账目居中、事件在后，同类按 ID。

object借贷的一笔记录。先后按发生时间，同一时刻起始待还在前、账目居中、事件在后，同类按 ID。
kind*stringopening 为起始待还；principal 与 repayment 来自借贷往来或冲抵待还的支出；credit 为代付的支出；interest、writeoff 与 calibration 是事件
entry_id*integer (int64)来自账目时为账目 ID，否则为 null
entry_type*string来自账目时为账目的类型，否则为 null
event_id*integer (int64)来自事件时为事件 ID，否则为 null
book_id*integer (int64)账目所在的账本；查看者不是那个账本的成员，或不是来自账目时为 null
book_name*string账目所在账本的名称；book_id 为 null 时同为 null
change*integer (int64)对待还的作用，单位为分，增加为正、减少为负；校准为差额
calibrated_to*integer (int64)校准到的待还，单位为分；其余为 null
title*string账目的标题；查看者不是账目所在账本的成员、或不是来自账目时为 null
category_names*array<string>支出的各分类名称，按分类 ID 排列；看不到账目内容或不是支出时为空数组。
note*string账目或事件的备注；看不到账目内容时为 null，起始待还为借贷的备注
occurred_at*integer (int64)
user_id*integer (int64)记录人；起始待还为建立借贷的人
username*string
nickname*string在借贷所在账本里示人的昵称，记录来自别的账本时也是如此
outstanding*integer (int64)这笔之后的待还，单位为分

LedgerDebtDetail

object
debt*LedgerDebt一笔借贷，属于一个账本，账本的成员都能查看，只有当事人（出借方与借入方里的成员）能修改。一方是账本外的人或机构时那一方为 null；两方都是成员的借贷由其中一方建立，双方都能操作。待还（出借方看来是待收）等于 principal 减 repaid 加 interest 减 written_off，各项都由服务端按借贷的全部记录算出。
records*array<LedgerDebtRecord>全部记录，按先后排列。

LedgerDebtEventInput

新增或修改借贷事件时由客户端提交的字段，修改是整体替换且不能换类型。事件不动任何人的资金余额，只改变待还。

object新增或修改借贷事件时由客户端提交的字段，修改是整体替换且不能换类型。事件不动任何人的资金余额，只改变待还。
kind*stringinterest 为利息（含手续费、罚息），增加待还；writeoff 为核销或减免，减少待还；calibration 为待还校准，把待还校准到 outstanding
amountinteger (int64)利息与核销必填，单位为分；校准须省略或为 null
outstandinginteger (int64)校准必填，校准之后的待还，单位为分；其余须省略或为 null
notestring
occurred_at*integer (int64)

LedgerDebtEvent

object
id*integer (int64)
debt_id*integer (int64)
user_id*integer (int64)记录人
username*string
nickname*string
kind*string
amount*integer (int64)利息与核销的金额；校准为差额，即校准到的待还减去校准之前的待还，可以为负，随它之前的记录增删改而变
outstanding*integer (int64)校准到的待还；其余为 null
note*string
occurred_at*integer (int64)
created_at*integer (int64)
updated_at*integer (int64)

LedgerBlockingEntry

挡住一次删除的一条账目，供客户端写明是哪一条。

object挡住一次删除的一条账目，供客户端写明是哪一条。
entry_id*integer (int64)
book_id*integer (int64)账目所在的账本；当前用户已不是那个账本的成员时为 null
book_name*stringbook_id 为 null 时同为 null
type*string
amount*integer (int64)账目的金额，单位为分
title*string标题；book_id 为 null 时为 null
category_names*array<string>各分类名称，按分类 ID 排列；book_id 为 null 时为空数组。
occurred_at*integer (int64)

LedgerDuplicateDebtError

新建或改名的借贷与当事人已有的借贷重名时的回复：同一个当事人、同一个方向，在他仍在其中的账本里。

object新建或改名的借贷与当事人已有的借贷重名时的回复：同一个当事人、同一个方向，在他仍在其中的账本里。
codeinteger
message*string
data*object

LedgerBlockedError

删除被关联的账目挡住时的回复，data.blockers 列出挡住它的账目，按发生时间倒序至多 50 条，total 为全部条数。

object删除被关联的账目挡住时的回复，data.blockers 列出挡住它的账目，按发生时间倒序至多 50 条，total 为全部条数。
codeinteger
message*string
data*object

Comment

object
id*integer (int64)
parent_id*integer (int64)直接回复的评论；顶层评论为 0
root_id*integer (int64)所在楼的顶层评论；顶层评论为 0
author*string作者身份，按作者账号当前的角色判定。guest 是自报昵称的访客或账号已被删除的作者；admin 即站长
nickname*string署名。账号作者的为账号当前的昵称，没有昵称时为用户名；访客与账号已被删除的作者为发表时记下的昵称
avatar_hash*string头像标识。作者邮箱去掉首尾空白并转成小写后的 SHA-256（十六进制小写），供客户端向与 Gravatar 接口兼容的头像服务查找头像；作者没有邮箱时为空串。邮箱本身不对外给出
website*string作者留下的网址；没有时为空串
content*stringMarkdown 源文，服务端原样保存，由客户端渲染并净化
region*string发表者地址的归属地，由服务端的离线归属地库查出：国内给到省，国外给到国家；内网地址、查不到或没有部署归属地库时为空串
os*string从发表者的浏览器标识认出的操作系统，如 Windows 10/11、Android 14；认不出时为空串
browser*string从发表者的浏览器标识认出的浏览器及其主版本，如 Chrome 126；认不出时为空串
created_at*integer (int64)Unix 秒
likes*integer (int64)赞数
dislikes*integer (int64)踩数
viewer_vote*string查看者自己对这条评论投的票。登录用户按账号认，其余按来源地址认；没有投票时为 none
ipstring发表者的地址。仅当查看者是管理员时出现

CommentThread

一楼，即一条顶层评论及其全部回复。

any一楼，即一条顶层评论及其全部回复。

CommentThreadPage

object
items*array<CommentThread>各楼按发表时间倒序。
page*integer
page_size*integer
total*integer (int64)评论流里的楼数，与分页无关
comment_count*integer (int64)评论流里的评论数，含回复，与分页无关

CommentInput

发表评论时由客户端提交的字段，其余字段一律忽略。文本字段的首尾空白会被去掉。

object发表评论时由客户端提交的字段，其余字段一律忽略。文本字段的首尾空白会被去掉。
path*string评论所在页面的路径。已解码，以斜杠开头，不带查询串与片段；末尾的斜杠会被去掉
members_onlyboolean是否发表在仅登录可见的评论流里
parent_idinteger (int64)被回复的评论；发表顶层评论时不传或传 null
nicknamestring访客自报的昵称，按字符计数，不能含控制字符，也不能与已注册账号的用户名、邮箱或昵称相同。登录用户不必传，传了也不作数
emailstring访客的邮箱，可不填；用于回复通知与头像，地址本身不对外公开
websitestring网址，可不填；只接受 http 与 https 地址
content*stringMarkdown 源文，按字符计数

CommentVoteInput

对一条评论投票时由客户端提交的字段。

object对一条评论投票时由客户端提交的字段。
members_onlyboolean评论所在的评论流是否仅登录可见；与评论实际所在的不符时按评论不存在答复
vote*stringup 为赞，down 为踩，none 撤回已投的票。每位投票者对每条评论至多一票，改投即替换原来的那一票

CommentVotes

object
likes*integer (int64)投票之后的赞数
dislikes*integer (int64)投票之后的踩数
viewer_vote*string投票者现在的那一票

NotebookEntry

object
namestring
pathstring
is_directoryboolean
sizeinteger仅普通文件含此字段

GatewayAsset

发布附件，只含客户端读取的字段。

object发布附件，只含客户端读取的字段。
namestring
sizeinteger
browser_download_urlstring网关自己的下载入口 /api/v1/repos/{owner}/{repository}/releases/download/{tag}/{name}

GatewayRelease

按字段白名单重建的发布；作者、上传者、源码归档与上游地址一律不出现，草稿不出现在任何响应中。

object按字段白名单重建的发布；作者、上传者、源码归档与上游地址一律不出现，草稿不出现在任何响应中。
tag_namestring
namestring
bodystring
draftboolean
prereleaseboolean
published_atstring
assetsarray<GatewayAsset>

SearchSection

站内搜索的一条记录，即页面里的一节：一个标题连同它下面直到下一个标题之前的正文；页面开头第一个标题之前的部分也是一节。

object站内搜索的一条记录，即页面里的一节：一个标题连同它下面直到下一个标题之前的正文；页面开头第一个标题之前的部分也是一节。
url*string站内路径，以单个斜杠开头，节有锚点时带着它，如 /我的笔记/NAS实践#ip分配
category*string页面所属的栏目路径，第一级为 博客 或 笔记，笔记其后接各级分类，各级以 › 相隔（如 笔记 › GUI开发），按字节计
title*string页面标题，按字节计
headings*array<string>从最外层到这一节的各级标题，页面开头那一节为空数组；每项非空，至多 1024 字节
content*string这一节的纯文本正文，可以为空，按字节计；除换行与制表符外不得含控制字符

SearchHit

命中的一节。

object命中的一节。
urlstring
categorystring
titlestring
headingsarray<string>
snippetstring从正文里截取的一段，围绕第一处命中，被截断的一侧带省略号；正文为空时为空串
scoreinteger相关程度，只在 explain 时给出
explanationarray<SearchTermExplanation>各检索词对得分的贡献，只在 explain 时给出

SearchTermExplanation

object
termstring
scoreinteger
viastringexact 为原样命中，synonym 为原样找不到时同义词原样出现，bigrams 为原样找不到时按两字对命中
synonymstringvia 为 synonym 时是出现的那个同义词
placesarray<string>命中的位置

SearchSynonymGroup

一组同义词。组内的词互相通用；搜组内的任何一个词还会找到 includes 里的下位词，反过来不会。由多个检索词组成的写法（如 network attached storage）只作为被匹配的一方，不能从查询里触发。

object一组同义词。组内的词互相通用；搜组内的任何一个词还会找到 includes 里的下位词，反过来不会。由多个检索词组成的写法（如 network attached storage）只作为被匹配的一方，不能从查询里触发。
words*array<string>组内互相通用的写法；只有一个词时 includes 不能为空。每项至多 300 字节，须含至少一个检索词
includesarray<string>只被组内的词指向的下位词，可省略

SearchQueryStatistics

一个查询的使用统计，按检索词归并：大小写、多余的空白与标点、重复的词不影响归并。

object一个查询的使用统计，按检索词归并：大小写、多余的空白与标点、重复的词不影响归并。
querystring归并后的查询，检索词以空格连接
searchesinteger计入统计的次数
openedinteger其中点开了结果的次数
last_totalinteger最近一次计入时的命中节数
last_partialboolean最近一次计入时是否舍弃了检索词才有结果
last_searched_atinteger最近一次计入的时间，Unix 秒