工作区 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`	原因
`401`	`workspace API key required`	该方法只接受工作区 API Key，却传了登录态或个人 Key
`401`	`invalid Bearer token`	凭据无效；例如对 `whoami` 使用了个人 Key 或登录态
`403`	`API key does not match workspace`	Key 属于别的工作区，和 URL 里的 slug 不一致
`403`	`API key revoked`	Key 已被吊销
`403`	`not the owner of this workspace`	用会话令牌调用了后端方法

按方法

方法	状态码	`detail`
`provisionMember`	`400`	请求体校验失败
`suspendMember`	`404`	`member not found`（成员不存在，或已经被停用）
`grantCredits`	`400`	`body/amount Number must be greater than 0`
	`402`	`insufficient owner wallet balance`
	`404`	`member not found`
`mintSession`	`400`	`body/ttl_seconds Number must be less than or equal to 86400`
	`403`	`member status is suspended`
	`404`	`member not found for sp_user_ref`
`getAgent`	`404`	`Agent not found in this workspace`
`sendSmsCode`	`400`	手机号格式不对
	`403`	`public SMS signup disabled`
	`404`	`workspace not found`
`verifySmsCode`	`401`	`invalid_or_expired_code`

行为约定

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

下一步

工作区 API 概览 — 获取 Key、完整接入流程
Workspace API REST 参考 — 字段定义与在线调试
错误处理 — SDK 的错误类型与重试建议

凭据矩阵​

方法签名​

错误码​

通用​

按方法​

行为约定​

下一步​

凭据矩阵

方法签名

错误码

通用

按方法

行为约定

下一步