数据库接口（API Key）

以下接口允许你通过 API Key 认证来发现 TopMat 热力学数据库（TOPDB）：浏览数据库目录、确认当前 API Key 用户已激活的数据库、按任务类型筛选可用数据库，并在创建任务前查询数据库的元素与可用相。所有请求都必须在 Authorization 头中携带有效的 API Key。

数据库概述

TopMat 的计算任务依赖热力学数据库（TOPDB）。每个数据库定义了可用的元素、相以及支持的任务类型。创建任务时，task_config.tdb_code 必须引用一个真实存在的数据库代码（即数据库记录中的 code 字段），因此创建任务前应先用本页的接口完成数据库发现与筛选。

注意

v2 API 只提供数据库的读取与发现接口。添加或移除用户与数据库的关联关系不属于 v2 API，仍由 Web 控制台对应的 JWT 接口处理，请勿在 API Key 流程中寻找这类写接口。

任务创建工作流程

从发现数据库到创建任务的推荐顺序如下：

1. 发现数据库：调用 GET /api/v2/database 浏览全部已启用的数据库，可按类型、级别或关键字筛选。
2. 确认激活状态：调用 GET /api/v2/database/users 查看当前 API Key 用户已关联的数据库及其订阅状态（user_status）；也可用 GET /api/v2/database/user/status 查询单个数据库的状态。
3. 按任务类型筛选：确定要执行的计算类型后，调用 GET /api/v2/database/by-task?task_type=<类型>，只保留 support_task_list 包含该任务类型的数据库。
4. 选择元素并查询可用相：从目标数据库的 element_list 中选择参与计算的元素，调用 POST /api/v2/database/{db_id}/phases 获取这些元素下可用的相列表，用于填写 task_config.condition.activated_phases。
5. 填写参数并创建任务：将所选数据库的 code 填入 task_config.tdb_code，并参考任务配置参数补全其余字段，最后调用 POST /api/v2/task 创建任务。详见任务接口。

Base URL

Base URL

https://api.topmaterial-tech.com/api/v2

认证方式

使用 API Key 认证

curl https://api.topmaterial-tech.com/api/v2/database \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

API Key 缺失或无效时返回 401；Key 被禁用或过期时返回 403。详见认证。

响应数据模型

除可用相和用户状态接口外，本页接口均以 TopDBItemResponse 表示一个数据库，分页列表包装为 ListTopDBResponse。

TopDBItemResponse

字段	类型	说明
id	string (UUID)	数据库 ID。
code	string	数据库代码，创建任务时填入 task_config.tdb_code。
name	string	数据库名称。
description	string	数据库描述。
type	string	数据库类型（自由文本）。
version	string	数据库版本号。
level	string	数据库级别，已知取值包括 free、premium、ultimate，但该列为自由文本，不要假设为封闭枚举。
element_list	string[]	数据库包含的元素列表。
phase_list	string[]	数据库包含的相列表。
support_task_list	string[]	数据库支持的任务类型列表，取值与 task_config.task_type 对应。该列表可能包含历史兼容值；创建任务时仅应使用任务接口文档列出的任务类型。
sp_id	string (UUID) | null	关联订阅套餐的 ID，可能为 null。
price	number	数据库价格。
user_status	string	当前用户对该数据库的订阅状态。来源于订阅记录，已知存储值包括 trail、active、inactive、expired、pending；列表接口通常只暴露 active 或 inactive。不要假设为封闭枚举。
created_at	string	创建时间（RFC 3339，如 2026-01-01T00:00:00Z）。
updated_at	string	更新时间（RFC 3339）。

ListTopDBResponse

字段	类型	说明
items	array	数据库列表，每项为 TopDBItemResponse 对象。
total	integer	总记录数。
page	integer	当前页码。
size	integer	每页条数。

列出数据库

列出数据库接口

GET /database

以分页形式返回全部已启用（enable）的数据库。数据库记录本身还有 disable、invisible 等状态，但 API 只返回已启用的记录。

查询参数

