# KukeMC-群组服 API 文档

## Docs
- [KukeMC 公共 API 接入指南](https://api-docx.0ctber.cn/9519008m0.md): 

## API Docs
- 公开接口文档 > 状态与监测 [获取 API 状态](https://api-docx.0ctber.cn/521402312e0.md): 匿名读取，无请求参数和请求体。成功状态为 HTTP 200，仅用于 API 可达性确认，不代表所有依赖或游戏服务器健康。只读。未声明固定响应模型，不将自由 schema 扩写为推测的成功结构。
- 公开接口文档 > 状态与监测 [获取全部服务器状态](https://api-docx.0ctber.cn/521402313e0.md): 匿名读取，无请求参数和请求体。HTTP 200 返回服务器状态数组，按 server_id 升序，项含 server_id、display_name、group_name、last_seen、ttl_seconds、online。last_seen 为 ISO 时间字符串加 Z 或 null；ttl_seconds 取状态记录值，缺省口径为 20 秒。online 根据当前 UTC 时间与 last_seen 的差值不超过 TTL 判断，缺少 last_seen 时为 false；这是心跳时间口径，不是主动连通性检测。过期记录仍可返回，并标记相应在线状态。只读；服务异常可能为 500，无统一错误正文承诺；未声明固定成功 schema。
- 公开接口文档 > 状态与监测 [获取单个服务器状态](https://api-docx.0ctber.cn/521402314e0.md): 匿名读取，无请求体。server_id 为必填字符串，精确匹配且不去除首尾空白，未声明长度限制。HTTP 200 返回单个服务器状态，字段与 /api/servers/status/all 的单项一致：server_id、display_name、group_name、last_seen、ttl_seconds、online；last_seen 为 ISO 时间字符串加 Z 或 null，TTL 缺省口径为 20 秒，缺少心跳时 online=false。在线值是心跳时间口径，不是主动连通性检测。未找到时为 404（error 文本为 Not Found），服务异常可能为 500。静态 /api/servers/status/all 优先匹配，不会作为 server_id 查询。只读；未声明固定成功 schema。
- 公开接口文档 > 内容与分类 [获取动态分类](https://api-docx.0ctber.cn/521402315e0.md): 匿名读取，无请求参数和请求体。HTTP 200 返回分类列表，按 id 升序；无发布状态过滤，无记录时为空列表。只读。未声明固定响应模型；服务异常可能返回 500，错误正文不保证统一。
- 公开接口文档 > 内容与分类 [获取公开新闻列表](https://api-docx.0ctber.cn/521402316e0.md): 匿名读取，无请求体。skip 默认为 0，limit 默认为 20，均为可选整数，未声明 HTTP 层上下界；负数或超大值的具体结果未验证。仅返回 is_published=true 的新闻，按 created_at 降序，HTTP 200 为 PublicNews 数组，不含分页总数。reactions 为各表情计数，comments_count 仅统计已审核评论；user_selected_reactions 默认空数组、reaction_users 默认空对象，不提供按身份个性化结果。只读；参数类型不合法通常为 422，服务或响应兼容性异常可能为 500。
- 公开接口文档 > 内容与分类 [获取公开更新日志](https://api-docx.0ctber.cn/521402317e0.md): 匿名读取，无请求体。skip 默认为 0，limit 默认为 20，均为可选整数，未声明 HTTP 层上下界；特殊边界值的具体结果未验证。仅返回 is_published=true 的更新日志，按 created_at 降序，HTTP 200 为 PublicChangelog 数组，不含分页总数。content 的元素未声明固定结构，不推测各元素的字段。只读；参数类型不合法通常为 422，服务或响应兼容性异常可能为 500。
- 公开接口文档 > 公开表单 [获取公开表单列表](https://api-docx.0ctber.cn/521402318e0.md): 匿名读取，无请求体。skip 默认为 0，limit 默认为 20，均为可选整数，未声明 HTTP 层上下界。先选 status=published 的表单，按创建时间降序并分页，再排除尚未开始或已经结束的项；因此一页可能少于 limit，甚至为空，并非先按时间过滤再分页。时间比较采用 UTC+8 的无时区时间口径，边界以服务端为准。HTTP 200 为 PublicForm 数组，每项计算 submission_count；require_login 不限制列表可见性。只读；类型错误通常为 422，服务、时间或响应兼容性异常可能为 500。
- 公开接口文档 > 公开表单 [获取公开表单详情](https://api-docx.0ctber.cn/521402319e0.md): 本公开文档仅描述匿名分支，不要求或发送身份凭据。id_or_slug 为必填字符串，未声明长度或 slug 格式限制；纯数字先按数字 ID 查找，未找到时再按原字符串 slug 查找。匿名仅可读取 status=published 的表单；不存在或不可公开时为 404，提示分别为 Form not found 或 Form not available。require_login、start_time、end_time 不限制详情可见性，不能据此推断是否可提交。HTTP 200 为 PublicForm；详情不重新计算 submission_count，该值通常为默认 0，不应当作实时提交数。静态 /api/forms/public 优先匹配，slug 为 public 的表单可用数字 ID 读取。只读；特殊数字字符转换或服务、响应兼容性问题可能为 500。私人扩展不在本公开范围。
- 公开接口文档 > 游戏排行榜 [获取 KitBattle 排行榜](https://api-docx.0ctber.cn/521402320e0.md): 匿名读取，无请求体。type 必填，仅接受 kills、deaths、exp、coins、kd；其他值为 400（Invalid leaderboard type）。period 默认 total，仅 weekly、monthly 使用周期统计，其他字符串按累计统计；page 默认 1，服务端将小于 1 的值调整为 1；limit 默认 10，服务端调整到 1～50。search 可省略或为 null，非空值按玩家名进行包含匹配，不去除首尾空白。HTTP 200 含 data 列表及 pagination，分页信息含 total、page、limit、total_pages；榜单项含 name、value、rank、exp、kills、deaths、coins、kd、position。value 为所选指标，kd 为小数，其他指标为整数；其余统计字段仍为累计值，kd 字段也为累计 KD。周期值为累计值减周期起点，仅纳入当前周期匹配者，负增量不截断；KD 分母为零时取击杀数或周期击杀增量。按 value 降序，并列无固定次级顺序；不搜索时 position 为当前分页位置，搜索时尝试全局名次并可能回退列表位置。周期依服务端本地日期，未承诺统一结果快照。只读；整数类型错误通常为 422，服务或数值处理异常可能为 500。未声明固定响应模型，不新增结构化成功 schema。
- 公开接口文档 > 游戏排行榜 [获取等级排行榜](https://api-docx.0ctber.cn/521402321e0.md): 匿名读取，无请求体。limit 为可选整数，默认为 50，未声明 HTTP 层上下界；负数或超大值的具体结果未验证。HTTP 200 返回榜单数组，项含 username、level、total_xp；按 total_xp 降序，level 根据当前经验值计算，无记录时为空数组，并列无固定次级顺序。只读，不创建或更新等级记录。参数类型错误通常为 422，服务异常可能为 500。未声明固定响应模型，不新增结构化成功 schema。
- 公开接口文档 > 在线玩家 [获取按服务器分组的玩家列表](https://api-docx.0ctber.cn/521402322e0.md): 匿名读取，无请求参数和请求体。HTTP 200 提供 servers、total、lastUpdate；每个服务器分组提供 server、count、players，玩家仅投影 name、uuid、ping，不透传其他字段。缺少服务器名称时归入“未知服务器”，分组按 count 降序、server 字典序排列。name、uuid、ping 未声明固定 JSON 类型，name/uuid 缺省为空字符串，ping 可为 null；延迟值按已提供的候选值回退，部分回退可能忽略 0。total 为合并名单的行数，可能包含重复或占位项，没有新鲜度过滤，不等于实时去重在线人数。lastUpdate 未声明固定类型，可能为时间字符串、null 或原更新时间值。名单不可用时可能为空；其他异常可能为 500，错误分支含空分组、total=0、lastUpdate=null 及 error 文本。只读；不新增固定成功 schema。
- 公开接口文档 > 在线玩家 [获取玩家名单文本](https://api-docx.0ctber.cn/521402323e0.md): 匿名读取，无请求参数和请求体。HTTP 200 的实际业务响应为 text/plain，展示主名单的行数及逐行玩家名称，不与其他名单合并；占位项也可能计入人数，因此不是实时去重在线人数。名单不可用时可返回 404 纯文本；名称信息缺失或其他异常可返回 500 纯文本。只读，未声明固定响应模型。本公开副本将 200 媒体类型按已冻结章节的明确契约纠正为 text/plain，保持原自由 schema；default 节点的媒体槽仅为原冻结占位，不代表错误一定为 JSON。
- 公开接口文档 > 玩家认证 [获取玩家公开认证状态](https://api-docx.0ctber.cn/521402324e0.md): 匿名读取，无查询参数和请求体。username 为必填字符串，未声明长度或账号格式约束。HTTP 200 提供 is_verified、verification_type、platform_label：玩家不存在或未认证时表示未认证，平台字段为 null；已认证时提供平台代码及显示标签，未知平台的标签使用原平台值。不存在玩家不返回 404。仅公开认证标记，不返回认证链接、申请状态或拒绝原因。只读；服务异常可能为 500，未声明固定响应模型，不新增结构化成功 schema。

## Schemas
- [PublicForm](https://api-docx.0ctber.cn/318208394d0.md): 
- [PublicNews](https://api-docx.0ctber.cn/318208395d0.md): 
- [PublicChangelog](https://api-docx.0ctber.cn/318208396d0.md):