浏览器窗口标签
本文档说明浏览器窗口标签的云端接口，涵盖标签列表查询、创建、编辑、删除以及窗口-标签绑定关系的更新，包含请求格式、认证方式、字段别名和常见错误码。
标签 Local API 文档
查询标签列表
标题
查询标签列表
简要描述
分页查询窗口标签列表，支持按标签名称搜索。
请求URL
http://127.0.0.1:54345/browserTag/list
请求方式
POST
Header
| 参数 | 必填 | 示例 | 说明 |
|---|---|---|---|
Content-Type | 是 | application/json | 请求体格式 |
X-Cos-Local-Token | 是 | YOUR_LOCAL_TOKEN | 本机访问令牌，可在客户端「设置 - Local API」中查看 |
请求Body参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
page | 否 | number | 页码，默认 1 |
page_size | 否 | number | 每页数量，默认 10000，兼容 pageSize |
keyword / tag_name | 否 | string | 标签名称搜索，兼容 tagName / name |
成功返回示例
{
"code": 0,
"msg": "success",
"data": {
"list": [
{
"id": 3001,
"tag_name": "重点账号",
"tagName": "重点账号",
"color": "#409EFF",
"sort_num": 0
}
],
"total": 1
}
}
成功返回示例的参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
code | number | 0 表示请求成功 |
msg | string | 返回信息 |
data.list | array | 标签列表 |
data.list[].id | number/string | 标签 ID |
data.list[].tag_name | string | 标签名称 |
data.list[].tagName | string | 标签名称 |
data.list[].color | string | 标签颜色 |
data.list[].sort_num | number | 排序值 |
data.total | number | 总数量 |
备注
接口只监听本机 127.0.0.1，调用前请先打开并登录客户端。
创建标签
标题
创建标签
简要描述
创建一个新的窗口标签。
请求URL
http://127.0.0.1:54345/browserTag/create
请求方式
POST
Header
| 参数 | 必填 | 示例 | 说明 |
|---|---|---|---|
Content-Type | 是 | application/json | 请求体格式 |
X-Cos-Local-Token | 是 | YOUR_LOCAL_TOKEN | 本机访问令牌，可在客户端「设置 - Local API」中查看 |
请求Body参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
tag_name | 是 | string | 标签名称，兼容 tagName / name |
color / tag_color | 否 | string | 标签颜色，如 #409EFF |
sort_num | 否 | number | 排序值，默认 0，兼容 sortNum |
成功返回示例
{
"code": 0,
"msg": "success",
"data": {
"id": 3001,
"tag_name": "重点账号"
}
}
成功返回示例的参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
code | number | 0 表示请求成功 |
msg | string | 返回信息 |
data.id | number/string | 新增标签 ID |
data.tag_name / data.tagName | string | 标签名称 |
备注
标签颜色建议使用十六进制颜色值，例如 #409EFF。创建接口即时响应通常只返回 id 和标签名称，颜色和排序可通过 /browserTag/list 查询。
编辑标签
标题
编辑标签
简要描述
修改指定标签的名称、颜色或排序。
请求URL
http://127.0.0.1:54345/browserTag/update
请求方式
POST
Header
| 参数 | 必填 | 示例 | 说明 |
|---|---|---|---|
Content-Type | 是 | application/json | 请求体格式 |
X-Cos-Local-Token | 是 | YOUR_LOCAL_TOKEN | 本机访问令牌，可在客户端「设置 - Local API」中查看 |
请求Body参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
id | 是 | number/string | 标签 ID |
tag_name | 是 | string | 标签名称，兼容 tagName / name |
color / tag_color | 否 | string | 标签颜色 |
sort_num | 否 | number | 排序值，默认 0，兼容 sortNum |
成功返回示例
{
"code": 0,
"msg": "success",
"data": {
"id": 3001,
"tag_name": "重点账号"
}
}
成功返回示例的参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
code | number | 0 表示请求成功 |
msg | string | 返回信息 |
data.id | number/string | 标签 ID |
data.tag_name / data.tagName | string | 修改后的标签名称 |
备注
编辑标签前可先调用 /browserTag/list 获取标签 ID。编辑接口即时响应通常只返回 id 和标签名称，颜色和排序可通过 /browserTag/list 查询。
删除标签
标题
删除标签
简要描述
删除单个或多个窗口标签。
请求URL
http://127.0.0.1:54345/browserTag/delete
请求方式
POST
Header
| 参数 | 必填 | 示例 | 说明 |
|---|---|---|---|
Content-Type | 是 | application/json | 请求体格式 |
X-Cos-Local-Token | 是 | YOUR_LOCAL_TOKEN | 本机访问令牌，可在客户端「设置 - Local API」中查看 |
请求Body参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
id | 是，和 ids 二选一 | number/string | 单个标签 ID |
ids | 是，和 id 二选一 | array/string | 多个标签 ID |
成功返回示例
{
"code": 0,
"msg": "success",
"data": {
"ids": [3001, 3002],
"results": [
{
"code": 0,
"msg": "success"
}
]
}
}
成功返回示例的参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
code | number | 0 表示请求成功 |
msg | string | 返回信息 |
data.ids | array | 已删除的标签 ID |
data.results | array | 每个标签删除请求的服务端结果 |
data.results[].code | number | 单个删除结果状态码 |
data.results[].msg | string | 单个删除结果信息 |
备注
删除多个标签时，本地 API 会逐个调用服务端删除接口；任意一个删除失败会直接返回失败结果。
更新窗口标签关系
标题
更新窗口标签关系
简要描述
为指定窗口覆盖、新增或移除标签绑定关系。
请求URL
http://127.0.0.1:54345/browserTag/updateRelation
请求方式
POST
Header
| 参数 | 必填 | 示例 | 说明 |
|---|---|---|---|
Content-Type | 是 | application/json | 请求体格式 |
X-Cos-Local-Token | 是 | YOUR_LOCAL_TOKEN | 本机访问令牌，可在客户端「设置 - Local API」中查看 |
请求Body参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
uuid | 是，和 browser_id 二选一 | string | 窗口 UUID，也可传 config_uuid。从 /browser/list 返回的 uuid 获取 |
browser_id / id | 是，和 uuid 二选一 | number/string | 窗口数字 ID，兼容 browserId。建议优先传 uuid |
tag_ids | 否 | array/string | 推荐用法：直接覆盖窗口标签 ID 列表，空数组表示清空。兼容 tagIds |
action | 否 | string | 传 bind 表示把 tag_ids 增量绑定，传 unbind 表示把 tag_ids 增量解绑 |
add_tag_ids | 否 | array/string | 兼容旧用法：要新增绑定的标签 ID，兼容 addTagIds |
remove_tag_ids | 否 | array/string | 兼容旧用法：要移除绑定的标签 ID，兼容 removeTagIds |
current_platform | 否 | string | 当前客户端平台，默认当前客户端平台，兼容 currentPlatform |
成功返回示例
{
"code": 0,
"msg": "success",
"data": {
"id": 10001,
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tag_ids": [3001, 3003],
"tagIds": [3001, 3003]
}
}
成功返回示例的参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
code | number | 0 表示请求成功 |
msg | string | 返回信息 |
data.id | number/string | 窗口 ID |
data.uuid | string | 窗口 UUID |
data.tag_ids / data.tagIds | array | 更新后的标签 ID 列表 |
备注
调用前可先通过 /browser/list 获取窗口 UUID，通过 /browserTag/list 获取标签 ID。直接传 tag_ids 时会覆盖原标签关系；传 action: "bind" / "unbind" 或旧字段 addTagIds / removeTagIds 时按增量方式处理。