参数	类型	必填	说明
type	string	否	按数据库类型过滤。
level	string	否	按数据库级别过滤。
search	string	否	按数据库代码、名称或元素搜索。
page	integer	否	页码，默认 1。
size	integer	否	每页条数，默认 10。

请求示例

查询数据库列表

curl "https://api.topmaterial-tech.com/api/v2/database?level=free&page=1&size=10" \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

响应 — 200 OK

响应示例：数据库列表

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "code": "TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB",
      "name": "高温陶瓷数据库 TopDB-Cer",
      "description": "包含 B、C、Si、Zr、Hf、La、Y、Ti、O 元素的热力学数据库",
      "type": "thermodynamic",
      "version": "1.0.0",
      "level": "free",
      "element_list": ["B", "C", "SI", "ZR", "HF", "LA", "Y", "TI", "O"],
      "phase_list": ["GAS", "LIQUID", "HCP_A3_HF", "DIAMOND_A4", "HFC", "BCC_A2", "GRAPHITE"],
      "support_task_list": ["point_calculation", "line_calculation", "binary_equilibrium", "thermodynamic_properties_next", "scheil_solidification", "binary_cpt_diagram"],
      "sp_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "price": 0,
      "user_status": "active",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-20T08:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 10
}

按任务类型筛选数据库

按任务类型筛选数据库接口

GET /database/by-task

只返回 support_task_list 包含指定任务类型的已启用数据库。确定计算类型后用此接口缩小数据库选择范围。

查询参数

参数	类型	必填	说明
task_type	string	是	任务类型，与 task_config.task_type 对应，例如 line_calculation。
page	integer	否	页码，默认 1。
size	integer	否	每页条数，默认 10。

请求示例

筛选支持线计算的数据库

curl "https://api.topmaterial-tech.com/api/v2/database/by-task?task_type=line_calculation&page=1&size=10" \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

响应 — 200 OK

返回 ListTopDBResponse，结构同列出数据库。

错误

状态码	含义	响应体
400	缺少必填的 task_type 参数	参数解析错误
401	API Key 缺失或无效	{"error": "invalid API key"}

查询当前用户的数据库

查询当前用户的数据库接口

GET /database/users

返回当前 API Key 用户关联的数据库，并附带订阅状态（user_status），用于确认哪些数据库已激活。过滤与分页参数同列出数据库。

查询参数

参数	类型	必填	说明
type	string	否	按数据库类型过滤。
level	string	否	按数据库级别过滤。
search	string	否	按数据库代码、名称或元素搜索。
page	integer	否	页码，默认 1。
size	integer	否	每页条数，默认 10。

请求示例

查询我的数据库

curl "https://api.topmaterial-tech.com/api/v2/database/users?page=1&size=10" \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

响应 — 200 OK

返回 ListTopDBResponse，其中每项的 user_status 反映当前用户的订阅状态，结构同列出数据库。

查看数据库详情

查看数据库详情接口

GET /database/{db_id}

按 UUID 获取单个已启用数据库的完整信息。

路径参数

参数	类型	说明
db_id	string (UUID)	数据库 ID。

请求示例

查询数据库详情

curl https://api.topmaterial-tech.com/api/v2/database/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

响应 — 200 OK

响应示例：数据库详情

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code": "TOPDB-B-C-Si-Zr-Hf-La-Y-Ti-O.TOPDB",
  "name": "高温陶瓷数据库 TopDB-Cer",
  "description": "包含 B、C、Si、Zr、Hf、La、Y、Ti、O 元素的热力学数据库",
  "type": "thermodynamic",
  "version": "1.0.0",
  "level": "free",
  "element_list": ["B", "C", "SI", "ZR", "HF", "LA", "Y", "TI", "O"],
  "phase_list": ["GAS", "LIQUID", "HCP_A3_HF", "DIAMOND_A4", "HFC", "BCC_A2", "GRAPHITE"],
  "support_task_list": ["point_calculation", "line_calculation", "binary_equilibrium", "thermodynamic_properties_next", "scheil_solidification", "binary_cpt_diagram"],
  "sp_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "price": 0,
  "user_status": "inactive",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-05-20T08:00:00Z"
}

