Connect to a hosted workbench API

Goal: Call a hosted workbench's tools from any HTTP client — curl, Postman, backend integrations, browser fetch — through a stable REST surface.

---

Prerequisites

• A hosted workbench with APIMode enabled — see Install a workbench from source.
• A Bearer JWT with the Workspace.Workbench.Host access right.
• Any HTTP client (curl, Postman, fetch, requests, backend HTTP library, etc.).

---

Your workspace URL

Once a workbench is hosted with APIMode, its base URL is:

<your-workspace-url>/oi-api/workbenches/{APISlug}/API

Every tool method is auto-exposed as a POST endpoint at:

<your-workspace-url>/oi-api/workbenches/{APISlug}/API/{tool}/{method}

For example, the api-sample workbench (from fathym-deno/api-workbench) declares two tools — Hello with a Greet method and Echo with an Echo method. On Open Industrial its routes are:

• POST https://www.openindustrial.co/oi-api/workbenches/api-sample/API/hello/greet
• POST https://www.openindustrial.co/oi-api/workbenches/api-sample/API/echo/echo

Method names lowercase in the URL; the workbench author never declares route paths. The path IS the tool + method they declared under .Tools({...}).

---

Option 1: curl (or any HTTP client)

The primary consumption path. One POST per tool method:

curl -X POST \
  <your-workspace-url>/oi-api/workbenches/api-sample/API/hello/greet \
  -H "Authorization: Bearer <your-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"arg0": "world"}'

# → "Hello from api-workbench, world!"

Method arguments arrive under arg0, arg1, ... (positional) or as named keys if the tool's schema declares a single object argument. The workbench author's Zod input schema defines which one — check the OpenAPI catalog (Option 2) or the workbench's source for the shape.

Same call from a backend integration (Deno/fetch):

const res = await fetch(
  '<your-workspace-url>/oi-api/workbenches/api-sample/API/hello/greet',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwt}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ arg0: 'world' }),
  },
);
const greeting = await res.json();

---

Option 2: OpenAPI catalog

APIMode auto-generates an OpenAPI 3.x catalog at:

GET <your-workspace-url>/oi-api/workbenches/{APISlug}/API/openapi.json

Feed it to any OpenAPI-aware tool for typed client generation, schema-driven testing, or interactive exploration:

# Get the catalog
curl <your-workspace-url>/oi-api/workbenches/api-sample/API/openapi.json | jq .

# Generate a typed TypeScript client
npx @hey-api/openapi-ts \
  --input <your-workspace-url>/oi-api/workbenches/api-sample/API/openapi.json \
  --output ./src/generated

The workspace itself reads the same catalog to render per-workbench route lists in the API Explorer (see below).

---

Option 3: Postman / browser tools

Point Postman at the OpenAPI catalog URL — Postman imports the routes as a collection you can explore, edit, and share. Add Authorization: Bearer <your-jwt> at the collection level and every request carries it.

Same pattern works for any REST-testing tool that speaks OpenAPI (Insomnia, Bruno, HTTPie's httpie generate, etc.).

---

Discovery in the workspace

The workspace API Explorer shows every API-enabled workbench with its full route catalog + copy-paste curl examples per route. Open API Explorer → select Hosted Workbench APIs in the API Type dropdown → each API-enabled workbench appears as a card with:

• Base URL (copyable)
• Every route with a colored method pill (GET/POST/PUT/PATCH/DELETE)
• Path + summary from the OpenAPI catalog
• Ready-to-paste curl example with the auth header pre-filled (JWT placeholder)

Populated automatically from the workbench container's /openapi.json — no manual catalog registration.

---

The mode-agnostic surface

---

Sample workbench

fathym-deno/api-workbench — public reference implementation. Two tools with one method each, wired into .Modes({ API: APIMode() }). The README.md walks through the local run, deploy via OpenX, and every route with a working curl example.

Mirror it for your own workbenches — same 3-file layout, swap in your own tools.

---

Auth + governance

Every request through the proxy is governed:

• Authentication — Bearer JWT required on every request.
• Authorization — the caller must hold the Workspace.Workbench.Host access right.
• Audit — every proxied call is logged with caller, workbench APISlug, method, path, and timestamp.
• Isolation — the API container runs alongside (and isolated from) any other enabled mode containers for the same workbench. Per-mode-per-route rights are a future track; today, holding Workspace.Workbench.Host grants access to every enabled route on every API-mode workbench.

---

Troubleshooting

Issue	Solution
Client can't connect	Check the URL — the mode segment (/API) is case-sensitive and matches the workbench's declared mode key verbatim.
401 Unauthorized	JWT expired or missing the Workspace.Workbench.Host right. Refresh the token and confirm your access rights.
404 on a route you expect	The workbench author's tool + method names determine the path. POST /hello/greet requires .Tools({ Hello: ... }) with a Greet method. Fetch /openapi.json to see what's actually exposed.
Empty /openapi.json catalog	The workbench container may still be deploying; the catalog is fetched by the SOP post-deploy and can lag on cold starts. Redeploy or wait a minute; the API Explorer card will refresh on the next Stats cycle.
503 on first request	Container cold-start. First call takes 5–15s; subsequent calls are fast. Set minReplicas: 1 on the workbench Hosting tab for always-on.
Method arguments not landing correctly	The workbench's Zod input schema defines the shape. Single object argument → send { field: value, ... } directly. Multiple positional arguments → send { arg0: ..., arg1: ..., ... }. Check the workbench source or the OpenAPI catalog's requestBody.

---

Next steps

If you want to...	Go to...
Install another workbench	Install a workbench from source →
Connect Claude, Cursor, or ChatGPT to a hosted workbench MCP	MCP access →
Understand the mode model	Workbenches overview →
See the surrounding workspace REST API	REST API reference →