论坛 API 文档现已开放，让我们一起把社区能力接出去！

xyc管理员

楼主发布于 2026年9月24日|2,567 浏览

以前论坛里的很多能力基本只服务于网页本身，例如资源、地图、蓝图、用户信息等。对于想做 Mindustry Mod、第三方启动器、资源管理器、机器人或者其他社区工具 的开发者来说，要么不知道接口在哪里，要么只能自己研究网页请求。

所以我们准备把这件事正式一点：

MDTBBS 将逐步开放公共 API，并提供面向第三方开发者的 API 文档。

API 文档入口：

https://mdtbbs.cn/api/v1

API 文档里有什么？

文档会直接基于 MDTBBS 当前实际提供的接口整理

目前文档中会展示：

接口地址与请求方式
请求参数说明
返回数据结构
错误码与异常响应
认证方式
分页、筛选等公共参数
JavaScript / TypeScript / Java / Kotlin / cURL 等调用示例

以后论坛 API 有调整时，也会尽量保证 /api/v1/* 的兼容性，避免第三方项目因为论坛内部的一次改动直接失效。

这些 API 能拿来做什么？

比如：

在 Mindustry Mod 里直接浏览社区资源
制作第三方 Mindustry 启动器
搜索、查看和下载地图、蓝图等资源
制作桌面端或移动端 MDTBBS 客户端
制作资源管理器、资源站聚合工具
做你想做的事情（

论坛不一定只能存在于浏览器里，而是可以存在于不同的应用中

如果有人愿意折腾，我们希望 MDTBBS 的资源和社区能力能够出现在更多地方

API 还在继续完善

目前这套 API 并不是“已经全部完成，以后不动了”的最终版本，它还会随着论坛继续开发，有些能力已经可以稳定使用，有些接口还在补充，还有一些需求可能只有真正开始开发第三方项目以后才能发现。

所以如果你在开发过程中发现：

缺少某个很有用的接口
返回的数据不够
字段设计不方便使用
文档写错了或者没有说明清楚
某个接口对于 Mod / 启动器来说调用起来很别扭
有更合理的 API 设计方案

欢迎提出指导

API 最终是给开发者用的，如果只有论坛自己觉得“这个接口设计得挺合理”，结果第三方真正接入的时候发现到处绕路，那这个 API 设计其实就没有达到目的。所以

欢迎一起共建

MDTBBS 本身也是一个长期折腾出来的社区项目，所以 API 这部分同样欢迎大家参与。

很多真正有用的接口，不一定是我们坐在这里提前设计出来的，而是在实际开发和接入过程中慢慢发现而创造出来的。

关于第三方项目

我们欢迎第三方客户端、启动器、Mod 和工具调用 MDTBBS 的公开 API。

第三方项目也不需要与我们绑定，你完全可以按照自己的想法开发自己的项目

如果你的项目已经接入 MDTBBS API，也欢迎在论坛发布，我们将为基于论坛而开发的应用提供高速下载地址

API 版本

目前公开 API 以：

/api/v1/*

作为主要版本路径。

以后如果出现较大的不兼容改动，会通过新的 API 版本处理，而不是直接把现有第三方程序全部干碎。

当然，在 API 还处于持续建设阶段的现在，一些接口和字段仍然可能进行调整。

资源、地图、蓝图、账号、搜索，以及以后更多能力，都可以逐渐变成开放的社区基础设施。

网页只是其中一个入口。

所以开放了互联api

如果你正在开发 Mindustry 相关项目，或者单纯想拿 API 做点有意思的东西，欢迎来试。

API 文档

👉 https://mdtbbs.cn/api/v1

如果遇到什么问题请在此帖或运营反馈板块留言

#1DeterMination-Wind用户用户编号 111|2026年9月25日Ningbo

# 给 MDTBBS 接口维护者：启动器还需要的 API

本文给 MDTBBS / 像素工厂文件站的接口维护者。Xenon 启动器要在程序内做原生社区（版块、帖子、正文、回复），并优先从像素工厂文件站下载游戏。

依据是 2026-09-26 对公开文档和线上接口的实测：

- <https://mdtbbs.cn/api/v1>
- <https://mdtbbs.cn/api/v1/capabilities>
- <https://mdtbbs.cn/api/v1/client/config>
- <https://file.mdtbbs.cn/api/v1/mindustry/manifest.json>

## 已经够用、不必重做

这些请保持稳定，启动器已经按它们接入：

- `GET /api/v1/categories`
- `GET /api/v1/threads?page=&limit=&category_id=`
- `GET /api/v1/threads/{id}`（含 `content`、`replies`、`reply_pagination`）
- `GET /api/v1/capabilities`
- `GET /api/v1/client/config`
- `GET /api/v1/discover`、`GET /api/v1/home`
- 文件站 `GET /api/v1/mindustry/manifest.json`（相对 `download_url`、`sha256`、`tag`、`source_repository`）

响应继续用 `{ data, meta }` / `{ error, meta }`。`error.code` 保持稳定，不要只返回中文句子。

## 请新增或对桌面客户端开放

### 1. 桌面登录（最高优先级）

现在只有「原生第一方客户端」一条路：MindAuth authorization code + PKCE，再 `POST /api/v1/auth/mobile/exchange` 换成论坛 access / refresh token。`GET /api/v1/capabilities` 里 `device_auth` 为 `false`。文档同时写明 External API Key 不能放进桌面客户端。

请增加一套给第三方桌面启动器的公开客户端登录，建议：

- 注册一个公开的 `client_id`（无 client secret，使用 PKCE）
- `GET /api/v1/auth/desktop/authorize`：返回验证地址和 `user_code` / `device_code`，或标准授权码地址
- `POST /api/v1/auth/desktop/token`：用 code + `code_verifier` 换 `access_token`、`refresh_token`、`expires_in`
- `POST /api/v1/auth/desktop/refresh`
- `POST /api/v1/auth/desktop/logout`

access token 仍可按现在的约 30 分钟，refresh token 轮换可以保留。登录完成后，现有的 `GET /api/v1/me` 就能用。

### 2. 注册与账号状态

公开文档里没有启动器可调用的注册接口。`/me` 未登录时返回 401，没有「为什么不能发帖」的字段。

请增加：

- `POST /api/v1/auth/register`：用户名、密码、验证码或邮箱。若注册必须跳到网页，请给出可在系统浏览器完成、再回到桌面 token 接口的地址，并写进文档。
- 扩展 `GET /api/v1/me`，至少包含：`id`、`username`、`avatar`、`role`、`banned`、`phone_verified`、`can_post`、`can_reply`、`can_message`。不能发帖时给稳定的 `post_block_reason`（如 `posting_disabled`、`phone_required`、`banned`），不要只靠中文 `message`。

### 3. 发帖、回复、编辑

`GET /api/v1/client/config` 当前是：

```json
{
  "features": {
    "posting": false,
    "image_upload": false,
    "notifications_sse": false
  }
}

文档写明写操作还要登录和手机验证。External API 的 POST /api/external/v1/posts 和 POST /api/external/v1/posts/{id}/replies 只能放在服务器上。

请对已登录的桌面 token 开放第一方写接口，并在 features.posting 为 true 时生效：

POST /api/v1/threads：category_id、title、content、可选 tags
POST /api/v1/threads/{id}/replies：content
PATCH /api/v1/threads/{id}、PATCH /api/v1/replies/{id}：仅作者
POST /api/v1/uploads/images：配 features.image_upload

正文请同时返回 Markdown 源文 content 和现成的 content_html。锁帖、禁言用 error.code，例如 THREAD_LOCKED、POSTING_DISABLED。

4. 列表字段和搜索

GET /api/v1/threads 现在每条只有 id、title、category_id、user_id、计数和时间。卡片要显示作者和版块名，只能再请求详情。?q= 实测返回 400。meta 里没有总数，客户端无法知道还有没有下一页。

请在列表每条中直接带上：

author_name、author_avatar_url
category_name、category_slug
excerpt（纯文本摘要，一两百字）
is_pinned、is_locked、reply_count、view_count、created_at

并增加：

GET /api/v1/threads?q=&category_id=&page=&limit=
meta.page、meta.limit、meta.total、meta.has_more

详情里的 reply_pagination 已经有 page / limit / total_pages，请补一个明确的翻页参数：GET /api/v1/threads/{id}?reply_page=&reply_limit=。

5. 私信和通知

网站有 /messages、/notifications，公开 V1 文档没有对应读写信接口。notifications_v1 和 notifications_sse 都是 false。

请增加：

GET /api/v1/messages、GET /api/v1/messages/{id}、POST /api/v1/messages
GET /api/v1/notifications、POST /api/v1/notifications/{id}/read
能力开关打开后再提供 SSE 或轮询间隔说明

未登录访问应返回 401，而不是 404。

6. 资源和文件站，供启动器安装

游戏包清单已经能用。论坛资源这边，resource_read 为 true，但 resource_files 和 download_grants 为 false。Resource V1 文档里的下载路径因此还不能当安装源。

请在开关打开后保证这些地址可用，并在清单里给出绝对地址或可解析的 download_url、sha256、文件大小：

GET /api/v1/resources
GET /api/v1/resources/{id}
GET /api/v1/resources/{id}/manifest
GET /api/v1/resources/{resourceId}/versions/{versionId}/files/{fileId}/download

游戏内容的 GET /api/v1/game-content/maps 和 GET /api/v1/game-content/maps/{id}/download/file 若要对启动器开放，请在 capabilities 里单独给出 map_download，避免和文件站游戏包混在一起。

文档和契约

/api/openapi/v1.json 的 paths 目前是空的，Reference 页也显示 0 个接口。请把上面已经存在的读接口和将要加的写接口写进 OpenAPI。Schema 里已有 CreatePostDto、CreateReplyDto、MobileExchangeDto，但没有路径，生成客户端时用不上。

另外请写明：

匿名读接口的频率上限。启动器会缓存清单和帖子列表，不会按秒轮询。
桌面客户端的 User-Agent 约定（Xenon 现在使用 Xenon-Launcher）。
features.* 与 capabilities.* 的关系。客户端会在开关为 false 时隐藏按钮，不再探测写接口。

建议的交付顺序

桌面 PKCE 登录、刷新、/me 状态字段。
打开 features.posting，提供发帖和回复。
帖子列表补上作者、版块、摘要、q 和分页 meta。
私信和通知。
打开 resource_files / download_grants，让 Mod 和地图能按 hash 安装。

#2IronRaw用户用户编号 92|2026年9月26日Linyi

太棒了，但我不会

#3GXFQE_GSC用户用户编号 123|2026年10月3日Changsha

好东西啊，正好在开发启动器直接拿走()