API de Laboratorios (Frida)

Ruta base: /workbenches/v1. Autenticación con la sesión o token de Studio; toda operación está limitada al Cliente activo. En la API el laboratorio se llama workbench.

Operaciones

Método y ruta	Descripción
`GET /workbenches/v1/plan`	Tallas disponibles para el Cliente (`sizes` con `cpu`, `memory`, `storage`, `gpumemMiB` y `gpus`), talla por defecto (`defaultSize`) y máximos por recurso (`ceiling`, incluido `gpus`).
`GET /workbenches/v1`	Lista de laboratorios. Filtro `ownership`: `mine`, `shared`, `all`.
`POST /workbenches/v1`	Crear. Cuerpo: `name` y `size` (nombre de talla) o `resources` (`cpu`, `memory`, `gpumem`, `storage`, `gpus`). `gpumem` es por tarjeta; `gpus` se omite en un laboratorio sin GPU.
`GET /workbenches/v1/{id}`	Detalle: `status`, `spec` (talla y recursos resueltos), `usage` (consumo por recurso), `dashboardUrl`, `rejectionEvents` (últimos rechazos de admisión con la fecha en que se vieron por última vez) y `access` (dueño y editores). Devuelve la cabecera `ETag`, que necesitas para redimensionar.
`PATCH /workbenches/v1/{id}`	Redimensionar. Solo el propietario. Cuerpo: `size` o `resources` completo (nunca parcial) y, opcionalmente, `stopRunningWorkloads: true` como consentimiento para detener los notebooks que estorben. Cabecera `If-Match` obligatoria con el `ETag` del `GET`. Ver Redimensionar.
`DELETE /workbenches/v1/{id}`	Eliminar. Solo el dueño, en estado `ready` o `failed`.
`GET`, `POST`, `DELETE /workbenches/v1/{id}/members`	Listar, agregar (`userId`, `role: editor`) y quitar editores.

Ejemplo: crear con una talla

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 se rellena cuando status pasa a ready; es la misma URL que abre el botón Abrir en Studio. Consulta el detalle cada 10 a 15 segundos hasta entonces; no antes.

Un rechazo por política llega como 422 con el recurso y el límite:

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

Redimensionar

La regla de admisión es uso ≤ destino en cada eje, medida contra lo que corre en ese momento. La dirección del cambio no importa: un cambio mixto (más CPU, menos memoria) puede exigir detener aunque parezca una subida.

# 1) leer el estado y quedarse con el ETag
curl -si "https://api.<tu-dominio>/workbenches/v1/wb_3wzamf964waf5t0cjzmqmrsdb" \
  -H "Authorization: Bearer <token>" | grep -i etag

# 2) pedir la talla nueva; If-Match evita pisar un cambio concurrente
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"}'

Respuesta	Qué pasó
`200`	El destino es igual al actual: no se tocó nada.
`202`	Aceptado. El laboratorio pasa a `status: resizing` y vuelve a `ready` cuando la cuota converge; consulta el detalle cada pocos segundos. El cuerpo puede traer `notices`, hoy solo uno: el disco pedido era menor que el actual y se conservó.
`409 LAB_RESIZE_REQUIRES_STOP`	No cabe contra el uso vivo. El mensaje nombra el eje y `details` lo que está corriendo (notebook y dueño). Repite con `stopRunningWorkloads: true` para que Frida detenga esos notebooks y aplique. Si detenerlos tampoco bastaría (el presupuesto lo ocupa una ejecución de pipeline u otra pieza que Frida no detiene), el mensaje lo dice y no ofrece esa salida.
`409 LAB_CAPACITY_UNAVAILABLE`	La subida cabe en el plan, pero no hay capacidad en la instalación ahora. Bajar nunca consulta capacidad.
`409 LAB_RESIZE_NOT_READY`	El laboratorio está en `pending` o `deleting`: no hay uso que medir. Espera a `ready`.
`409 LAB_RESIZE_STOP_TIMED_OUT`	Consentiste, los notebooks se detuvieron, pero el uso no bajó a tiempo. No se aplicó nada: el laboratorio conserva la cuota anterior con los notebooks detenidos. Reintenta; la segunda vez entra en caliente.
`412 LAB_RESIZE_STALE_VERSION`	El `If-Match` no coincide: el laboratorio cambió desde que lo leíste. Vuelve a leerlo y repite.
`422 LAB_CEILING_EXCEEDED`	Un eje supera el techo del plan; `details` trae eje, pedido y límite.

Dos garantías del orden de operaciones: Frida detiene antes de aplicar, así que un fallo a medio camino deja el laboratorio con su cuota anterior y relanzable, nunca con menos presupuesto del que usa; y Frida solo detiene notebooks, nunca ejecuciones de pipelines ni piezas de la plataforma, y no relanza nada por su cuenta.

El disco es un trinquete también por API: un resources.storage menor que el actual no falla, se conserva el valor vigente, llega el notices, y el laboratorio deja de tener spec.size (pasa a resources explícitos).

Cantidades

Los recursos usan la notación de Kubernetes: cpu en núcleos (4) o milinúcleos (500m); memory y storage con sufijo binario (16Gi); gpumem en MiB sin sufijo (24576) o con sufijo (24Gi).

Estados

pending, provisioning, ready, resizing, failed, deleting, deleted, not_installed. resizing no es un estado guardado: se deriva de comparar la cuota pedida con la viva, y desaparece solo cuando coinciden.

Errores

HTTP	Cuándo
400	`LAB_INVALID_RESOURCES`: cantidad mal formada, o talla y recursos enviados a la vez.
403	No eres dueño (eliminar, compartir).
404	No existe o pertenece a otro Cliente.
409	Ya existe un laboratorio con ese nombre, o hay una eliminación en curso. Al redimensionar: `LAB_RESIZE_REQUIRES_STOP`, `LAB_CAPACITY_UNAVAILABLE`, `LAB_RESIZE_NOT_READY`, `LAB_RESIZE_STOP_TIMED_OUT` (ver Redimensionar).
412	`LAB_RESIZE_STALE_VERSION`: el `If-Match` no coincide con el `ETag` actual.
422	`LAB_POLICY_UNAVAILABLE`: la talla no existe en el plan o un recurso supera el máximo (`details` trae `dimension`, `requested` y `limit`). `LAB_CAPACITY_UNAVAILABLE`: no hay capacidad ahora (al crear; al redimensionar es `409`). `LAB_CEILING_EXCEEDED`: al redimensionar con `resources`, un eje supera el techo del plan.
403 / 404 (miembros)	`LAB_MEMBER_NOT_IN_ORGANIZATION`, `LAB_MEMBER_IS_OWNER`, `LAB_INVALID_ROLE` al compartir con alguien fuera del Cliente, con el propio dueño o con un rol distinto de `editor`.

Operaciones​

Ejemplo: crear con una talla​

Redimensionar​

Cantidades​

Estados​

Errores​