Molecule AI
API Reference

Workspaces API

Workspace CRUD, lifecycle, budget, configuration, files, activity, and session search endpoints.

Workspaces

Core workspace CRUD and lifecycle operations.

CRUD

MethodPathAuthDescription
POST/workspacesAdminAuthCreate 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/workspacesAdminAuthList all workspaces with status, runtime, agent card, position, and hierarchy info.
GET/workspaces/:idWorkspaceAuthGet a single workspace by ID.
PATCH/workspaces/:idWorkspaceAuthUpdate 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 (`[]
DELETE/workspaces/:idAdminAuthDelete a workspace. Stops the container, revokes all auth tokens, and removes all associated data.

Lifecycle

MethodPathAuthDescription
POST/workspaces/:id/restartWorkspaceAuthRestart the workspace container. Sends a restart_context A2A message after successful re-registration.
POST/workspaces/:id/pauseWorkspaceAuthStop the container and set status to paused. Paused workspaces skip health sweep, liveness monitor, and auto-restart. Resume manually via /resume.
POST/workspaces/:id/resumeWorkspaceAuthRe-provision a paused workspace. Status transitions to provisioning.
POST/workspaces/:id/hibernateWorkspaceAuthImmediately hibernate a workspace (stop container, set status to hibernated). Useful for manual cost control. See hibernation note below.

Workspace hibernation

A workspace with hibernation_idle_minutes set in its config will be automatically hibernated by the platform after that many idle minutes (no active tasks, no recent heartbeat). The monitor checks every 2 minutes.

hibernated differs from paused:

  • paused — manual, resumes only via POST /resume.
  • hibernated — automatic (or via POST /hibernate), resumes automatically when an A2A message arrives.

When a message is sent to a hibernated workspace, the platform returns:

HTTP 503  Retry-After: 15
{"waking": true}

Callers should retry after ~15 seconds. The workspace typically returns to online within that window.

To opt a workspace into auto-hibernation, add to its config.yaml:

hibernation_idle_minutes: 30   # hibernate after 30 min idle; null (default) = disabled

Atomic hibernation guarantee: The platform uses a single atomic SQL claim (UPDATE … WHERE active_tasks = 0) before stopping the container. If a task arrives between the idle check and the container stop, the claim fails and hibernation is aborted — no in-flight tasks are silently lost.

Budget

MethodPathAuthDescription
GET/workspaces/:id/budgetAdminAuthRead a workspace's current spend and ceiling. Returns budget_limit, monthly_spend, and budget_remaining (all in USD cents).
PATCH/workspaces/:id/budgetAdminAuthSet or clear a workspace's monthly spend ceiling. Body: { "budget_limit": N } (positive integer, USD cents) or { "budget_limit": null } to remove the cap. Negative values → 400. Returns same shape as GET.

Request / response shape:

// PATCH request body
{ "budget_limit": 500 }   // $5.00/month ceiling
{ "budget_limit": null }  // no ceiling

// GET and PATCH success response (200)
{
  "budget_limit":     500,   // null when no ceiling
  "monthly_spend":    312,   // accumulated spend this period, USD cents
  "budget_remaining": 188    // null when no ceiling; max(0, limit-spend) — can be negative
}

budget_limit and monthly_spend are absent from GET /workspaces/:id

Financial fields are stripped unconditionally from the workspace detail response — they do not appear for any caller, authenticated or not. Always use GET /workspaces/:id/budget (AdminAuth) to read spend data.

budget_limit is also not accepted on the general PATCH /workspaces/:id endpoint. Use the dedicated /budget route.

Enforcement and fail-open behaviour

When monthly_spend >= budget_limit, POST /workspaces/:id/a2a returns:

HTTP 402 Payment Required
{"error": "workspace budget limit exceeded"}

Channel sends (Slack, Telegram, Discord, Lark) are also budget-gated with the same 402 response. The workspace itself is not paused — it keeps running; only inbound A2A and channel traffic is blocked.

Fail-open: if the budget check encounters a DB error, traffic is allowed through rather than blocked. The spend ceiling is a soft guardrail, not a hard guarantee.

Configuration

MethodPathAuthDescription
GET/workspaces/:id/configWorkspaceAuthGet the workspace's config.yaml contents.
PATCH/workspaces/:id/configWorkspaceAuthUpdate the workspace config. "Save & Restart" writes config and auto-restarts; "Save" writes only and shows a restart banner in the Canvas.
GET/workspaces/:id/modelWorkspaceAuthGet the workspace's current model selection.
PUT/workspaces/:id/modelWorkspaceAuthSet the workspace model (e.g. anthropic:claude-sonnet-4-6).
GET/workspaces/:id/providerWorkspaceAuthGet the resolved LLM provider for the workspace's runtime + model.
PUT/workspaces/:id/providerWorkspaceAuthOverride the LLM provider for the workspace.

Files

Workspace file management. Files are stored in the workspace's config directory.

MethodPathAuthDescription
GET/workspaces/:id/filesWorkspaceAuthList files in the workspace config directory.
GET/workspaces/:id/files/*pathWorkspaceAuthRead a specific file.
PUT/workspaces/:id/files/*pathWorkspaceAuthWrite a file. Creates parent directories as needed. On SaaS workspaces (EC2, no Docker), routes via EC2 Instance Connect endpoint using an ephemeral SSH key pair — the key is scoped to the file-write operation and deleted within 30 seconds. Max payload ~10 MiB. Self-hosted Docker workspaces write via docker cp as before.
DELETE/workspaces/:id/files/*pathWorkspaceAuthDelete a file.

Activity

Activity logging and search for A2A communications, task updates, and agent logs.

MethodPathAuthDescription
GET/workspaces/:id/activityWorkspaceAuthList activity logs for a workspace. Supports ?source=canvas or ?source=agent filter, and ?type=delegation for A2A topology overlay polling.
POST/workspaces/:id/activityWorkspaceAuthLog an activity entry (used by workspace runtimes to self-report).
POST/workspaces/:id/notifyWorkspaceAuthAgent-to-user push message via WebSocket. Delivers a notification to connected Canvas clients.
MethodPathAuthDescription
GET/workspaces/:id/session-searchWorkspaceAuthSearch activity logs with filters for type, date range, and text content. Returns paginated results.

API Reference

Complete reference for all Molecule AI Platform HTTP and WebSocket endpoints.

Communication API

Agent registry, discovery, A2A proxy, and delegation endpoints.

On this page

WorkspacesCRUDLifecycleBudgetConfigurationFilesActivitySession Search