群组 API - Qoder CN

群组 API 用于将成员组织起来，以便进行功能权限管理。一个成员可加入多个群组。群组成员关系不会改变成员的角色、席位、个人用量上限、计费组或 Credits 归属。

适用版本：Enterprise。组织需已开通群组能力。

前置条件

请求头携带 Authorization: Bearer <api_key>。
带 JSON 请求体时，发送 Content-Type: application/json。
organization_id 必须是 API Key 所属组织。
userIds 请求字段使用用户 ID，而不是组织成员 ID。可从成员 API返回的 userId 字段获取。

群组类型

请以 source 判断群组是否可写。source: "manual" 表示由 Qoder 手动管理，可通过这些 API 更新、删除和维护成员。其他来源在 OpenAPI 中均为只读，并返回 isManaged: true；例如 SCIM 群组返回 source: "scim"。只读群组应在来源系统中管理。

数据模型

Group

字段	类型	说明
`id`	string	群组 ID
`organizationId`	string	组织 ID
`displayName`	string	群组名称
`description`	string	描述；为空时省略
`source`	string	群组来源，例如 `manual` 或 `scim`
`externalId`	string	来源系统中的群组 ID；为空时省略
`syncType`	string	同步类型，例如 `scim`；为空时省略
`isManaged`	boolean	成员关系是否由外部来源托管
`creatorId`	string	创建人用户 ID；不可用时省略
`createdAt`	string	创建时间，ISO 8601 格式；不可用时省略
`updatedAt`	string	最后更新时间，ISO 8601 格式；不可用时省略
`memberCount`	integer	当前群组成员数

群组成员

字段	类型	说明
`id`	string	组织成员 ID
`userId`	string	用户 ID；添加或移除群组成员时使用该值
`name`	string	成员名称
`email`	string	成员邮箱；不可用时省略
`status`	string	组织成员状态，例如 `ENABLED` 或 `DISABLED`
`joinedAt`	string	用户加入组织的时间；不可用时省略
`usageLimit`	object	当前个人用量上限；不可用时省略
`usageLimit.quotaKey`	string	配额标识
`usageLimit.limitValue`	number	上限值；`-1` 表示不限额
`usageLimit.usedValue`	number	当前统计期间已用量
`usageLimit.resetCycle`	string	重置周期；不可用时省略
`usageLimit.isActive`	boolean	该上限是否生效
`usageLimit.lastResetAt`	string	上次重置时间；不可用时省略
`usageLimit.nextResetAt`	string	下次重置时间；不可用时省略

群组成员对象不会返回成员角色或计费组。如需这些字段，请使用成员 API。

API 参考

列出群组

GET /v1/organizations/{organization_id}/groups

查询参数	类型	必填	说明
`source`	string	否	精确匹配来源，例如 `manual` 或 `scim`
`externalId`	string	否	精确匹配外部群组 ID
`syncType`	string	否	精确匹配同步类型
`userId`	string	否	仅返回包含该用户 UUID 的群组
`keyword`	string	否	在群组名称或描述中进行不区分大小写的匹配
`maxResults`	integer	否	每页数量，默认 20，最大 100
`nextToken`	string	否	上一页响应返回的游标

成功响应（200 OK）

