Labs API (Frida)

Base path: /workbenches/v1. Authentication with the Studio session or token; every operation is limited to the active Client. In the API, the lab is called workbench.

Operations

Method and path	Description
`GET /workbenches/v1/plan`	Sizes available for the Client (`sizes` with `cpu`, `memory`, `storage`, `gpumemMiB` and `gpus`), default size (`defaultSize`) and maximums per resource (`ceiling`, including `gpus`).
`GET /workbenches/v1`	List of labs. `ownership` filter: `mine`, `shared`, `all`.
`POST /workbenches/v1`	Create. Body: `name` and `size` (size name) or `resources` (`cpu`, `memory`, `gpumem`, `storage`, `gpus`). `gpumem` is per card; `gpus` is omitted for a lab without GPU.
`GET /workbenches/v1/{id}`	Detail: `status`, `spec` (resolved size and resources), `usage` (consumption per resource), `dashboardUrl`, `rejectionEvents` (latest admission rejections with the date they were last seen) and `access` (owner and editors). Returns the `ETag` header, which you need to resize.
`PATCH /workbenches/v1/{id}`	Resize. Owner only. Body: `size` or complete `resources` (never partial) and, optionally, `stopRunningWorkloads: true` as consent to stop the notebooks that get in the way. `If-Match` header required, with the `ETag` from the `GET`. See Resize.
`DELETE /workbenches/v1/{id}`	Delete. Owner only, in the `ready` or `failed` state.
`GET`, `POST`, `DELETE /workbenches/v1/{id}/members`	List, add (`userId`, `role: editor`) and remove editors.

Example: create with a size

curl -X POST "https://api.<tu-dominio>/workbenches/v1" \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name": "prediccion-fugas", "size": "M"}'

{
  "id": "wb_3wzamf964waf5t0cjzmqmrsdb",
  "name": "prediccion-fugas",
  "status": "pending",
  "spec": { "size": "M", "cpu": "5", "memory": "18Gi", "gpumem": "12288", "storage": "50Gi" },
  "dashboardUrl": null,
  "access": { "owner": "usr_...", "editors": [] }
}

dashboardUrl is filled in when status changes to ready; it is the same URL that the Abrir (Open) button opens in Studio. Query the detail every 10 to 15 seconds until then; not more often.

A policy rejection arrives as 422 with the resource and the limit:

{
  "error": {
    "code": "LAB_POLICY_UNAVAILABLE",
    "message": "gpumem 32768 exceeds the plan ceiling of 24576",
    "details": { "dimension": "gpumem", "requested": "32768", "limit": "24576" }
  }
}

Resize

The admission rule is uso ≤ destino (usage ≤ target) on each axis, measured against what is running at that moment. The direction of the change does not matter: a mixed change (more CPU, less memory) can require stopping even if it looks like an increase.

# 1) read the state and keep the ETag
curl -si "https://api.<tu-dominio>/workbenches/v1/wb_3wzamf964waf5t0cjzmqmrsdb" \
  -H "Authorization: Bearer <token>" | grep -i etag

# 2) request the new size; If-Match avoids overwriting a concurrent change
curl -X PATCH "https://api.<tu-dominio>/workbenches/v1/wb_3wzamf964waf5t0cjzmqmrsdb" \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -H 'If-Match: "1234567"' \
  -d '{"size": "M"}'

Response	What happened
`200`	The target is the same as the current one: nothing was touched.
`202`	Accepted. The lab changes to `status: resizing` and returns to `ready` when the quota converges; query the detail every few seconds. The body can include `notices`, currently only one: the requested disk was smaller than the current one and the current one was kept.
`409 LAB_RESIZE_REQUIRES_STOP`	It does not fit against the live usage. The message names the axis, and `details` names what is running (notebook and owner). Repeat with `stopRunningWorkloads: true` so that Frida stops those notebooks and applies the change. If stopping them would not be enough either (the budget is taken by a pipeline run or another piece that Frida does not stop), the message says so and does not offer that way out.
`409 LAB_CAPACITY_UNAVAILABLE`	The increase fits in the plan, but there is no capacity in the installation right now. A decrease never checks capacity.
`409 LAB_RESIZE_NOT_READY`	The lab is in `pending` or `deleting`: there is no usage to measure. Wait for `ready`.
`409 LAB_RESIZE_STOP_TIMED_OUT`	You consented and the notebooks stopped, but the usage did not drop in time. Nothing was applied: the lab keeps its previous quota with the notebooks stopped. Retry; the second time it applies live.
`412 LAB_RESIZE_STALE_VERSION`	The `If-Match` does not match: the lab changed since you read it. Read it again and repeat.
`422 LAB_CEILING_EXCEEDED`	An axis exceeds the plan ceiling; `details` includes the axis, the request and the limit.

Two guarantees about the order of operations: Frida stops before applying, so a failure halfway through leaves the lab with its previous quota and ready to relaunch, never with less budget than it uses; and Frida only stops notebooks, never pipeline runs or platform pieces, and does not relaunch anything on its own.

The disk is a ratchet through the API too: a resources.storage smaller than the current one does not fail, the current value is kept, the notices arrives, and the lab no longer has spec.size (it switches to explicit resources).

Quantities

Resources use Kubernetes notation: cpu in cores (4) or millicores (500m); memory and storage with a binary suffix (16Gi); gpumem in MiB without a suffix (24576) or with a suffix (24Gi).

Statuses

pending, provisioning, ready, resizing, failed, deleting, deleted, not_installed. resizing is not a stored status: it is derived by comparing the requested quota with the live one, and it disappears only when they match.

Errors

HTTP	When
400	`LAB_INVALID_RESOURCES`: malformed quantity, or size and resources sent together.
403	You are not the owner (delete, share).
404	It does not exist or belongs to another Client.
409	A lab with that name already exists, or a deletion is in progress. When resizing: `LAB_RESIZE_REQUIRES_STOP`, `LAB_CAPACITY_UNAVAILABLE`, `LAB_RESIZE_NOT_READY`, `LAB_RESIZE_STOP_TIMED_OUT` (see Resize).
412	`LAB_RESIZE_STALE_VERSION`: the `If-Match` does not match the current `ETag`.
422	`LAB_POLICY_UNAVAILABLE`: the size does not exist in the plan or a resource exceeds the maximum (`details` includes `dimension`, `requested` and `limit`). `LAB_CAPACITY_UNAVAILABLE`: there is no capacity right now (when creating; when resizing it is `409`). `LAB_CEILING_EXCEEDED`: when resizing with `resources`, an axis exceeds the plan ceiling.
403 / 404 (members)	`LAB_MEMBER_NOT_IN_ORGANIZATION`, `LAB_MEMBER_IS_OWNER`, `LAB_INVALID_ROLE` when sharing with someone outside the Client, with the owner themselves or with a role other than `editor`.

Operations​

Example: create with a size​

Resize​

Quantities​

Statuses​

Errors​