#API 概览

Firmiana 实现了 Matrix Client-Server API 规范。

#基础 URL

http://localhost:8899/_matrix/client/v3

#认证

大多数端点需要在 Authorization 头中提供 Bearer Token：

Authorization: Bearer syt_xxxxxxxxxxxxxxxxxxxxx

标记为 @Secured(IS_ANONYMOUS) 的端点不需要认证（如登录、注册、版本查询）。

#请求格式

• Content-Type: application/json
• 请求体: JSON
• ID 是区分大小写的字符串（如 @alice:localhost、!room:localhost、$event:localhost）

#响应格式

成功响应返回 JSON，HTTP 200。

错误响应遵循 Matrix 错误格式：

{
  "errcode": "M_NOT_FOUND",
  "error": "房间未找到"
}

#常见错误码

#限流

请求按 IP 地址限流：

• 默认：每 60 秒窗口 100 个请求
• 超出：HTTP 429，包含 Retry-After 头

#版本

查询支持的版本：

GET /_matrix/client/versions

Firmiana 支持：v1.1、v1.2、v1.3、v1.4、v1.5、v1.6

#分页

许多列表端点支持通过 from 和 to 流令牌进行分页：

GET /messages?from=t123&to=t456&dir=b&limit=50

• dir=b — 向后（更新的事件在前）
• dir=f — 向前（更旧的事件在前）
• limit — 最大事件数（默认 50，最大 100）