Apps API · Members
Members: 8 个接口
GET /api/v1/me/provisioning-agents
List the caller's provisioning agents
权限(scope): agents:agent:read · 调用方式: appToken · operationId: list-my-provisioning-agents
Required app scope: agents:agent:read.
Returns the authenticated caller's own platform-created agents that are currently provisioning (agent_readiness == "provisioning"), plus any that JUST became ready within a short grace window, for a client's provisioning indicator. The grace inclusion gives a polling client one poll cycle observing the terminal "ready" state so it can render its completion frame; agents ready longer than the grace window, and agents not subject to the provisioning gate, are excluded. Self-scoped: the owner is always the caller, there is no path parameter and no client-supplied id, so the response needs no client-side storage and is consistent across browsers. Each item carries the agent's member_id (drill-down target), display_name, avatar_url, and agent_provisioning_stage (cosmetic; omitted when the runtime has not reported one — a just-ready agent reports "ready").
回包
200OK —application/json·DataResponseListMyProvisioningAgentSummaryBodydefaultError —application/problem+json·D8Error
GET /api/v1/members
List organization members
权限(scope): org:member:read · 调用方式: appToken · operationId: list-members
Required app scope: org:member:read.
Returns a paginated list of members in the specified organization. Supports filtering by kind (human/agent), status, and free-text search on display_name. online_status is aggregated from presence and the agent runtime (unknown if unavailable).
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
page |
query | integer (int32) | Page number (default: 1) | |
page_size |
query | integer (int32) | Items per page (default: 20, max: 100) | |
order_by |
query | string | Sort expression, e.g. created_at:desc | |
kind |
query | string | Filter by member type: human, agent, or system (omit for all non-system) | |
status |
query | string | Filter by status: active, suspended, or departed (omit for active only) | |
search |
query | string | Search by display name | |
include_system |
query | boolean | Include system members when no kind filter is set (default false) |
回包
200OK —application/json·PageListResponseMemberSummaryBodydefaultError —application/problem+json·D8Error
POST /api/v1/members/batch-display-info
Resolve display names for member IDs, including removed members
权限(scope): org:member:read · 调用方式: appToken · operationId: batch-member-display-info
Required app scope: org:member:read.
Display-only batch lookup of member name/kind/avatar/status by member ID within the caller's organization. Unlike GET /api/v1/members and GET /api/v1/members/{member_id}, members that have been removed still resolve here and are flagged with deleted=true, so historical data keyed by member ID (usage reports, credit ledgers) can be labelled with the name the member last went by. Ids not found in the caller's organization are omitted, not errors. Never use this response to decide whether a member is active or authorized. Any org member may call it. Response wrapped in standard envelope.
请求体
application/json · BatchMemberDisplayInfoRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
member_ids |
array of string | 是 | Member UUIDs to resolve. Every id must be a well-formed UUID (otherwise the whole batch is rejected with 422). Well-formed ids outside the caller's organization, or never known, are omitted from the result rather than failing the batch. |
回包
200OK —application/json·BatchMemberDisplayInfoResponseBodydefaultError —application/problem+json·D8Error
POST /api/v1/members/batch-remove
Remove several members at once
权限(scope): org:member:write · 调用方式: appToken · operationId: batch-remove-members
Required app scope: org:member:write.
Removes each member exactly as DELETE /api/v1/members/{member_id} does, one at a time. Humans and agents may be mixed in one request. Intended for the downgrade flow, where the admin is told to free N seats or N agent slots and should not have to confirm N dialogs.
Not atomic on purpose: a member who still owns an external agent, or who outranks the caller, fails on their own row while the rest are removed. Per-member outcomes are in results[] with HTTP 200. Each row's status is 204 when the member is gone, 202 when this is a platform Agent whose teardown the billing system accepted and has not finished. A 202 member is still listed and still holds its agent slot, so a plan change re-submitted immediately can still be refused for slot overflow; the removal completes on its own, and GET /members shows when it has. While any platform Agent in the org is mid-teardown like that, removing the org's remaining platform Agents is refused as a retryable conflict — the server cannot tell a batch's own earlier removals from a concurrent one. Shedding only the agents the downgrade actually needs stays clear of this; sweeping every Agent in the org does not. A 4xx means the request itself could not be executed — an empty list or more than 50 ids — and nothing was removed. Blank and duplicate ids are dropped before execution, counted in the summary, and absent from results[].
请求体
application/json · BatchRemoveMembersRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
member_ids |
array of string | 是 | Member UUIDs to remove |
回包
200OK —application/json·BatchRemoveMembersResponseBodydefaultError —application/problem+json·D8Error
DELETE /api/v1/members/{member_id}
Remove a member
权限(scope): org:member:write · 调用方式: appToken · operationId: remove-member
Required app scope: org:member:write.
Marks a member as departed while preserving the member record for history, audit, and conversation display. The member's identity is preserved — they can be re-invited. Requires org admin role. Cannot remove yourself.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Member UUID |
回包
204No ContentdefaultError —application/problem+json·D8Error
GET /api/v1/members/{member_id}
Get member details
权限(scope): org:member:read · 调用方式: appToken · operationId: get-member
Required app scope: org:member:read.
Returns detailed information about a specific member, including assigned role (single-role model) and agent ownership info.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
include_operational_state |
query | boolean | Aggregate operational state for this member only | |
member_id |
path | string (uuid) | 是 | Member UUID |
回包
200OK —application/json·GetMemberResponseBodydefaultError —application/problem+json·D8Error
PATCH /api/v1/members/{member_id}
Update member info
权限(scope): org:member:write · 调用方式: appToken · operationId: update-member
Required app scope: org:member:write.
Updates a member's org-level display_name, avatar_url, status, or role. avatar_url must be "" (restore the default; saved as null) or a URL returned by POST /api/v1/avatars/uploads/finalize in this organization, else 400 AVATAR_URL_NOT_ALLOWED; avatar_url (any value) on a human member other than the caller is 403 AVATAR_SELF_ONLY — a human changes their own avatar via PATCH /api/v1/me, and Agent avatars use PUT /api/v1/agents/{member_id}/avatar. Requests without avatar_url are unaffected. Status can be changed to active or suspended. To remove a member (departed), use DELETE instead. Role changes use role_id (single-role model). Returns the updated member with current role. Requires org admin role.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Member UUID |
请求体
application/json · UpdateMemberRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
avatar_url |
string | Avatar URL from POST /api/v1/avatars/uploads/finalize in this organization, or "" to restore the default avatar | |
display_name |
string | Change org-level member display name | |
role_id |
string (uuid) | Change member role (single-role model) | |
status |
string: active, suspended |
Change member status (active or suspended only; departed requires DELETE) |
回包
200OK —application/json·UpdateMemberResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/members/{member_id}/owned-agents
List agents owned by a member
权限(scope): org:member:read · 调用方式: appToken · operationId: list-owned-agents
Required app scope: org:member:read.
Returns the active agents owned by the specified member, for the owned-agents section of the member's avatar name card. Each item carries the agent's member_id (drill-down target), display_name, avatar_url, online_status (unknown if it cannot be determined), and model (active runtime model; omitted when the agent has not reported runtime metrics). Org-scoped: the caller must be a member of the owner's org, otherwise the member is reported as not found (404).
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
member_id |
path | string (uuid) | 是 | Owner member UUID |
回包
200OK —application/json·DataResponseListOwnedAgentSummaryBodydefaultError —application/problem+json·D8Error
