公开活动 API · 终末地版本日历

01 / OVERVIEW

概览

该接口只读、免密，并返回 Access-Control-Allow-Origin: *。浏览器、服务端程序和命令行工具都可以直接调用，无需 Cookie 或 API Key。

稳定版本契约

当前 API 版本为 1。调用方应同时检查 HTTP 状态码、顶层 success 与 apiVersion。

02 / QUICK START

快速调用

命令行

curl "https://ef-cal.mogujun.icu/api/v1/events?version=5&status=live"

浏览器 JavaScript

const response = await fetch(
  "https://ef-cal.mogujun.icu/api/v1/events?category=operator,limited&status=upcoming",
);
const payload = await response.json();

if (!payload.success) throw new Error(payload.error.message);
console.log(payload.data.events);

03 / QUERY

查询参数

参数	默认值	说明
`version`	`all`	`all`、版本键（如 `version-5`）或版本号（如 `5`）
`category`	`all`	逗号分隔的 `operator`、`arsenal`、`permanent`、`limited`、`update`
`status`	`all`	`all`、`upcoming`、`live`、`ended`
`from`	无	带时区的 RFC 3339 时间；查询区间起点（包含）
`to`	无	带时区的 RFC 3339 时间；查询区间终点（不包含）

category 可以组合，例如 ?category=operator,arsenal。时间筛选采用区间相交语义，而不是只比较活动开始时间。

没有确定结束时间的常驻活动会被视为持续开放；单次更新节点只在其发生时刻与查询区间相交。参数非法、版本不存在或 from 不早于 to 时返回 HTTP 400。

04 / RESPONSE

成功响应

{
  "success": true,
  "apiVersion": "1",
  "generatedAt": "2026-07-12T00:00:00.000Z",
  "timeZone": "Asia/Shanghai",
  "source": {
    "mode": "origin",
    "partial": false,
    "updatedAt": "2026-07-11T18:16:32.446Z"
  },
  "data": {
    "activeVersionKey": "version-5",
    "versions": [],
    "events": []
  },
  "meta": {
    "total": 0,
    "filters": {
      "version": "all",
      "categories": ["all"],
      "status": "all",
      "from": null,
      "to": null
    }
  }
}

数据来源状态

`source.mode`	含义
`origin`	主站版本快照读取成功，并与日历仓库人工活动合并
`partial`	只取得部分上游数据，缺失部分已由本地数据补齐
`fallback`	上游不可用，完整使用仓库内置版本与活动数据

调用方不应只根据 HTTP 200 判断数据是否来自上游，还应检查 source.mode 和 source.partial。

05 / EVENT FIELDS

事件字段

字段	说明
`id`	稳定事件 ID
`versionKey`	事件所属版本键
`poolId`	对应主站卡池 ID；非卡池活动为 `null`
`category`	活动分类
`title` / `related`	活动标题及配套签到、作战演练等关联内容
`start` / `end`	ISO 8601 时间；未知或开放式结束为 `null`
`status`	`upcoming`、`live` 或 `ended`
`startUnknown`	`start` 是否仅为时间轴定位锚点
`startLabel` / `endLabel`	未确定或相对时间的展示说明
`permanent` / `milestone`	是否为常驻内容或单次更新节点
`overlayFor`	更新节点所依附的活动 ID
`image`	可直接访问的绝对图片 URL，或 `null`
`color` / `eventInk`	时间轴背景色与建议文字色
`description` / `sourceNote`	活动说明、数据来源或不确定性说明

排轨位置、浏览器 Date 对象和数据库管理字段不会公开。

poolKind 区分普通卡池（standard）与重构卡池（reconstruction）；重构池仍归属 operator / arsenal 分类。

displayEnd 仅限制常驻活动条在下一版本分割线处收束，不代表内容关闭，不参与状态或时间筛选。真实结束时间以 end 为准。

06 / ERRORS

错误响应

{
  "success": false,
  "apiVersion": "1",
  "error": {
    "code": "INVALID_QUERY",
    "message": "查询参数无效",
    "details": []
  }
}

HTTP 状态	场景
`400`	查询参数非法
`405`	使用了 GET、OPTIONS 之外的方法
`429`	同一客户端在限速窗口内请求过多
`500`	服务端发生无法通过本地数据恢复的错误

上游主站超时或暂时不可用通常不会返回 502；接口会使用仓库内置数据，并通过 source.mode: "fallback" 告知调用方。

07 / RATE LIMIT

请求频率限制

接口默认按客户端 IP 提供每 60 秒 60 次函数请求的基础保护。超过限额时返回 HTTP 429 和错误代码 RATE_LIMITED：

HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Limit: 60
RateLimit-Remaining: 0
Cache-Control: no-store

跨域预检 OPTIONS 不占额度。由 ESA 或 Vercel CDN 直接命中的缓存响应通常不会进入函数，也不会消耗函数内额度。当前限制在每个 Vercel 函数实例内独立计数，用于抑制突发请求，并非跨全部实例的严格全局配额。

08 / CACHE

缓存与实时状态

Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300

共享 CDN 可缓存成功响应 60 秒，并在后台重新验证期间短暂使用旧响应。因此 status 通常最多可能相对请求时刻延迟约一分钟；需要临界秒级精度时，应根据事件时间字段自行重新计算。

所有错误响应（400、405、429 和 500）均使用 no-store，避免 CDN 缓存临时错误或限速结果。

09 / SOURCES

数据来源与免责声明

规范版本与卡池信息来自抽卡主站公开接口；人工活动主要依据罗德岛蜜饼工坊发布的「向渊行」非官方活动时间轴整理。

接口是社区维护的非官方服务，与鹰角网络、峘形山工作室及相关权利方不存在隶属、授权或背书关系。若接口内容与官方公告或游戏内显示不一致，请以官方信息为准；调用方展示数据时应保留适当的非官方说明和来源信息。