API 参考 / schedule

创建里程碑

POST /api/v1/schedule/milestones · createMilestone

Workflow OpenAPI 合同中的 createMilestone 端点（POST /schedule/milestones）。完整字段与示例以合同为准。

鉴权：项目 API Token（Authorization: Bearer wfp_…）。详见 Agent 接入。

参数

Idempotency-Key: string —— 幂等键（建议用 UUID，最长 255 字符）。重复提交同键且请求体一致时返回首次创建的结果（200）而不新建对象；请求体不一致返回 409。有效期 24 小时。

请求体

title（必填）: string
description: string —— 里程碑说明（可选，纯文本）。
kind: enum；取值：review / integration / freeze / release / custom
requirementIds: string[]
releaseWindowId: string
targetOn（必填）: string
status: enum；取值：planned / at_risk / done
reason: string

响应字段 · 201

id（必填）: string
displayKey（必填）: string
title（必填）: string
description: string —— 里程碑说明（可选，纯文本）。空串表示无说明。
kind（必填）: enum；取值：review / integration / freeze / release / custom
requirementIds（必填）: string[] —— 关联需求 id 列表（多对多，可为空表示项目级节点）。
releaseWindowId: string
targetOn（必填）: string
status（必填）: enum；取值：planned / at_risk / done
createdAt（必填）: string
updatedAt（必填）: string

响应字段 · 200

id（必填）: string
displayKey（必填）: string
title（必填）: string
description: string —— 里程碑说明（可选，纯文本）。空串表示无说明。
kind（必填）: enum；取值：review / integration / freeze / release / custom
requirementIds（必填）: string[] —— 关联需求 id 列表（多对多，可为空表示项目级节点）。
releaseWindowId: string
targetOn（必填）: string
status（必填）: enum；取值：planned / at_risk / done
createdAt（必填）: string
updatedAt（必填）: string

错误

401：Problem 错误响应
403：Problem 错误响应
409：Problem 错误响应
422：Problem 错误响应

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/schedule/milestones" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"title":"示例标题","targetOn":"2026-08-01","description":"一段描述文字"}'

响应示例

HTTP/1.1 201
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "displayKey": "示例文本",
  "title": "示例标题",
  "kind": "review",
  "requirementIds": [
    "018f3c2e-0000-7000-8000-000000000000"
  ],
  "targetOn": "2026-08-01",
  "status": "planned",
  "createdAt": "示例文本",
  "updatedAt": "2026-08-01"
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引

Workflow 正在加载…