# 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` 对象数组，每个对象结构与单个获取一致。