警告

当前限制：详情接口暂不会计算当前用户的真实订阅状态，返回的 user_status 固定为 "inactive"。需要真实订阅状态时，请使用查询当前用户的数据库或查询用户数据库状态接口。

错误

状态码	含义	响应体
404	数据库不存在或未启用	{"error": "TopDB not found"}

查询数据库可用相

查询数据库可用相接口

POST /database/{db_id}/phases

给定参与计算的元素列表，返回该数据库在这些元素下可用的相列表。返回的相可用于填写 task_config.condition.activated_phases。

调用此接口要求当前用户对目标数据库持有有效（active 且未过期）的访问权限，否则返回 403。

路径参数

参数	类型	说明
db_id	string (UUID)	数据库 ID。

请求体

字段	类型	必填	说明
element_list	string[]	是	参与计算的元素列表，通常为目标数据库 element_list 的子集。

请求示例

查询可用相

curl -X POST https://api.topmaterial-tech.com/api/v2/database/3fa85f64-5717-4562-b3fc-2c963f66afa6/phases \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "element_list": ["HF", "C"]
  }'

响应 — 200 OK

响应示例：可用相列表

{
  "phase_list": ["GAS", "LIQUID", "HCP_A3_HF", "DIAMOND_A4", "HFC"]
}

字段	类型	说明
phase_list	string[]	给定元素下可用的相列表。

警告

当前限制：服务端内部解析数据库文件失败时，接口同样返回 200 OK 和空的 phase_list，与「给定元素下确实没有兼容相」无法区分。得到空列表时，建议先核对 element_list 中的元素拼写是否与数据库 element_list 一致。

错误

状态码	含义	响应体
403	当前用户没有该数据库的有效访问权限（未激活或已过期）	{"error": "You do not have access to this TopDB or your access has expired"}
404	数据库不存在或未启用	{"error": "TopDB not found"}

查询用户数据库状态

查询用户数据库状态接口

GET /database/user/status

查询指定用户对指定数据库的订阅状态。API Key 用户只能查询自己的状态：user_id 必须与 API Key 所属用户一致，否则返回 403。

查询参数

参数	类型	必填	说明
user_id	string (UUID)	是	用户 ID，必须是当前 API Key 所属用户的 ID。
topdb_id	string (UUID)	是	数据库 ID。

请求示例

查询数据库订阅状态

curl "https://api.topmaterial-tech.com/api/v2/database/user/status?user_id=550e8400-e29b-41d4-a716-446655440000&topdb_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer tk_0123456789abcdef0123456789abcdef"

响应 — 200 OK

响应示例：数据库订阅状态

{
  "status": "active"
}

字段	类型	说明
status	string	订阅状态，来源于订阅记录；已知存储值包括 trail、active、inactive、expired、pending。没有关联订阅记录时返回 inactive。不要假设为封闭枚举。

错误

状态码	含义	响应体
403	查询了其他用户的状态	{"error": "Cannot access other user's TopDB status"}
404	数据库不存在、未启用或没有可用的订阅套餐	{"error": "TopDB not found"}

与任务创建的关系

创建任务接口 POST /api/v2/task 通过 task_config.tdb_code 指定数据库，tdb_code 的值就是本页接口返回的数据库 code。服务端会查找已启用的数据库记录、校验订阅访问权限，并把 tdb_code 替换为服务端管理的数据库文件路径（tdb_file）后交给计算核心：

• tdb_code 和 tdb_file 都未提供时，返回 400：task_config.tdb_code or task_config.tdb_file is required。
• tdb_code 不存在或未启用时，返回 400：TopDB code '<code>' was not found or is disabled。
• 当前用户对 tdb_code 对应数据库没有有效订阅时，返回 403：the current subscription does not allow access to TopDB code '<code>'。

为兼容旧客户端，缺少 tdb_code 时会从 tdb_file 路径的文件名推导数据库代码；客户端传入的文件路径本身不会被使用。