快速开始

API v1 的基础地址是：

https://1939.giaory.xyz/api/v1

读取卡牌、卡背和公开卡组不需要 API Key。管理自己的卡组才需要鉴权。

1. 发出第一条请求

下面的请求搜索卡牌目录，并限制只返回 3 项：

curl "https://1939.giaory.xyz/api/v1/cards?q=虎式&limit=3"

浏览器和 Node.js 也可以直接使用 fetch：

const response = await fetch(
  'https://1939.giaory.xyz/api/v1/cards?q=虎式&limit=3'
)

if (!response.ok) {
  const failure = await response.json()
  throw new Error(`${failure.error.code}: ${failure.error.message}`)
}

const { data: cards, meta } = await response.json()
console.log(cards, meta.total)

成功响应统一使用 data 和 meta：

{
  "data": [
    {
      "card_id": "<card_id>",
      "name_zh": "<卡牌名称>",
      "pool": "active",
      "is_derived": false
    }
  ],
  "meta": {
    "page": 1,
    "limit": 3,
    "total": 1,
    "total_pages": 1
  }
}

2. 读取公开卡组

curl "https://1939.giaory.xyz/api/v1/decks?sort=likes&limit=10"

从列表项的 share_slug 可以继续读取完整卡组：

curl "https://1939.giaory.xyz/api/v1/decks/<share_slug>"

攻略、备卡和展示设置分别位于 guide、guide.reserve_recommendations 与 display。

3. 管理自己的卡组

先在个人中心的 API 页面创建 API Key，再把 Key 放进请求头：

curl "https://1939.giaory.xyz/api/v1/users/<user_id>/decks" \
  -H "Authorization: Bearer <kd_api_key>"

user_id 是个人中心“军籍编号（UID）”显示的 UUID。它必须属于当前 API Key，否则返回 user_mismatch。

下一步：

• 只想调用备卡：看调用备卡
• 需要创建或更新卡组：看管理自己的卡组
• 需要接入异常处理：看分页与错误

先用公开接口验证网络

如果公开的 /cards 能访问、带 Key 的请求不能访问，优先检查请求头、Key 是否过期、权限范围和路径中的 user_id，不要先归因于部署或 DNS。