完整文档索引见 llms.txt。在页面 URL 后附加 .md 即可获取 Markdown 版本；本页的 Markdown 版本可在此获取。

角色

角色相关操作

获取所有角色

按类型（全局和项目）分组返回所有角色。设置 `withUsageCount` 可包含使用各角色的用户数量和项目数量。

GET/roles

请求参数

参数	位置	类型	必填	说明
withUsageCount	query	string	否	默认值："false" 可选值：true, false

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问

响应结构：200 · application/json

字段	类型	必填	说明
global	array	是	展开字段 字段 类型 必填 说明 global.[]slug string 是 global.[]displayName string 是 global.[]description string 是 global.[]systemRole boolean 是 global.[]roleType string 是 可选值：global global.[]scopes array 是 global.[]createdAt string 是 global.[]updatedAt string 是 global.[]licensed boolean 是 global.[]usedByUsers number 否 global.[]usedByProjects number 否
project	array	是	展开字段 字段 类型 必填 说明 project.[]slug string 是 project.[]displayName string 是 project.[]description string 是 project.[]systemRole boolean 是 project.[]roleType string 是 可选值：project project.[]scopes array 是 project.[]createdAt string 是 project.[]updatedAt string 是 project.[]licensed boolean 是 project.[]usedByUsers number 否 project.[]usedByProjects number 否

下载完整 OpenAPI 定义（JSON）

创建自定义角色

创建自定义角色。将 `roleType` 设为 `global` 可创建实例级角色，设为 `project` 可创建项目角色。

POST/roles

请求参数

参数	位置	类型	必填	说明
Idempotency-Key	header	string	否	此 POST 请求的安全重试键。使用 1 到 128 个可见 ASCII 字符。相同的键配合相同的请求，会返回首次成功的响应。使用此键发送不同请求时返回 422。首次请求仍在处理时重试，会返回 409。

请求体

application/json

字段	类型	必填	说明
displayName	string	是
description	string	否
roleType	string	是	可选值：project, global
scopes	array	是

响应

状态码	说明
201	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
409	冲突
415	不支持的媒体类型。
422	无法处理的实体

响应结构：201 · application/json

字段	类型	必填	说明
slug	string	是
displayName	string	是
description	string	是
systemRole	boolean	是
roleType	string	是	可选值：project, global
scopes	array	是
createdAt	string	是
updatedAt	string	是

下载完整 OpenAPI 定义（JSON）

获取角色

返回单个角色及其作用域。设置 `withUsageCount` 可包含使用该角色的用户数量和项目数量。

GET/roles/{roleSlug}

请求参数

参数	位置	类型	必填	说明
roleSlug	path	string	是	角色的 slug。
withUsageCount	query	string	否	默认值："false" 可选值：true, false

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。

响应结构：200 · application/json

字段	类型	必填	说明
slug	string	是
displayName	string	是
description	string	是
systemRole	boolean	是
roleType	string	是	可选值：project, global
scopes	array	是
createdAt	string	是
updatedAt	string	是
licensed	boolean	是
usedByUsers	number	否
usedByProjects	number	否

下载完整 OpenAPI 定义（JSON）

更新自定义角色

替换自定义角色的显示名称、说明和作用域。系统角色不能更新。

PUT/roles/{roleSlug}

请求参数

参数	位置	类型	必填	说明
roleSlug	path	string	是	角色的 slug。

请求体

application/json

字段	类型	必填	说明
displayName	string	是
description	string	是
scopes	array	是

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。
415	不支持的媒体类型。

响应结构：200 · application/json

字段	类型	必填	说明
slug	string	是
displayName	string	是
description	string	是
systemRole	boolean	是
roleType	string	是	可选值：project, global
scopes	array	是
createdAt	string	是
updatedAt	string	是

下载完整 OpenAPI 定义（JSON）

删除自定义角色

删除自定义角色。系统角色不能删除。已分配用户的角色不能删除，除非先设置 `reassignRoleSlug`，将这些用户转移到其他角色。

DELETE/roles/{roleSlug}

请求参数

参数	位置	类型	必填	说明
roleSlug	path	string	是	角色的 slug。
reassignRoleSlug	query		否

响应

状态码	说明
200	操作成功。
400	请求无效，或提供的数据格式错误。
401	未授权
403	禁止访问
404	未找到指定资源。

响应结构：200 · application/json

字段	类型	必填	说明
slug	string	是
displayName	string	是
description	string	是
systemRole	boolean	是
roleType	string	是	可选值：project, global
scopes	array	是
createdAt	string	是
updatedAt	string	是

下载完整 OpenAPI 定义（JSON）