Overview

The workbenches.dev API is one HTTP API at https://api.workbenches.dev. Every resource route is under /v1. The same routes serve the wb CLI, the dashboard, the MCP server, and your integrations; what differs is the credential.

• Request and response bodies are JSON with snake_case fields.
• Direct resource URLs take UUIDs, except runs, sessions, and commands (see Identifiers).
• Actions that are not plain create, read, update, or delete are modelled as resources, such as POST /v1/searches and POST /v1/resolutions.

Two other surfaces sit outside /v1: the OCI image registry at images.workbenches.dev/v2 (see Images), and the OAuth routes at /oauth/* and /.well-known/* that MCP clients use (see Connect).

Authentication#

Every request carries one of two credentials.

Organization API keys#

curl https://api.workbenches.dev/v1/profile \
  -H "Authorization: Bearer wb_..."

A key belongs to one organization, holds one or more scopes, and always expires. Tokens are wb_ followed by 64 hex characters. A key always acts in its own organization.

Keys come from:

• the dashboard, where an owner or admin chooses scopes and an expiry of 1 to 365 days (default 90),
• wb login, which holds every scope except org:admin and lasts 90 days,
• an MCP client's OAuth sign-in, labelled MCP: <client name>, with the scopes granted (never org:admin) and 90 days.

A key stops working the moment its creator's membership in the organization ends. Basic authentication with a wb_ token as the password is also accepted, so standard OCI clients work with the image registry.

Browser sessions#

The dashboard signs in with Google and uses a session cookie. Some routes accept only a session: they serve the dashboard and are marked "Session" in this reference. A mutating request with a session cookie must come from the dashboard origin; a request with an Authorization header counts as a key call and skips that check.

Scopes#

Roles#

Organization members have a role: owner, admin, or member. In this reference:

• Key scope means a key of the target organization holding that scope.
• Session: member means a signed-in member of any role.
• Session: manager means an owner or admin.
• Manager creator means a key whose creating user is currently an owner or admin. A demoted creator's keys lose that power immediately.
• Open means anonymous callers are accepted, and a key or session widens what they see.

A stale or invalid key on an open read is treated as anonymous.

Errors#

Errors have one shape:

{
    "error": {
        "code": "not_found",
        "message": "Run not found",
        "request_id": "..."
    }
}

An internal Workbench, run, or other resource you cannot see is reported as not found. A run, session, or command that exists answers 403 to a caller outside its organization and to a key of its organization without the scope.

The /oauth/* routes use the OAuth shape instead: { "error", "error_description" }. The image registry uses the OCI error format.

Identifiers#

Selecting the organization#

A key always acts in its own organization. A browser session names the organization where a route needs one: with organization (a slug) on run, session, project, and worker routes, or organization_id (a UUID) on others. Each route lists which.

Pagination#

List routes that page take limit and cursor and return next (or next_cursor), the cursor for the following page, or null at the end. Pages are newest first.

Health#

Route index#