Update Modrinth API documentation

2026-07-13 16:42:52 +08:00 · 2026-07-13 16:42:52 +08:00 · 691ae86e00
commit 691ae86e00
parent b778ebc1d8
1 changed files with 264 additions and 0 deletions
--- a/docs/modrinth/get-project.md
+++ b/docs/modrinth/get-project.md
@ -0,0 +1,264 @@
+# Get Project
+
+获取 Modrinth 上的单个或多个 project 的基本数据。
+
+---
+
+## GET `/project/{id|slug}`
+
+获取单个 project 的完整信息。
+
+### 路径参数
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| `id\|slug` | path | `string` | ✅ | Project 的 ID（base62 编码）或 slug（用于自定义 URL）。 |
+
+### 响应 `200 OK`
+
+返回 [`Project`](#project-模型) 对象。
+
+### 响应 `404 Not Found`
+
+指定的 project 不存在或无权限访问。
+
+---
+
+## GET `/projects`
+
+批量获取多个 project 的完整信息。
+
+### 查询参数
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| `ids` | query | `string` | ✅ | 以 JSON 数组格式指定要获取的 project ID 或 slug。例如 `["AABBCCDD", "my_project"]`。 |
+
+### 响应 `200 OK`
+
+返回 [`Project`](#project-模型) 对象数组。
+
+---
+
+## Project 模型
+
+`Project` 继承自多个层级 schema，完整字段如下。
+
+> **🔗 Schema 继承关系:** `Project` = `NonSearchProject` + `ServerRenderedProject` + 自身字段
+>
+> 其中 `NonSearchProject` 和 `ServerRenderedProject` 均继承自 `BaseProject`。
+
+```
+
+Project
+├── BaseProject (基础信息)
+│   ├── slug
+│   ├── title
+│   ├── description
+│   ├── categories
+│   ├── client_side
+│   └── server_side
+├── NonSearchProject (非搜索专属字段)
+│   ├── body
+│   ├── status
+│   ├── requested_status
+│   ├── additional_categories
+│   ├── issues_url
+│   ├── source_url
+│   ├── wiki_url
+│   ├── discord_url
+│   └── donation_urls
+├── ServerRenderedProject (服务端渲染字段)
+│   ├── project_type
+│   ├── downloads
+│   ├── icon_url
+│   ├── color
+│   ├── thread_id
+│   └── monetization_status
+└── Project (自身字段)
+    ├── id
+    ├── team
+    ├── body_url ⚠️
+    ├── moderator_message ⚠️
+    ├── published
+    ├── updated
+    ├── approved
+    ├── queued
+    ├── followers
+    ├── license
+    ├── versions
+    ├── game_versions
+    ├── loaders
+    └── gallery
+
+```
+
+### 字段一览
+
+| 字段 | 类型 | 来源 | 说明 |
+|------|------|------|------|
+| `id` | `string` | Project | Project ID（base62 编码）。 |
+| `slug` | `string` | BaseProject | 用于自定义 URL 的简短标识符，正则 `^[\w!@$().`+,"'-]{3,64}$`。 |
+| `title` | `string` | BaseProject | Project 名称或标题。 |
+| `description` | `string` | BaseProject | 简短描述。 |
+| `body` | `string` | NonSearchProject | 长描述（支持 Markdown）。 |
+| `categories` | `string[]` | BaseProject | 主分类列表。 |
+| `additional_categories` | `string[]` | NonSearchProject | 附加分类（可搜索但非主要）。 |
+| `client_side` | `string` | BaseProject | 客户端支持类型。`required` / `optional` / `unsupported` / `unknown`。 |
+| `server_side` | `string` | BaseProject | 服务端支持类型。`required` / `optional` / `unsupported` / `unknown`。 |
+| `project_type` | `string` | ServerRenderedProject | 项目类型。`mod` / `modpack` / `resourcepack` / `shader`。 |
+| `downloads` | `integer` | ServerRenderedProject | 总下载次数。 |
+| `followers` | `integer` | Project | 关注者数量。 |
+| `status` | `string` | NonSearchProject | 项目状态：`approved` / `archived` / `rejected` / `draft` / `unlisted` / `processing` / `withheld` / `scheduled` / `private` / `unknown`。 |
+| `requested_status` | `string` ⚠️ | NonSearchProject | 申请中的状态。`approved` / `archived` / `unlisted` / `private` / `draft`。可为 `null`。 |
+| `license` | [`ProjectLicense`](#projectlicense) | Project | 许可证信息。 |
+| `team` | `string` | Project | 拥有此 project 的团队 ID。 |
+| `published` | `string` (ISO-8601) | Project | 发布日期。 |
+| `updated` | `string` (ISO-8601) | Project | 最后更新日期。 |
+| `approved` | `string` (ISO-8601) ⚠️ | Project | 审核通过日期。可为 `null`。 |
+| `queued` | `string` (ISO-8601) ⚠️ | Project | 提交审核日期。可为 `null`。 |
+| `icon_url` | `string` ⚠️ | ServerRenderedProject | 图标 URL。可为 `null`。 |
+| `color` | `integer` ⚠️ | ServerRenderedProject | 从图标自动生成的 RGB 颜色值。可为 `null`。 |
+| `thread_id` | `string` | ServerRenderedProject | 关联的审核线程 ID。 |
+| `monetization_status` | `string` | ServerRenderedProject | 变现状态。`monetized` / `demonetized` / `force-demonetized`。 |
+| `issues_url` | `string` ⚠️ | NonSearchProject | 问题跟踪链接。可为 `null`。 |
+| `source_url` | `string` ⚠️ | NonSearchProject | 源代码链接。可为 `null`。 |
+| `wiki_url` | `string` ⚠️ | NonSearchProject | Wiki 链接。可为 `null`。 |
+| `discord_url` | `string` ⚠️ | NonSearchProject | Discord 邀请链接。可为 `null`。 |
+| `donation_urls` | [`ProjectDonationURL[]`](#projectdonationurl) | NonSearchProject | 捐赠链接列表。 |
+| `body_url` | `string` ⚠️ ⛔ | Project | 已弃用，始终为 `null`。 |
+| `moderator_message` | [`ModeratorMessage`](#moderatormessage) ⛔ | Project | 已弃用，始终为 `null`。 |
+| `versions` | `string[]` | Project | 所有版本 ID 列表（`draft` 状态时为空）。 |
+| `game_versions` | `string[]` | Project | 支持的 Minecraft 版本列表。 |
+| `loaders` | `string[]` | Project | 支持的模组加载器列表。 |
+| `gallery` | [`GalleryImage[]`](#galleryimage) | Project | 图库图片列表。 |
+
+> ⚠️ 表示可为 `null`。⛔ 表示已弃用。
+
+---
+
+### ProjectLicense
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | `string` | SPDX 许可证 ID（如 `LGPL-3.0-or-later`）。 |
+| `name` | `string` | 许可证全名（如 `GNU Lesser General Public License v3 or later`）。 |
+| `url` | `string` ⚠️ | 许可证文本 URL，可为 `null`。 |
+
+### ProjectDonationURL
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | `string` | 捐赠平台 ID（如 `patreon`）。 |
+| `platform` | `string` | 捐赠平台名称（如 `Patreon`）。 |
+| `url` | `string` | 捐赠链接。 |
+
+### GalleryImage
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `url` | `string` | 图片 URL。 |
+| `featured` | `boolean` | 是否为精选图片。 |
+| `title` | `string` ⚠️ | 图片标题，可为 `null`。 |
+| `description` | `string` ⚠️ | 图片描述，可为 `null`。 |
+| `created` | `string` (ISO-8601) | 创建日期。 |
+| `ordering` | `integer` | 排序序号（先按此字段排，再按标题字母序排）。 |
+
+### ModeratorMessage
+
+> ⛔ 已弃用，始终为 `null`。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `message` | `string` | 审核员留言。 |
+| `body` | `string` ⚠️ | 留言详细内容，可为 `null`。 |
+
+---
+
+## 示例
+
+### 请求 - 获取单个 project
+
+```bash
+curl -X GET "https://api.modrinth.com/v2/project/my_project"
+```
+
+### 响应
+
+```json
+{
+  "id": "AABBCCDD",
+  "slug": "my_project",
+  "team": "MMNNOOPP",
+  "title": "My Project",
+  "description": "A short description",
+  "body": "A long body describing my project in detail",
+  "categories": ["technology", "adventure", "fabric"],
+  "additional_categories": ["utility"],
+  "client_side": "required",
+  "server_side": "optional",
+  "project_type": "mod",
+  "status": "approved",
+  "requested_status": null,
+  "downloads": 52341,
+  "followers": 1203,
+  "license": {
+    "id": "MIT",
+    "name": "MIT License",
+    "url": "https://opensource.org/licenses/MIT"
+  },
+  "published": "2023-03-15T10:30:00Z",
+  "updated": "2024-01-20T14:22:00Z",
+  "approved": "2023-03-15T12:00:00Z",
+  "queued": null,
+  "icon_url": "https://cdn.modrinth.com/data/AABBCCDD/icon.png",
+  "color": 8703084,
+  "thread_id": "TTUUVVWW",
+  "monetization_status": "monetized",
+  "issues_url": "https://github.com/my_user/my_project/issues",
+  "source_url": "https://github.com/my_user/my_project",
+  "wiki_url": null,
+  "discord_url": "https://discord.gg/AaBbCcDd",
+  "donation_urls": [
+    {
+      "id": "patreon",
+      "platform": "Patreon",
+      "url": "https://www.patreon.com/my_user"
+    }
+  ],
+  "body_url": null,
+  "moderator_message": null,
+  "versions": ["IIJJKKLL", "QaRSSTT"],
+  "game_versions": ["1.19", "1.19.1", "1.19.2", "1.19.3"],
+  "loaders": ["forge", "fabric", "quilt"],
+  "gallery": [
+    {
+      "url": "https://cdn.modrinth.com/data/AABBCCDD/images/009b7d8d6e8bf04968a29421117c59b3efe2351a.png",
+      "featured": true,
+      "title": "My awesome screenshot!",
+      "description": "This awesome screenshot shows all of the blocks in my mod!",
+      "created": "2023-06-01T08:15:00Z",
+      "ordering": 0
+    }
+  ]
+}
+```
+
+### 请求 - 批量获取多个 project
+
+```bash
+curl -X GET "https://api.modrinth.com/v2/projects?ids=%5B%22AABBCCDD%22%2C%22my_project%22%5D"
+```
+
+> URL 编码后的 `ids` 参数值为 `["AABBCCDD","my_project"]`。
+
+### 响应
+
+```json
+[
+  { "...": "..." },
+  { "...": "..." }
+]
+```
+
+返回 `Project` 对象数组，每个对象结构与单个获取一致。