KARDS Decker API

主题

卡组字段 ​

卡组响应 ​

字段类型说明
idUUID卡组主键
namestring由攻略字段组合出的展示名称
descriptionstring | null卡组介绍
main_factionstring主阵营
ally_factionstring | null盟军阵营
deck_codestring标准 KARDS 卡组代码
cards_snapshot{card_id,count}[]服务端从代码解析的卡牌快照
tagsstring[]最多 12 个，每个最多 20 字符
share_slugstring | null公开详情路径使用的分享标识
displayobject展示卡与卡背设置
guideobject | null卡组攻略、核心卡、平替和 OTK 组件等内容
archiveobject必备组件、备卡、平替建议和图表设置
authorobject公开作者资料，存在时返回
created_at / updated_atdate-time | null创建和更新时间

自己的卡组接口还返回 visibility 与 sort_order；公开接口不会返回这两个管理字段。

guide ​

字段限制说明
schema_version只读，固定为 1攻略结构版本
prefix最多 24 字符名称前缀
system必填，最多 40 字符卡组体系
variant最多 40 字符分支或版本
description最多 1200 字符卡组介绍；写入后只从响应顶层 description 返回
core_cards最多 30 个唯一 ID必须属于主卡组且不能是衍生卡
reserve_recommendations最多 30 个唯一 ID已废弃的 v1 兼容字段；不与 archive.alternatives 自动同步，新客户端不要使用
substitutions最多 20 项标准卡与替换卡的对应关系
otk_components最多 10 组每组 1 至 10 个主卡组内卡牌 ID

guide 在 PATCH 中是整对象替换，详见管理自己的卡组。

archive.key_components ​

archive.key_components 表示必备组件（必备卡）板块：

json
{
  "archive": {
    "key_components": {
      "enabled": true,
      "items": [
        {
          "card_id": "<deck_card_id>",
          "reason": "这张牌在卡组中的关键作用"
        }
      ]
    }
  }
}

items 至多 8 项。enabled 为 true 时必须至少有 1 项，且每项 reason 必填并在去除首尾空白后保持非空。每项 card_id 必须是已知的非衍生卡并属于当前卡组。

写入时 key_components 必须是对象。新记录未提交时通常返回默认禁用对象 {"enabled":false,"items":[]}，旧记录或空值可能返回 null；要停用该板块，请提交该默认禁用对象。

archive.alternatives ​

archive.alternatives 表示备卡（备选卡牌），即构筑或调整这套卡组时可选带入的候选卡：

json
{
  "archive": {
    "alternatives": {
      "enabled": true,
      "items": [
        {
          "card_id": "<optional_card_id>",
          "reason": "针对当前环境可选带入"
        }
      ]
    }
  }
}

items 至多 10 项。备卡不必已在当前卡组中，但必须是可供主阵营或盟军阵营使用的已知非总部、非衍生卡；宿主阵营可用的卡也符合条件。enabled 为 true 时必须至少有 1 项，且每项 reason 必填并在去除首尾空白后保持非空。新记录未提交时通常返回默认禁用对象 {"enabled":false,"items":[]}，旧记录或空值可能返回 null；停用时提交该默认禁用对象。

不要混淆这三个字段：key_components 是当前卡组内不可或缺的必备卡；alternatives 是不绑定某张原卡的可选带卡；replacements 是从当前卡组原卡指向一个或多个替代选项的平替关系。卡牌目录中的官方预备池由 pool=reserve 表示，也不是这里的备卡。

archive.chart_settings.otkConfig ​

这是网站的 OTK 概率图表配置，不是另一套备卡字段。每个 items 条目用 required 表示至少需要摸到的数量；card_ids 可列出至多 39 个当前卡组内的卡牌作为 OR 卡池，其中任意卡都计入该数量。旧数据只有单个 card_id 时仍受支持，API 会保留提交的 card_ids 并同步首项到 card_id。

display ​

响应把两个输入字段归入 display：

json
{
  "display": {
    "featured_card_id": "<card_id>",
    "card_back_id": "<card_back_id>"
  }
}

写入时仍应把 featured_card_id 与 card_back_id 放在请求正文顶层。展示卡必须属于当前卡组；卡背必须来自卡背目录并通过可用性与阵营校验。

visibility ​

值行为
public出现在公开列表，也可通过分享标识读取
unlisted不出现在公开列表，知道分享标识即可读取
private只允许所有者通过 API Key 读取