Older HTTP API

vv1OpenAPI 3.1.0

Older 服务端对外 HTTP 接口。除特别说明外，响应为 JSON。鉴权采用「短寿命访问令牌 `older_auth` + 长寿命刷新令牌 `older_refresh_token`」双 Cookie 模型；访问令牌过期后由 `POST /api/v1/user/refresh` 凭刷新令牌续期（设计见 `resources/50-http-api/spec.md`）。处理器未捕获的异常由会话层统一兜底：请求体 JSON 语法/类型错误与参数解析错误返回 400，其他内部错误返回 500，正文均为 Error 信封，连接保持可用。

59 个接口
13 个标签
13 个数据模型
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 续期。

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 比对 Meilisearch ApiKey，/api/v1/notebook/update 比对 Gitea AccessToken。

分析

5 个接口

访问统计与站点信息

用户

9 个接口

设备

6 个接口

设备列表、信息与控制

笔记本

3 个接口

笔记本文件读取与同步

设置

2 个接口

运行时设置

访问记录

2 个接口

VisitRecord 查询与删除

便签

4 个接口

TickNote 便签

图床

7 个接口

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

聊天室

3 个接口

聊天室消息与实时 WebSocket

信令

1 个接口

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

管理

7 个接口

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

系统

6 个接口

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

发布网关

4 个接口

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

数据模型

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

AccountSummary

object

idinteger

usernamestring

emailstring

statusstringunverified | pending | approved | rejected

rolestringuser | admin

created_atintegerUnix 秒

reviewed_atinteger

reviewed_byinteger

reject_reasonstring

VisitRecord

object

idinteger

urlstring

visitorUuidstring

lastUserAgentstring

lastViewTimeintegerUnix 秒

pageViewCountinteger

FilterRule

object

typestring

patternstring

ChatMessage

object

idinteger

nicknamestring

emailstring

websitestring

contentstring

created_atintegerUnix 秒

TickNote

object

idinteger

contentstring

created_atintegerUnix 秒

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 表示允许匿名浏览与读取

AlbumImagePage

object

items*array<AlbumImage>

page*integer

page_size*integer

total*integer (int64)

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>