From 5b0190a7880b49d256a1d66f2c2b71802009cd2e Mon Sep 17 00:00:00 2001 From: "molecule-ai[bot]" <276602405+molecule-ai[bot]@users.noreply.github.com> Date: Fri, 17 Apr 2026 12:44:10 +0000 Subject: [PATCH] docs(api-ref): auth + validation breaking changes from PR #701 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates content/docs/api-reference.mdx: - Add breaking-changes Callout (PATCH auth, templates AdminAuth, UUID validation) - PATCH /workspaces/:id: remove old field-level authz caveat; add full validation constraints (name ≤255, role ≤1000, model/runtime ≤100, no newlines/YAML-special) - GET /templates: None → AdminAuth - GET /org/templates: None → AdminAuth Source PR: Molecule-AI/molecule-core#701 Co-Authored-By: Claude Sonnet 4.6 --- content/docs/api-reference.mdx | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/content/docs/api-reference.mdx b/content/docs/api-reference.mdx index b0f0909..adde987 100644 --- a/content/docs/api-reference.mdx +++ b/content/docs/api-reference.mdx @@ -7,6 +7,16 @@ description: Complete reference for all Molecule AI Platform HTTP and WebSocket The Molecule AI Platform exposes a REST API (default port 8080) for workspace management, agent registry, communication, and administration. All endpoints return JSON unless otherwise noted. + + **Breaking changes — PR #701 (2026-04-17)** + + - **`PATCH /workspaces/:id` now requires authentication.** Previously, requests without a bearer token could update cosmetic fields (name, x/y position). All `PATCH` calls now require `Authorization: Bearer ` or receive **401 Unauthorized**. + - **`GET /templates` and `GET /org/templates` now require AdminAuth.** Unauthenticated callers receive **401 Unauthorized**. + - **All `/workspaces/:id` endpoints validate the `:id` path parameter** as a UUID. Non-UUID values return **400 Bad Request** before any database interaction. + + **Migration:** add `Authorization: Bearer ` to all `PATCH /workspaces/:id` calls. Use an admin bearer token for `GET /templates` and `GET /org/templates`. Ensure `:id` values in automation scripts are valid UUIDs. + + **Base URL:** `http://localhost:8080` (self-hosted) or `https://api.moleculesai.app` (SaaS) --- @@ -62,7 +72,7 @@ Core workspace CRUD and lifecycle operations. | POST | `/workspaces` | AdminAuth | Create a new workspace. Accepts `name`, `runtime`, `template`, `parent_id`, `tier`, `workspace_dir`, and other fields. Runtime is auto-detected from template config if omitted (defaults to `langgraph`). | | GET | `/workspaces` | AdminAuth | List all workspaces with status, runtime, agent card, position, and hierarchy info. | | GET | `/workspaces/:id` | WorkspaceAuth | Get a single workspace by ID. | -| PATCH | `/workspaces/:id` | WorkspaceAuth | Update workspace fields. **Field-level authz:** cosmetic fields (name, role, x, y, canvas) pass through; sensitive fields (tier, parent_id, runtime, workspace_dir) require a valid bearer token when any live token exists. | +| PATCH | `/workspaces/:id` | WorkspaceAuth | Update workspace fields. A workspace bearer token is always required — unauthenticated calls return 401. Validates field constraints: `name` ≤ 255 chars, `role` ≤ 1,000 chars, `model` and `runtime` ≤ 100 chars each; `name` and `role` must not contain newlines (`\\n`, `\\r`) or YAML-special characters (`{}[]|>*&!`). Oversized or invalid field values return 400. `:id` must be a valid UUID. | | DELETE | `/workspaces/:id` | AdminAuth | Delete a workspace. Stops the container, revokes all auth tokens, and removes all associated data. | ### Lifecycle @@ -302,14 +312,14 @@ Expand and collapse team views in the Canvas hierarchy. | Method | Path | Auth | Description | |--------|------|------|-------------| -| GET | `/templates` | None | List available workspace templates with their runtime, description, and config schema. | +| GET | `/templates` | AdminAuth | List available workspace templates with their runtime, description, and config schema. | | POST | `/templates/import` | AdminAuth | Import a workspace template from a `github://` source URL. | ### Org Templates | Method | Path | Auth | Description | |--------|------|------|-------------| -| GET | `/org/templates` | None | List available organization templates. | +| GET | `/org/templates` | AdminAuth | List available organization templates. | | POST | `/org/import` | AdminAuth | Import an org template. Applies `resolveInsideRoot` path sanitization. Creates the full workspace hierarchy defined in `org.yaml`. | ### Bundles