API 参考 / documents

创建文档

POST /api/v1/documents · createDocument

创建当前项目文档；actor 与 project 只来自 session/Host 上下文。

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

参数

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

请求体

title（必填）: string
body: string
summary: string
type: enum；取值：spec / note / release_plan / qa_plan / custom
status: enum；取值：draft / in_review / published / archived
ownerId: string
requirementId: string
externalUrl: string
reason: string

响应字段 · 201

id（必填）: string
displayKey（必填）: string
title（必填）: string
body（必填）: string
summary: string
type（必填）: enum；取值：spec / note / release_plan / qa_plan / custom
status（必填）: enum；取值：draft / in_review / published / archived
ownerId（必填）: string
requirementId: string
externalUrl: string —— 外部知识库链接（如 GitHub 仓库 / 文件地址）。过渡形态：真实文档方向转外部 Git 知识库，本字段承载点击跳转的外链，body 仍是本地 Markdown 只读内容。
createdAt（必填）: string
updatedAt（必填）: string

响应字段 · 200

id（必填）: string
displayKey（必填）: string
title（必填）: string
body（必填）: string
summary: string
type（必填）: enum；取值：spec / note / release_plan / qa_plan / custom
status（必填）: enum；取值：draft / in_review / published / archived
ownerId（必填）: string
requirementId: string
externalUrl: string —— 外部知识库链接（如 GitHub 仓库 / 文件地址）。过渡形态：真实文档方向转外部 Git 知识库，本字段承载点击跳转的外链，body 仍是本地 Markdown 只读内容。
createdAt（必填）: string
updatedAt（必填）: string

错误

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

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/documents" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"title":"示例标题","body":"示例文本","summary":"一段描述文字"}'

响应示例

HTTP/1.1 201
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "displayKey": "示例文本",
  "title": "示例标题",
  "body": "示例文本",
  "type": "spec",
  "status": "draft",
  "ownerId": "018f3c2e-0000-7000-8000-000000000000",
  "createdAt": "示例文本",
  "updatedAt": "2026-08-01"
}

合同真值：OpenAPI 3.1（0.1.0）。

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