Workbench developer docs中文

API reference

The operations the wb CLI and your own apps call, generated from Workbench's OpenAPI specification on every change, so this page always matches the server. Every request goes to https://desktop-api.wbench.io with Authorization: Bearer <token> (see Using the token in your own app). Every error is a JSON Error: category, message, and details (see Limits and errors).

GET /v1/me

getMe: The signed-in user, their company and their other memberships.

Who may call: a signed-in person or a personal token

Answers

StatusMeaning
200The caller.
401Missing, expired or revoked token.

Answer fields

FieldTypeRequired
onboardingOnboardingno
userUseryes
companyCompanyyes
membershipsarray of Membershipyes
regionstringyes
capabilitiesarray of stringyes

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.

Who may call: a signed-in person or a personal token

Parameters

NameInRequiredDescription
Idempotency-KeyheaderyesClient-chosen key, unique per logical mutation. A retry with the same key returns the original result.

Request body

FieldTypeRequired
codeChallengestringyes
redirectUristringyes
namestringno

Answers

StatusMeaning
201The grant, answered once.
400The request is malformed or fails validation.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.

Answer fields

FieldTypeRequired
codestringno
expiresAtstringyes

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.

Who may call: anyone (it signs you in)

Request body

FieldTypeRequired
codestringyes
codeVerifierstringyes
redirectUristringyes

Answers

StatusMeaning
200Signed in; the token, returned in this answer only.
400The request is malformed or fails validation.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.

Answer fields

FieldTypeRequired
idstringyes
namestringyes
createdAtstringyes
expiresAtstringyes
lastUsedAtstring or nullyes
revokedAtstring or nullyes
tokenstringno
userUseryes
companyCompanyyes

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.

Who may call: a signed-in person or a personal token

Parameters

NameInRequiredDescription
Idempotency-KeyheaderyesClient-chosen key, unique per logical mutation. A retry with the same key returns the original result.

Answers

StatusMeaning
200Signed out.
401Missing, expired or revoked token.
413The 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.

Answer fields

FieldTypeRequired
logoutUrlstring or nullyes

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).

Who may call: a signed-in person or a personal token

Answers

StatusMeaning
200The caller's tokens.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.

Answer fields

FieldTypeRequired
itemsarray of PersonalTokenyes

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.

Who may call: a signed-in person or a personal token

Parameters

NameInRequiredDescription
Idempotency-KeyheaderyesClient-chosen key, unique per logical mutation. A retry with the same key returns the original result.

Request body

FieldTypeRequired
namestringyes

Answers

StatusMeaning
201The new token, its value in this answer only (a replay answers it without token).
400The request is malformed or fails validation.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.

Answer fields

FieldTypeRequired
idstringyes
namestringyes
createdAtstringyes
expiresAtstringyes
lastUsedAtstring or nullyes
revokedAtstring or nullyes
tokenstringno

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.

Who may call: a signed-in person or a personal token

Parameters

NameInRequiredDescription
Idempotency-KeyheaderyesClient-chosen key, unique per logical mutation. A retry with the same key returns the original result.
tokenIdpathyes

Answers

StatusMeaning
204Done; no body.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.
404No such record visible to the caller.
413The 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.

Who may call: a signed-in person or a personal token

Parameters

NameInRequiredDescription
connectionpathyesThe connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key.
pathpathyesThe 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.

Answers

StatusMeaning
200The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came).
400The request is malformed or fails validation.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.
404No such record visible to the caller.
429Too 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.
502The 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.

Who may call: a signed-in person or a personal token

Parameters

NameInRequiredDescription
connectionpathyesThe connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key.
pathpathyesThe 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.

Answers

StatusMeaning
200The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came).
400The request is malformed or fails validation.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.
404No such record visible to the caller.
429Too 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.
502The 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.

Who may call: a signed-in person or a personal token

Parameters

NameInRequiredDescription
connectionpathyesThe connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key.
pathpathyesThe 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.

Answers

StatusMeaning
200The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came).
400The request is malformed or fails validation.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.
404No such record visible to the caller.
429Too 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.
502The 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.

Who may call: a signed-in person or a personal token

Parameters

NameInRequiredDescription
connectionpathyesThe connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key.
pathpathyesThe 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.

Answers

StatusMeaning
200The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came).
400The request is malformed or fails validation.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.
404No such record visible to the caller.
429Too 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.
502The 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.

Who may call: a signed-in person or a personal token

Parameters

NameInRequiredDescription
connectionpathyesThe connection whose Company key is used: anthropic, openai, digikey, mouser, trustedparts, serper, mrpeasy, close, gitlab, render. Available only when the company has the key.
pathpathyesThe 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.

Answers

StatusMeaning
200The vendor's answer: its status and body as sent (JSON for the listed connections; another content type passes as it came).
400The request is malformed or fails validation.
401Missing, expired or revoked token.
403The token scope or the user's permissions refuse the operation.
404No such record visible to the caller.
429Too 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.
502The 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).