API 参考
wb CLI 和您自己的应用调用的接口。本页在每次修改时由 Workbench 的 OpenAPI 规范自动生成,因此始终与服务器一致;各接口的说明文字直接取自规范,为英文。所有请求发往 https://desktop-api.wbench.io,并带上 Authorization: Bearer <token>(见在自己的应用中使用令牌)。所有错误都是 JSON 格式的 Error:category、message 和 details(见限制与错误)。
GET /v1/me
getMe: The signed-in user, their company and their other memberships.
调用者: 已登录的用户或个人令牌
响应
| 状态码 | 含义 |
|---|---|
| 200 | The caller. |
| 401 | Missing, expired or revoked token. |
响应字段
| 字段 | 类型 | 必填 |
|---|---|---|
onboarding | Onboarding | 否 |
user | User | 是 |
company | Company | 是 |
memberships | array of Membership | 是 |
region | string | 是 |
capabilities | array of string | 是 |
POST /v1/auth/cli-grants
createCliGrant: The person authorises wb login: a single-use grant the CLI redeems with cliLogin.
Called by Workbench's CLI sign-in page when the signed-in person presses Authorise, after it showed the requesting client (name) and the code the CLI printed. Answers a grant code, stored only as a hash, that lasts 5 minutes and is redeemed once by cliLogin with the PKCE verifier for codeChallenge and exactly this redirectUri. The grant code is not a bearer token. Same rules as createPersonalToken (403 details.reason pat_admins_only, cli_off or pat_needs_sign_in); 400 for a challenge or redirect that isn't valid. The code is answered once: a retry with the same Idempotency-Key answers the grant without code.
调用者: 已登录的用户或个人令牌
参数
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
Idempotency-Key | header | 是 | Client-chosen key, unique per logical mutation. A retry with the same key returns the original result. |
请求正文
| 字段 | 类型 | 必填 |
|---|---|---|
codeChallenge | string | 是 |
redirectUri | string | 是 |
name | string | 否 |
响应
| 状态码 | 含义 |
|---|---|
| 201 | The grant, answered once. |
| 400 | The request is malformed or fails validation. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
响应字段
| 字段 | 类型 | 必填 |
|---|---|---|
code | string | 否 |
expiresAt | string | 是 |
POST /v1/auth/cli-login
cliLogin: wb login: redeem the person's CLI grant for a personal access token.
The CLI's sign-in: the CLI opens Workbench's CLI sign-in page with its PKCE challenge, loopback redirect and name, and prints the code that page shows; the signed-in person checks it and presses Authorise (createCliGrant); the page sends the browser to the loopback redirect with the grant code, and the CLI sends it here with its verifier. The grant is used up by this call whatever the outcome; an identity provider's sign-in code is refused (401). Answers a personal access token (a user token that lasts 90 days, shown in this answer only), no session or refresh token. During the CLI trial only a company admin of a company whose cli switch is on gets one: otherwise 403 with details.reason pat_admins_only or cli_off. Every refusal is audited.
调用者: 任何人(用于登录)
请求正文
| 字段 | 类型 | 必填 |
|---|---|---|
code | string | 是 |
codeVerifier | string | 是 |
redirectUri | string | 是 |
响应
| 状态码 | 含义 |
|---|---|
| 200 | Signed in; the token, returned in this answer only. |
| 400 | The request is malformed or fails validation. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
响应字段
| 字段 | 类型 | 必填 |
|---|---|---|
id | string | 是 |
name | string | 是 |
createdAt | string | 是 |
expiresAt | string | 是 |
lastUsedAt | string or null | 是 |
revokedAt | string or null | 是 |
token | string | 否 |
user | User | 是 |
company | Company | 是 |
POST /v1/auth/logout
logout: End the current session and revoke its tokens.
logoutUrl is the identity provider's logout for this sign-in (WorkOS AuthKit sessions/logout, returning to the web sign-in page). The desktop opens it in the system browser, so the next sign-in asks for an account again instead of silently reusing AuthKit's session. Null when there is no provider session.
调用者: 已登录的用户或个人令牌
参数
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
Idempotency-Key | header | 是 | Client-chosen key, unique per logical mutation. A retry with the same key returns the original result. |
响应
| 状态码 | 含义 |
|---|---|
| 200 | Signed out. |
| 401 | Missing, expired or revoked token. |
| 413 | The request is larger than this operation holds to fingerprint and replay it (category unsupported_type_or_size; details.reason is body_too_large, details.maxBytes the limit). Nothing ran and the Idempotency-Key is still free. |
响应字段
| 字段 | 类型 | 必填 |
|---|---|---|
logoutUrl | string or null | 是 |
GET /v1/auth/personal-tokens
listPersonalTokens: The caller's own personal access tokens, newest first, without their values.
Live, expired and revoked. Needs a person's sign-in: a personal access token itself gets 403 (details.reason pat_needs_sign_in).
调用者: 已登录的用户或个人令牌
响应
| 状态码 | 含义 |
|---|---|
| 200 | The caller's tokens. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
响应字段
| 字段 | 类型 | 必填 |
|---|---|---|
items | array of PersonalToken | 是 |
POST /v1/auth/personal-tokens
createPersonalToken: Make a personal access token (the CLI's credential) from a person's sign-in.
A user token that acts as the caller, in their company, with their role, for 90 days; shown in this answer only and stored only as a hash. During the CLI trial only a company admin of a company whose cli switch is on may make one (403 details.reason pat_admins_only or cli_off), and a token stops working when either stops holding. A personal access token can't make another (pat_needs_sign_in). The value is answered once: a retry with the same Idempotency-Key answers the token it made without token.
调用者: 已登录的用户或个人令牌
参数
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
Idempotency-Key | header | 是 | Client-chosen key, unique per logical mutation. A retry with the same key returns the original result. |
请求正文
| 字段 | 类型 | 必填 |
|---|---|---|
name | string | 是 |
响应
| 状态码 | 含义 |
|---|---|
| 201 | The new token, its value in this answer only (a replay answers it without token). |
| 400 | The request is malformed or fails validation. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
响应字段
| 字段 | 类型 | 必填 |
|---|---|---|
id | string | 是 |
name | string | 是 |
createdAt | string | 是 |
expiresAt | string | 是 |
lastUsedAt | string or null | 是 |
revokedAt | string or null | 是 |
token | string | 否 |
DELETE /v1/auth/personal-tokens/{tokenId}
revokePersonalToken: Revoke one of the caller's own personal access tokens.
Allowed whatever the trial rule says now, so a token can always be ended. Another person's token is not_found. Needs a person's sign-in (pat_needs_sign_in); a token ends itself with logout.
调用者: 已登录的用户或个人令牌
参数
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
Idempotency-Key | header | 是 | Client-chosen key, unique per logical mutation. A retry with the same key returns the original result. |
tokenId | path | 是 |
响应
| 状态码 | 含义 |
|---|---|
| 204 | Done; no body. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
| 404 | No such record visible to the caller. |
| 413 | The request is larger than this operation holds to fingerprint and replay it (category unsupported_type_or_size; details.reason is body_too_large, details.maxBytes the limit). Nothing ran and the Idempotency-Key is still free. |
GET /v1/proxy/{connection}/{path}
proxyGet: GET the path from the connection with the company's key added (the caller's headers and any body go up as sent, less its own sign-in and cookies). A 2xx answer is the vendor's status, its named headers only (content type, cache control, Retry-After, request id, rate limits) and its body (decoded when the vendor compressed it), unless it holds the key in any form or can't be checked: then it is withheld (502). An event stream (text/event-stream) goes on an event at a time, each checked the same way first; at an event that holds the key or can't be checked, or when the vendor breaks off, the stream ends with one event: error whose data is {"type": "error", "error": <Error>}. A vendor's non-2xx answer (a redirect too) is never forwarded: it becomes an Error with the vendor's status (details.upstreamStatus), its error type and code when listed, and the reason (details.reasonZh in Chinese). A model provider's other paths (e.g. v1/models) take GET with the company's own key. Company admins of a company with the cli switch on (user tokens, or a personal access token); anyone else is refused with the reason. Another host or plain HTTP is refused before anything is sent.
调用者: 已登录的用户或个人令牌
参数
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
connection | path | 是 | The connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key. |
path | path | 是 | The rest of the address, slashes included: a path on the connection's host, or an absolute https:// URL on one of its allowed hosts (a pagination link). The query string is sent as given. |
响应
| 状态码 | 含义 |
|---|---|
| 200 | The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came). |
| 400 | The request is malformed or fails validation. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
| 404 | No such record visible to the caller. |
| 429 | Too many requests, or the server is busy: a limit on concurrent work, or no database connection in time (category rate_limited). Nothing is stored, so the same Idempotency-Key runs on a retry after Retry-After seconds. |
| 502 | The connection couldn't be reached, answered with a server error or redirect, its answer was over 8 MB, or it held the key or couldn't be checked for it (withheld whole). |
POST /v1/proxy/{connection}/{path}
proxyPost: POST the body (up to 8 MB, its content type kept) to the connection with the company's key added; as proxyGet otherwise. A model call goes to the model relay, which answers once the whole answer is checked. A larger body is refused (400) and logged. It changes no Workbench data and stores nothing of the request or answer, so it takes no Idempotency-Key: a retry is sent again.
调用者: 已登录的用户或个人令牌
参数
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
connection | path | 是 | The connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key. |
path | path | 是 | The rest of the address, slashes included: a path on the connection's host, or an absolute https:// URL on one of its allowed hosts (a pagination link). The query string is sent as given. |
响应
| 状态码 | 含义 |
|---|---|
| 200 | The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came). |
| 400 | The request is malformed or fails validation. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
| 404 | No such record visible to the caller. |
| 429 | Too many requests, or the server is busy: a limit on concurrent work, or no database connection in time (category rate_limited). Nothing is stored, so the same Idempotency-Key runs on a retry after Retry-After seconds. |
| 502 | The connection couldn't be reached, answered with a server error or redirect, its answer was over 8 MB, or it held the key or couldn't be checked for it (withheld whole). |
PUT /v1/proxy/{connection}/{path}
proxyPut: PUT to the connection with the company's key added (a body up to 8 MB, its content type kept); as proxyPost otherwise.
调用者: 已登录的用户或个人令牌
参数
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
connection | path | 是 | The connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key. |
path | path | 是 | The rest of the address, slashes included: a path on the connection's host, or an absolute https:// URL on one of its allowed hosts (a pagination link). The query string is sent as given. |
响应
| 状态码 | 含义 |
|---|---|
| 200 | The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came). |
| 400 | The request is malformed or fails validation. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
| 404 | No such record visible to the caller. |
| 429 | Too many requests, or the server is busy: a limit on concurrent work, or no database connection in time (category rate_limited). Nothing is stored, so the same Idempotency-Key runs on a retry after Retry-After seconds. |
| 502 | The connection couldn't be reached, answered with a server error or redirect, its answer was over 8 MB, or it held the key or couldn't be checked for it (withheld whole). |
PATCH /v1/proxy/{connection}/{path}
proxyPatch: PATCH to the connection with the company's key added (a body up to 8 MB, its content type kept); as proxyPost otherwise.
调用者: 已登录的用户或个人令牌
参数
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
connection | path | 是 | The connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key. |
path | path | 是 | The rest of the address, slashes included: a path on the connection's host, or an absolute https:// URL on one of its allowed hosts (a pagination link). The query string is sent as given. |
响应
| 状态码 | 含义 |
|---|---|
| 200 | The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came). |
| 400 | The request is malformed or fails validation. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
| 404 | No such record visible to the caller. |
| 429 | Too many requests, or the server is busy: a limit on concurrent work, or no database connection in time (category rate_limited). Nothing is stored, so the same Idempotency-Key runs on a retry after Retry-After seconds. |
| 502 | The connection couldn't be reached, answered with a server error or redirect, its answer was over 8 MB, or it held the key or couldn't be checked for it (withheld whole). |
DELETE /v1/proxy/{connection}/{path}
proxyDelete: DELETE to the connection with the company's key added (a body up to 8 MB, its content type kept); as proxyPost otherwise.
调用者: 已登录的用户或个人令牌
参数
| 名称 | 位置 | 必填 | 说明 |
|---|---|---|---|
connection | path | 是 | The connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key. |
path | path | 是 | The rest of the address, slashes included: a path on the connection's host, or an absolute https:// URL on one of its allowed hosts (a pagination link). The query string is sent as given. |
响应
| 状态码 | 含义 |
|---|---|
| 200 | The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came). |
| 400 | The request is malformed or fails validation. |
| 401 | Missing, expired or revoked token. |
| 403 | The token scope or the user's permissions refuse the operation. |
| 404 | No such record visible to the caller. |
| 429 | Too many requests, or the server is busy: a limit on concurrent work, or no database connection in time (category rate_limited). Nothing is stored, so the same Idempotency-Key runs on a retry after Retry-After seconds. |
| 502 | The connection couldn't be reached, answered with a server error or redirect, its answer was over 8 MB, or it held the key or couldn't be checked for it (withheld whole). |