research: Colab REST API (v1beta runtimes/operations) as a control-plane adapter #12

Open
opened 2026-11-11 22:56:16 +00:00 by dsh · 0 comments
Owner

Google documents the Colab API as a REST service as well as an MCP server:
https://developers.google.com/colab/api/reference/rest

Discovery documents: https://colaboratory.googleapis.com/$discovery/rest?version=v1beta (and v1), plus OpenAPI 3.0.

Surface (v1beta)

  • GET/POST /v1beta/runtimes, GET/DELETE /v1beta/runtimes/{name}
  • GET /v1beta/runtimespecs (machine shapes + eligibility)
  • GET /v1beta/{name=subscription}
  • long-running operations: GET /v1/operations, GET /v1/operations/{name}:wait

Same control plane the MCP server wraps. Unlike MCP it is a plain HTTP API with a stable discovery document; no MCP handshake, no OAuth-MCP setup. Unlike the CLI it still has no file transfer, no Drive mount, no attached exec / idle guard, so it cannot replace the run path.

Why note it

  1. A fallback control-plane client (same Google credential, plain fetch) for list_runtimes, runtimespecs, get_subscription if MCP auth is awkward on a host.
  2. A likely home for orphan cleanup/reconciliation in colab_fanout (v1): list runtimes, match scheduler-owned tags, delete leftovers.

Evaluation

  • Reuse the MCP spike's live checklist; add: can a runtime created via REST be seen/attached by the CLI, and vice versa?
  • Does REST expose anything for kernel sessions/execution, or only runtimes + operations?
  • Auth: same OAuth/ADC story as MCP?

Findings go into the new "Related: the Colab REST API" section of docs/mcp-spike.md; roadmap has a later-ideas row.

Google documents the Colab API as a REST service as well as an MCP server: <https://developers.google.com/colab/api/reference/rest> Discovery documents: `https://colaboratory.googleapis.com/$discovery/rest?version=v1beta` (and `v1`), plus OpenAPI 3.0. ## Surface (v1beta) - `GET/POST /v1beta/runtimes`, `GET/DELETE /v1beta/runtimes/{name}` - `GET /v1beta/runtimespecs` (machine shapes + eligibility) - `GET /v1beta/{name=subscription}` - long-running operations: `GET /v1/operations`, `GET /v1/operations/{name}:wait` Same control plane the MCP server wraps. Unlike MCP it is a plain HTTP API with a stable discovery document; no MCP handshake, no OAuth-MCP setup. Unlike the CLI it still has **no file transfer, no Drive mount, no attached exec / idle guard**, so it cannot replace the run path. ## Why note it 1. A fallback control-plane client (same Google credential, plain `fetch`) for `list_runtimes`, `runtimespecs`, `get_subscription` if MCP auth is awkward on a host. 2. A likely home for orphan cleanup/reconciliation in `colab_fanout` (v1): list runtimes, match scheduler-owned tags, delete leftovers. ## Evaluation - Reuse the MCP spike's live checklist; add: can a runtime created via REST be seen/attached by the CLI, and vice versa? - Does REST expose anything for kernel sessions/execution, or only runtimes + operations? - Auth: same OAuth/ADC story as MCP? Findings go into the new "Related: the Colab REST API" section of `docs/mcp-spike.md`; roadmap has a later-ideas row.
Sign in to join this conversation.
No description provided.