跳到主要内容

工作区 API 方法参考

本页是工作区 API 的速查表:每个 SDK 方法对应的 HTTP 路由、接受的凭据,以及会返回的错误。 下面的状态码和错误信息都来自对线上接口的实际调用。字段级的请求 / 响应定义与在线调试见 Workspace API REST 参考。

所有路由都在 https://api.openhex.tech/api/v2 之下,凭据通过 Authorization: Bearer <token> 传递。错误响应体为 { "detail": "…" },SDK 把它抛成 ApiError(err.status 为状态码,err.message 为 detail)。

凭据矩阵​

方法HTTP工作区 API Key (sk_…)工作区所有者登录态会话令牌无凭据
whoami()GET /workspaces/whoami✅———
provisionMember(body)POST /workspaces/{slug}/members✅———
listMembers()GET /workspaces/{slug}/members✅✅——
suspendMember(memberId)DELETE /workspaces/{slug}/members/{memberId}✅———
grantCredits(memberId, body)POST /workspaces/{slug}/members/{memberId}/credits✅✅——
mintSession(body)POST /workspaces/{slug}/sessions✅———
startVisitorSession(body)依次调用 provisionMember 与 mintSession✅———
listAgents()GET /workspaces/{slug}/agents✅✅——
getAgent(agentId)GET /workspaces/{slug}/agents/{agentId}✅✅——
sendSmsCode(body)POST /workspaces/{slug}/sms/send———✅
verifySmsCode(body)POST /workspaces/{slug}/sms/verify———✅

表中的方法都在 client.workspace(slug) 句柄上;whoami 在 client.workspaces 上。使用 client.workspaces.<方法>(slug, …) 时把 slug 作为第一个参数。所有方法最后都接受一个可选的 { signal }。

方法签名​

whoami(opts?): Promise<{ workspace_id; slug; display_name; status; api_key_id }>

provisionMember({ sp_user_ref, display_name? }, opts?)
: Promise<{ member_id; billing_account_id; created }>

listMembers(opts?)
: Promise<{ members: { user_id; billing_account_id; sp_user_ref; status; joined_at; balance }[] }>

suspendMember(memberId, opts?): Promise<void>

grantCredits(memberId, { amount, idempotency_key }, opts?)
: Promise<{ balance; purchase_id; idempotent }>

mintSession({ sp_user_ref, ttl_seconds? }, opts?)
: Promise<{ token; user_id; expires_at }>

startVisitorSession({ sp_user_ref, display_name?, ttl_seconds? }, opts?)
: Promise<{ token; user_id; expires_at }>

listAgents(opts?)
: Promise<{ scope: 'workspace'; workspace_id; agents: WorkspaceAgent[] }>

getAgent(agentId, opts?)
: Promise<{ scope: 'workspace'; workspace_id; agent: WorkspaceAgent }>

sendSmsCode({ phone }, opts?): Promise<void>

verifySmsCode({ phone, code }, opts?): Promise<{ token; user_id; expires_at }>

对应的 TypeScript 类型(WorkspaceWhoami、WorkspaceMember、ProvisionMemberResponse、GrantCreditsResponse、SessionTokenResponse、WorkspaceAgent 等)都从包根导出。

错误码​

通用​

状态码detail原因
401workspace API key required该方法只接受工作区 API Key,却传了登录态或个人 Key
401invalid Bearer token凭据无效;例如对 whoami 使用了个人 Key 或登录态
403API key does not match workspaceKey 属于别的工作区,和 URL 里的 slug 不一致
403API key revokedKey 已被吊销
403not the owner of this workspace用会话令牌调用了后端方法

按方法​

方法状态码detail
provisionMember400请求体校验失败
suspendMember404member not found(成员不存在,或已经被停用)
grantCredits400body/amount Number must be greater than 0
402insufficient owner wallet balance
404member not found
mintSession400body/ttl_seconds Number must be less than or equal to 86400
403member status is suspended
404member not found for sp_user_ref
getAgent404Agent not found in this workspace
sendSmsCode400手机号格式不对
403public SMS signup disabled
404workspace not found
verifySmsCode401invalid_or_expired_code

行为约定​

方法约定
provisionMember按 sp_user_ref 幂等;再次调用返回同一成员,created: false;不会恢复已停用的成员
suspendMember不幂等;已停用的成员再次调用返回 404;不吊销已签发的令牌
grantCredits按 idempotency_key 幂等;重放返回原结果,idempotent: true
mintSessionttl_seconds 默认 3600,最大 86400
listMembers / listAgents单次最多 500 条,无分页

下一步​