API 参考 / attachments

按目标对象列附件

GET /api/v1/attachments · listAttachments

按当前项目 RLS 读取某个目标对象（targetType+targetId）的附件元数据列表；只返回元数据 （文件名/大小/mime/上传者/时间），不返回文件本体。targetType 只接受白名单内的值 （requirement / work_item / bug / milestone / document / comment），其余返回 422——不返回空列表， 免得参数写错被当成「这个对象没有附件」。targetType=work_item 且 targetId 指向的工作项 type=bug 时，服务端按 bug 查（与上传侧同一条归一规则，B-00065），不会回一个空列表。 评论附件（B-00080）：targetType=comment + targetId=评论 uuid 列出挂在这条评论上的附件； 讨论区可用逗号分隔的多值 targetId 一次取回整屏评论的附件（B-00090）， 评论附件不会出现在宿主对象的附件列表里（宿主的附件列表仍按 requirement / bug / work_item 等自己的 targetType 查）。

多值语义：limit 作用在每个 targetId 上（不是总条数），这样一条评论的附件不会因为 前面几条占满配额而整条消失；某个 targetId 没有附件时它就不出现在结果里——响应里 每条 Attachment 都带 targetId，调用方按 id 分组后取不到即为空，不存在歧义。

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

参数

targetType（必填）
string —— 附件宿主对象类型。白名单之外的值返回 422（B-00053）；work_item 指向 type=bug 的工作项时服务端归一成 bug（B-00065，缺陷没有独立表，两个值指的是同一个对象）；comment 是评论附件（B-00080），targetId 为评论 uuid。
targetId（必填）
string —— 目标对象 id。支持逗号分隔的多值批量读（B-00090）：最多 100 个，超过返回 422；响应是扁平列表，每条 Attachment 自带 targetId，调用方据此分组（不另造嵌套结构，既有单值调用方的解析代码一行都不用改）。根治的是讨论区 N+1——此前每条评论各发一次 GET /attachments，一次开屏几十个并发请求，只能靠「滚进视口再取」缓解。limit 作用在每个 targetId 上，不是总条数。
limit
integer

响应字段 · 200

items（必填）
Attachment[]
items[].id（必填）
string
items[].targetType（必填）
enum；取值：requirement / work_item / bug / milestone / document / comment
items[].targetId（必填）
string
items[].fileName（必填）
string
items[].size（必填）
integer
items[].mimeType（必填）
string
items[].uploaderId（必填）
string
items[].createdAt（必填）
string

错误

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/attachments?targetType=…&targetId=…" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "items": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "targetType": "requirement",
      "targetId": "018f3c2e-0000-7000-8000-000000000000",
      "fileName": "示例标题",
      "size": 1,
      "mimeType": "示例文本",
      "uploaderId": "018f3c2e-0000-7000-8000-000000000000",
      "createdAt": "示例文本"
    }
  ]
}

合同真值：OpenAPI 3.1（0.1.0）。

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

Workflow 正在加载…