慧企星助开放平台文档

GET /api/openplatform/labels

获取当前企业可用标签列表。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403。

字段	类型	必填	说明
`keyword`	string	否	标签名称关键词，最长 50 个字符。只返回名称包含该关键词的团队标签与个人标签；不传或传空白时返回全量，与 MCP 工具 `label_list` 同口径。超过 50 个字符返回 `400`。
`page`	int	否	页码，从 1 开始，默认 1。
`pageSize`	int	否	每页条数，默认 20，取值范围 1 到 100。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "紧急",
      "color": "#ff4d4f",
      "groupId": "c3d4e5f6-a789-01ba-cdef-234567890123",
      "groupName": "优先级",
      "type": 0
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "我的标签",
      "color": "#515a6e",
      "groupId": "00000000-0000-0000-0000-000000000001",
      "groupName": "个人标签",
      "type": 1
    }
    ]
  }
}

响应字段

字段	类型	说明
`data.total`	long	当前员工可见标签总数。
`data.page`	int	当前页码，从 1 开始。
`data.pageSize`	int	当前页返回条数上限，范围为 1 到 100。
`data.items`	Label[]	当前页标签数据。
`id`	guid	标签标识，可用于任务、便签等资源关联。
`name`	string	标签名称。
`color`	string	标签颜色值（只读），例如 `#ff4d4f`。颜色属于标签组的属性：团队标签取所属组色，个人标签用平台默认色；标签写入接口不接收该字段，要到工作台改组色（改组色级联刷新组内标签）。
`groupId`	guid	所属分组标识。团队标签是 `label_group` 的真实分组 Id，可直接用于新增团队标签时指定分组；个人标签返回只读聚合键 `00000000-0000-0000-0000-000000000001`，它不是真实分组行，回传做写入会返回 `400` 并说明正确做法（新增个人标签请传 `type=personal` 并省略 `groupId`），该键仅用于按分组聚合与判别。
`groupName`	string	所属分组名称；个人标签固定为 `个人标签`。
`type`	int	标签类型：`0` 团队标签（企业内共享）、`1` 个人标签（仅本人可见）。

POST /api/openplatform/labels

新增标签。团队标签（type=team）需要操作人具备企业标签维护权限且必须指定分组；个人标签（type=personal）仅操作人本人可见。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403。写操作需 labels.write 权限。

字段	类型	必填	说明
`name`	string	是	标签名称，同企业内不允许重名。
`type`	string	否	标签类型（字符串枚举）：`team` 团队标签（默认）、`personal` 个人标签。
`groupId`	guid	否	标签分组 Id；`type=team` 时必填。
`color`	string	不接受	创建标签不设颜色：团队标签继承所属标签组的颜色，个人标签使用平台默认色。传入非空 `color` 返回 `400` 并说明原因，不会被静默忽略；要改颜色请到工作台修改标签组颜色，组内标签级联刷新。
`remark`	string	否	备注。

请求示例：

{
  "name": "慧企星助AI助理",
  "type": "team",
  "groupId": "0c4e5a71-6f5e-4c22-9e2b-3d1a0f8b7c01"
}

响应示例：

{
  "statusCode": 100,
  "msg": "保存成功！",
  "data": { "id": "2f6e8a10-3c4b-4d5e-9f80-a1b2c3d4e5f6" }
}

PATCH /api/openplatform/labels/{id}

修改标签名称。颜色随所属标签组、不作为标签字段修改；本接口只分发 update 动作（此前误用工作台内部名 edit 落到不支持分支，已修正）。

必填请求头：必须提供 X-Employee-Virtual-Id。写操作需 labels.write 权限。

字段	类型	必填	说明
`name`	string	是	标签名称。
`color`	string	不接受	修改标签只改名称，颜色随所属标签组；传入非空 `color` 返回 `400`。

DELETE /api/openplatform/labels/{id}

删除标签。标签已被任务、便签等业务使用时是否允许删除由平台业务校验返回结果。写操作需 labels.write 权限，并需提供 X-Employee-Virtual-Id。

标签接口

响应字段