{
  "groups": [
    {
      "id": "1c8f3ee2-b970-4b61-93f9-f8be080ae945",
      "organizationId": "org_xxx",
      "displayName": "Platform Team",
      "description": "Platform maintainers",
      "source": "manual",
      "isManaged": false,
      "creatorId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-08-01T08:00:00Z",
      "updatedAt": "2026-08-01T08:00:00Z",
      "memberCount": 2
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

最后一页会省略 nextToken。

创建群组

POST /v1/organizations/{organization_id}/groups 创建手动管理的群组。displayName 会去除首尾空格，且不能为空。群组名不得与已有的有效手动群组冲突。省略 userIds 或传空数组可创建无成员群组；重复用户 ID 会自动去重。如任一 ID 无效或不是当前组织成员，请求会失败且不会创建群组。

请求体

{
  "displayName": "Platform Team",
  "description": "Platform maintainers",
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

字段	类型	必填	说明
`displayName`	string	是	群组名称
`description`	string	否	群组描述
`userIds`	string 数组	否	创建群组时同时加入的用户 UUID

成功时返回创建后的 Group，状态码为 201 Created。

获取群组

GET /v1/organizations/{organization_id}/groups/{group_id} 成功时返回对应的 Group，状态码为 200 OK。

更新群组

PUT /v1/organizations/{organization_id}/groups/{group_id} 仅手动管理的群组可更新。未传字段保持不变；传入空的 description 可清空描述。

请求体

{
  "displayName": "Platform Engineering",
  "description": ""
}

字段	类型	必填	说明
`displayName`	string	否	新群组名称；去除首尾空格后不能为空
`description`	string	否	新描述；空字符串表示清空

成功时返回更新后的 Group，状态码为 200 OK。

删除群组

DELETE /v1/organizations/{organization_id}/groups/{group_id} 仅手动管理的群组可删除。删除群组会删除其成员关系以及绑定到该群组的访问策略，但不会删除组织成员，也不会改变成员的计费组、个人用量上限或历史用量。成功时返回 200 OK：

{}

列出群组成员

GET /v1/organizations/{organization_id}/groups/{group_id}/members

查询参数	类型	必填	说明
`keyword`	string	否	在成员名称或邮箱中进行不区分大小写的匹配
`maxResults`	integer	否	每页数量，默认 20，最大 100
`nextToken`	string	否	上一页响应返回的游标

成功响应（200 OK）

{
  "members": [
    {
      "id": "member_abc123",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Alice",
      "email": "alice@example.com",
      "status": "ENABLED",
      "joinedAt": "2026-06-01T08:00:00Z",
      "usageLimit": {
        "quotaKey": "big_model_credits",
        "limitValue": 5000,
        "usedValue": 1250,
        "resetCycle": "monthly",
        "isActive": true
      }
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

最后一页会省略 nextToken。

添加群组成员

POST /v1/organizations/{organization_id}/groups/{group_id}/members 向手动管理的群组添加一个或多个组织用户。已有成员关系不会重复创建。

请求体

{
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

userIds 必填，且至少包含一个非空用户 ID。重复或已加入的用户 ID 不会产生重复成员关系。系统会在变更成员关系前校验整批 ID；如任一 ID 格式错误或不是当前组织成员，请求返回 400 BadRequest，且不会添加任何成员关系。 200 OK 响应最多包含当前群组的前 20 名成员，且不包含分页字段；如需完整列表，请调用列出群组成员。

{
  "members": [
    {
      "id": "member_abc123",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Alice",
      "email": "alice@example.com",
      "status": "ENABLED",
      "joinedAt": "2026-06-01T08:00:00Z"
    }
  ]
}

移除群组成员

DELETE /v1/organizations/{organization_id}/groups/{group_id}/members 从手动管理的群组中删除一个或多个成员关系，不会将用户从组织中删除。

请求体

{
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

userIds 必填，且至少包含一个非空用户 ID。该接口在 DELETE 请求中携带 JSON 请求体，请确保 HTTP 客户端和代理不会丢弃请求体。如任一 ID 格式错误，请求返回 400 BadRequest，且不会移除任何成员关系。格式有效但不是组织成员或不在该群组中的用户 ID 不会产生影响；同一请求中其他匹配的成员关系仍会被移除。成功时返回 200 OK：

{}

错误

错误响应使用 OpenAPI 约定与规范中定义的通用结构。

HTTP 状态码	错误码	常见原因
400	`BadRequest`	请求格式错误、ID 或游标无效、必填字段为空
400	`OrganizationGroupSCIMReadOnly`	尝试修改同步或外部托管群组
401	`Unauthorized`	API Key 缺失或无效
403	`Forbidden`	API Key 不属于目标组织
403	`OrganizationPlanCapabilityForbidden`	组织未开通群组能力
404	`NotFound`	群组或成员不存在
409	`AlreadyExists`	已存在同名的有效手动群组

​前置条件

​群组类型

​数据模型

​Group

​群组成员

​API 参考

​列出群组

​成功响应（200 OK）

​创建群组

​请求体

​获取群组

​更新群组

​请求体

​删除群组

​列出群组成员

​成功响应（200 OK）

​添加群组成员

​请求体

​移除群组成员

​请求体

​错误

前置条件

群组类型

数据模型

Group

群组成员

API 参考

列出群组

成功响应（200 OK）

创建群组

请求体

获取群组

更新群组

请求体

删除群组

列出群组成员

成功响应（200 OK）

添加群组成员

请求体

移除群组成员

请求体

错误