# 介绍与快速开始

了解 ATHub，发起你的第一个请求。

ATHub 是 ALBATEXTUS 统一服务的 v2 内容模块。通过一套 REST API，管理平台、作者、标签库、小说、卷和章节。

## 开始之前

ATHub 服务地址为 `https://api.albatextus.com`。以下所有接口统一使用此地址，且必须携带 `Authorization: Bearer <ATHUB_API_TOKEN>` 请求头。

先登录账户，在 `POST /api/v1/account/key` 创建自己的 ATHub Key。创建时只返回一次明文，将它保存到调用端的 `ATHUB_API_TOKEN` 环境变量。所有内容路径统一以 `/api/v2/` 开头；账户与 OAuth 功能使用 `/api/v1/`。两者在同一 Go 进程中分别监听 `8001`（OAuth）和 `8003`（ATHub），数据库分别配置。

> 个人 Key 目前可读写共享内容库，不按用户隔离小说。请仅在服务端或采集程序中使用，切勿放入网页或公开客户端。Key 和调用记录保存在账户库；文档站不会代发 API 请求或保存你的密钥。

## 发起第一个请求

```bash
curl --request GET 'https://api.albatextus.com/api/v2/platforms' \
  --header "Authorization: Bearer $ATHUB_API_TOKEN"
```

成功返回平台数组；没有平台时返回 `[]`。接下来可先[创建平台](/athub/platforms-create)，再[批量上传小说](/athub/upload)。

## 接口一览

| 方法 | 路径 | 用途 | 成功状态 |
| --- | --- | --- | --- |
| GET | `/api/v2/platforms` | 获取平台列表或单个平台 | 200 |
| POST | `/api/v2/platforms` | 新建平台 | 201 |
| GET | `/api/v2/authors` | 获取作者列表或单个作者 | 200 |
| POST | `/api/v2/authors` | 新建作者标识 | 201 |
| GET | `/api/v2/tags` | 获取独立标签库列表或单个标签 | 200 |
| POST | `/api/v2/tags` | 新建标签 | 201 |
| PUT | `/api/v2/tags?id=...` | 修改标签名称 | 200 |
| DELETE | `/api/v2/tags?id=...` | 删除未被引用的标签 | 204 |
| GET | `/api/v2/novelinfo` | 获取小说列表或小说元信息 | 200 |
| POST | `/api/v2/novelinfo` | 新建小说，仅元信息 | 201 |
| PUT | `/api/v2/novelinfo?id=...` | 完整覆盖小说元信息 | 200 |
| DELETE | `/api/v2/novelinfo?id=...` | 删除小说及全部卷、章节 | 204 |
| GET | `/api/v2/volumes` | 获取卷列表或一个卷 | 200 |
| PUT | `/api/v2/volumes` | 上传一个卷，不存在则新增、存在则覆盖卷名 | 200 |
| DELETE | `/api/v2/volumes?novelId=...&order=...` | 删除空卷 | 204 |
| GET | `/api/v2/toc?novelId=...` | 一次获取全书卷与章节目录，不含正文 | 200 |
| GET | `/api/v2/content` | 获取章节列表或一个章节，包含正文 | 200 |
| PUT | `/api/v2/content` | 上传一个章节，不存在则新增、存在则覆盖 | 200 |
| DELETE | `/api/v2/content?novelId=...&order=...` | 删除一个章节 | 204 |
| POST | `/api/v2/upload` | 一次创建小说并导入卷/章节，或给已有小说批量续传 | 201 / 200 |

POST 不带查询参数；`PUT /api/v2/volumes`、`PUT /api/v2/content` 也不带查询参数。
不支持 PATCH。平台和作者目前只提供获取与创建，没有修改/删除接口。

## 推荐阅读

- [鉴权与通用约定](/athub/authentication)：确认服务地址、请求格式和大小限制。
- [批量上传小说](/athub/upload)：一次导入元信息、卷和章节。
- [获取全书目录](/athub/toc)：一次读取卷与章节标题，不传输正文。
- [完整调用示例](/athub/examples)：运行从零导入和分批续传示例。